built-ins

Built-in Commands

init

Scaffold a minimal Balda project.

npx balda init -p ./src -t true

Flags:

• -p, --path <string>: target directory (default ./src)
• -t, --typescript <boolean>: generate TS files (default true)

list

List registered commands with descriptions. Commands are organized by category for better readability.

npx balda list

Example output:

✨ Available Balda Commands:

User Commands:

  GENERATOR:
    generate-controller    Generate a new controller in the specified path
    generate-middleware    Generate a new middleware in the specified path

Built-in Commands:

  init                    Initialize a new balda project in the current directory
  list                    List all available commands
  generate-command        Generate a new command in the specified path
  generate-plugin         Generate a new plugin in the specified path
  generate-cron           Generate a new cron job in the specified path
  generate-queue          Generate a new queue in the specified path
  generate-controller     Generate a new controller in the specified path
  generate-middleware     Generate a new middleware in the specified path
  build                   Build the project for production (Node.js only)

Commands marked with [deprecated] are still available but will be removed in future versions.

serve

Run the server in development mode with hot reload. The command automatically detects your runtime (Bun, Deno, or Node.js) and uses the appropriate hot reload mechanism.

npx balda serve -e ./src/index.ts

Flags:

• -e, --entry, -s <string>: Entry point of the project (default ./src/index.ts)
• -d, --deno-import-map <string>: Path to Deno import map (Deno only)

Runtime-specific behavior:

• Bun: Uses native bun run --watch for hot reload
• Deno: Uses native deno run --watch with --unstable-sloppy-imports and --allow-all permissions
• Node.js: Uses tsx for hot reload (automatically installs if not found)

Requirements:

• For Node.js, tsx will be automatically installed as a dev dependency if not detected
• This command should be run from the root of your project

Example with custom entry point:

npx balda serve --entry ./src/server.ts

#### generate-command

Generate a new custom CLI command. This creates a command class template that you can customize.

```bash
npx balda generate-command hello -p src/commands

Generated file: src/commands/hello.ts

Flags:

• -p, --path <string>: Target directory (default src/commands)

Important: Command names must be unique. The generator will prevent you from creating a command that conflicts with existing built-in or user-defined commands.

Example generated code:

import { Command, CommandOptions } from "balda-js";

export default class extends Command {
  static commandName = "hello";
  static description = "Command description";

  static options: CommandOptions = {
    // Define your command options here
    keepAlive: false,
  };

  static async handle(): Promise<void> {
    // Implement your command logic here
  }
}

generate-plugin

Generate a new plugin to extend Balda's functionality.

npx balda generate-plugin auth -p src/plugins/security

Generated file: src/plugins/security/auth.ts

Flags:

• -p, --path <string>: Target directory (default src/plugins)

generate-cron

Generate a new cron job for scheduled tasks.

npx balda generate-cron clean-sessions -p src/maintenance/cron

Generated file: src/maintenance/cron/clean-sessions.ts

Flags:

• -p, --path <string>: Target directory (default src/cron)

generate-queue

Generate a new queue worker for background job processing.

npx balda generate-queue user-signup -p src/queues --provider bullmq

Generated file: src/queues/user-signup.ts

Flags:

• -p, --path <string>: Target directory (default src/queues)
• --provider <string>: Queue provider (bullmq, pgboss, sqs, or custom)

generate-controller

Generate a new controller with RESTful route handlers. Controllers are classes that handle HTTP requests and define API endpoints using decorators.

npx balda generate-controller user -p src/controllers

Generated file: src/controllers/user.ts

The generated controller includes:

• RESTful route handlers (index, show, create, update, destroy)
• Route decorators (@get, @post, @put, @del)
• Proper URL structure based on the controller name

Flags:

• -p, --path <string>: Target directory (default src/controllers)

Example generated code:

import { controller, get, post, put, del, Request, Response } from "balda-js";

@controller("/user")
export default class UserController {
  @get("/")
  async index(req: Request, res: Response) {
    return { message: "List all users" };
  }

  @get("/:id")
  async show(req: Request, res: Response) {
    return { message: `Get user with id ${req.params.id}` };
  }

  @post("/")
  async create(req: Request, res: Response) {
    return { message: "Create user", data: req.body };
  }

  @put("/:id")
  async update(req: Request, res: Response) {
    return { message: `Update user with id ${req.params.id}`, data: req.body };
  }

  @del("/:id")
  async destroy(req: Request, res: Response) {
    return { message: `Delete user with id ${req.params.id}` };
  }
}

generate-middleware

Generate a new middleware function. Middlewares can be used to process requests before they reach your route handlers.

npx balda generate-middleware auth -p src/middlewares

Generated file: src/middlewares/auth.ts

Flags:

• -p, --path <string>: Target directory (default src/middlewares)

Example generated code:

import type {
  Request,
  Response,
  NextFunction,
  ServerRouteMiddleware,
} from "balda-js";

/**
 * Auth middleware
 * @description Add your middleware logic here
 */
export const Auth: ServerRouteMiddleware = async () => {
  return async (req: Request, res: Response, next: NextFunction) => {
    // Add your middleware logic here
    return next();
  };
};

Usage with controllers:

import { controller, get, middleware } from "balda-js";
import { Auth } from "./middlewares/auth";

@controller("/protected")
@middleware(Auth)
export default class ProtectedController {
  @get("/data")
  async getData(req: Request, res: Response) {
    return { message: "Protected data" };
  }
}

build

Build the project for production (Node.js only). Creates an optimized production bundle with optional asset copying.

npx balda build -t ./tsconfig.json -a ./assets

Flags:

• -c, --clear-dist <boolean>: Clear the dist directory before building (default false)
• -e, --entry <string>: Entry point of the project (default ./src/index.ts)
• -o, --output <string>: Output directory path (default ./dist)
• -t, --tsconfig <string>: Path to tsconfig.json file (default ./tsconfig.json)
• -a, --assets <string>: Path to assets directory to copy to output
• -f, --format <string>: Build format: esm or cjs (default esm)
• -p, --packages <string>: Package bundling: bundle or external (default external)
• -s, --sourcemap <boolean>: Generate sourcemaps (default true)

Requirements:

• Must have esbuild installed: npm install -D esbuild
• For asset copying, must have esbuild-plugin-copy installed: npm install -D esbuild-plugin-copy

Example with all options:

npx balda build \
  --entry ./src/server.ts \
  --output ./dist \
  --tsconfig ./tsconfig.json \
  --assets ./public \
  --format esm \
  --packages external \
  --sourcemap true \
  --clear-dist

Build output:

• Main file: ./dist/server.js
• Assets (if specified): ./dist/assets/*
• Source maps (if enabled): ./dist/server.js.map