Skip to main content

Development Guide

This guide covers development workflows for building Balda applications with hot reload support across different JavaScript runtimes.

Hot Reload Development​

Hot reload allows your server to automatically restart when you make changes to your code, significantly speeding up the development process.

The easiest way to run your Balda server in development mode is using the built-in serve command:

npx balda serve

This command automatically:

  • Detects your runtime (Node.js, Bun, or Deno)
  • Uses the appropriate hot reload mechanism for your runtime
  • Installs required dependencies if needed (like tsx for Node.js)
  • Watches for file changes and restarts your server automatically

Custom entry point:

npx balda serve ./src/server.ts

With flags:

npx balda serve --deno-import-map ./import_map.json

The serve command uses:

  • Node.js: tsx with watch mode (automatically installed if missing)
  • Bun: bun run --watch
  • Deno: deno run --watch with required permissions
tip

The npx balda serve command is the recommended way to run your development server as it handles all runtime-specific configuration automatically.

Manual Setup (Alternative)​

If you prefer to set up hot reload manually or need more control over the configuration, you can use the runtime-specific tools directly:

Node.js​

For Node.js projects, you can use several tools for hot reloading:

tsx is a fast TypeScript execution environment with watch mode.

Installation:

npm install -D tsx

Usage:

tsx watch src/index.ts

Package.json script:

{
  "scripts": {
    "dev": "tsx watch src/index.ts"
  }
}

Then run:

npm run dev

Using ts-node-dev​

ts-node-dev is another popular option with fast recompilation.

Installation:

npm install -D ts-node-dev

Usage:

ts-node-dev --respawn --transpile-only src/index.ts

Package.json script:

{
  "scripts": {
    "dev": "ts-node-dev --respawn --transpile-only src/index.ts"
  }
}

Bun​

Bun has built-in watch mode support with excellent performance.

Usage:

bun run --watch src/index.ts

Package.json script:

{
  "scripts": {
    "dev": "bun run --watch src/index.ts"
  }
}

Then run:

bun run dev

Deno​

Deno provides built-in watch mode with the --watch flag.

Usage:

deno run --allow-net --allow-read --watch src/index.ts

deno.json script:

{
  "tasks": {
    "dev": "deno run --allow-net --allow-read --watch src/index.ts"
  }
}

Then run:

deno task dev