Getting Started with Vespa: Node.js
Welcome to Vespa by HiveOps, your next-generation database-as-a-service platform designed for speed, scalability, and simplicity. This guide walks you through creating a database stack, initializing your project, and writing your first app using Vespa.
📦 Step 1: Create a Secure App and Database Stack
Before you begin coding, you need to set up your environment through the HiveOps Console:
Create a Secure App
Navigate to the Apps page in the HiveOps Console.
Create a new Secure App and copy the Access Token, you'll need this later.
Create a Vespa Database Stack
Go to the Databases page and create a new stack.
Copy the Stack Hive Resource Number (HRN), which identifies your database.
🛠️ Step 2: Initialize the Project
Open your terminal in the root of your project directory and run:
npx @hiveops/cli@latest vespa init
You’ll be prompted to provide:
The Stack Hive Resource Number from the console.
The Access Token for your secure app.
Whether to bootstrap sample models (recommended for first-time users).
What’s Generated
Once initialization is complete, the following will be added to your project:
📄 package.json
If not already present, a package.json
file will be created and updated with these scripts:
"scripts": {
"vespa:generate": "hive vespa generate -p ts",
"vespa:apply": "hive vespa apply",
"vespa:generate-and-apply": "hive vespa generate-and-apply -p ts"
}
📦 Dependencies
@hiveops/node@latest
is added as a dependency.@hiveops/cli@latest
is added as a dev dependency.
📁 src/models.hcl
model User = {
firstName: string = 1
lastName: string = 2
email: string = 4
age: int = 5
}
model Post = {
userId: string = 1
title: string = 2
body: string = 3
}
⚙️ Step 3: Compile and Apply Models
You can now run the following commands:
npm run vespa:generate
➜ Compilesmodels.hcl
into TypeScript code undersrc/vespa
.npm run vespa:apply
➜ Applies the model schema to your Vespa database.npm run vespa:generate-and-apply
➜ Does both of the above in a single step.
Once applied, you can view and inspect your schema in the console.
🧪 Step 4: Write Your First Script
Install required dependencies:
npm install --save @faker-js/faker dotenv
Create a src/main.ts
file:
import { faker } from "@faker-js/faker";
import { configDotenv } from "dotenv";
import { postRepository, userRepository, vespaInit } from "./vespa";
configDotenv();
const start = async () => {
vespaInit();
const firstName = faker.person.firstName();
const lastName = faker.person.lastName();
const email = faker.internet.email({ firstName, lastName });
const user = await userRepository.saveOne({
firstName,
lastName,
email,
age: faker.number.int({ min: 21, max: 45 }),
});
console.log(user);
if (!user) {
console.error("User not found");
return;
}
const post = await postRepository.saveOne({
userId: user._vespa_id,
title: faker.lorem.words(3),
body: faker.lorem.paragraph(),
});
console.log(post);
const posts = await postRepository.findMany({});
console.log(posts);
};
start().catch(console.error);
Now run your script with ts-node src/main.ts
✅ You’re All Set!
You’ve now:
Created a secure Vespa database stack
Bootstrapped your project
Generated and applied a schema
Written your first data persistence script