Skip to main content

Quick Start

Build your first Balda API in 5 minutes.

1. Create a Server​

Create server.ts:

import { Server, controller, get, post } from "balda";
import { z } from "zod";

const server = new Server({ port: 3000 });

@controller("/users")
class UsersController {
  private users = [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
  ];

  @get("/")
  getAll(req, res) {
    res.json(this.users);
  }

  @get("/:id")
  getById(req, res) {
    const user = this.users.find((u) => u.id === Number(req.params.id));
    user ? res.json(user) : res.notFound({ error: "User not found" });
  }

  @post("/")
  create(req, res) {
    const user = { id: this.users.length + 1, ...req.body };
    this.users.push(user);
    res.created(user);
  }
}

server.listen(() => console.log("Server running on http://localhost:3000"));

2. Run the Server​

Using the CLI (recommended):

npx balda serve

Or run directly:

# Node.js
npx tsx server.ts

# Bun
bun server.ts

# Deno
deno run --allow-net server.ts

3. Test Your API​

# Get all users
curl http://localhost:3000/users

# Get a specific user
curl http://localhost:3000/users/1

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Charlie"}'

Add Validation​

Add request validation with Zod, TypeBox, or OpenAPI schemas:

import { validate } from "balda";
import { z } from "zod";

const CreateUserSchema = z.object({
  name: z.string().min(1),
});

@controller("/users")
class UsersController {
  @post("/")
  @validate.body(CreateUserSchema)  // Also supports validate.query()
  create(req, res, body) {
    // body is now validated and typed
    const user = { id: this.users.length + 1, ...body };
    this.users.push(user);
    res.created(user);
  }
}
info

Balda supports Zod, TypeBox (@sinclair/typebox), and OpenAPI/AJV schemas for validation and serialization.

View API Documentation​

Balda automatically generates Swagger docs at /docs:

http://localhost:3000/docs

Next Steps​