ADR-002: Bun as the Application Runtime

Status: Accepted

Context

The dashboard backend needs a JavaScript/TypeScript runtime. The main alternatives are Node.js and Bun.

Decision

Use Bun as the sole runtime — for the backend server, bundler, test runner, and package manager.

Reasons

• Native TypeScript — no ts-node, tsx, or build step for the server; Bun runs .ts files directly.
• Built-in .env loading — no dotenv dependency; Bun.env just works.
• Bundler included — replaces Vite/webpack for the frontend bundle. One tool for the whole stack.
• Fast test runner — bun:test is API-compatible with Jest and significantly faster.
• Bun.serve() — a single call replaces Express/Fastify for the HTTP server with built-in WebSocket support.

Consequences

• Never use node, npm, npx, ts-node, yarn, or dotenv anywhere in the project. All scripts, CI steps, and Dockerfiles use bun.
• Bun.file replaces fs.readFile/fs.writeFile.
• Bun.$\cmd`replacesexeca/child_process`.
• Client-side env vars must be prefixed BUN_PUBLIC_ to be inlined at bundle time.
• Bun’s ecosystem is maturing fast but occasionally lags Node.js for obscure packages. When a package doesn’t work, check the Bun compatibility tracker before reaching for a workaround.