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:

  1. 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.

  2. 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

    ➜ Compiles models.hcl into TypeScript code under src/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