bun-pro

Overview

Bun is an all-in-one JavaScript and TypeScript runtime built on JavaScriptCore that replaces Node plus npm plus your bundler plus your test runner with a single fast binary. Its headline features are near-instant installs, a native bundler, a Jest-compatible test runner, and a high-performance HTTP server API (Bun.serve). Bun also aims for broad Node.js compatibility, so most existing projects run with little or no change. This skill covers using Bun effectively, migrating from Node, and knowing where the edges still are.

When to use

• Starting a new JS/TS project where install speed and a single toolchain matter.
• Migrating a Node project to reduce toolchain complexity (one binary for runtime, bundler, tests).
• Building high-throughput HTTP services or WebSocket servers on Bun.serve.
• Speeding up CI with faster installs and test runs.
• Evaluating runtime tradeoffs between Bun, Node, and Deno.
• Bundling frontend assets without a separate webpack/vite setup.
• Writing CLIs where a single compiled binary simplifies distribution.

Core concepts

• One binary, four tools. bun run (runtime), bun install (package manager), bun build (bundler), bun test (test runner). Learn all four before reaching for webpack/vite/jest equivalents — you often do not need them.
• Node compatibility layer. Bun implements node: builtins and npm package semantics. Most pure-JS packages work; native addons and exotic node_modules layouts are where breaks happen — test before switching production.
• Bun.serve and WebSockets. The native server API handles HTTP and WebSocket upgrades with far less overhead than framework stacks:

  Bun.serve({
    port: 3000,
    fetch(req) { return new Response("hi"); },
    websocket: { message(ws, msg) { ws.send("echo: " + msg); } },
  });
  

• Built-in SQLite and FFI. bun:sqlite gives a zero-dependency embedded database; bun:ffi calls native libraries directly. Both remove whole dependency classes for small services.
• Transpiler on by default. Bun runs TypeScript, JSX/TSX, and modern syntax natively — no tsconfig wrangling for runtime behavior (though you still want tsc or an editor for type errors).
• Workspaces and lockfile. Bun supports npm-style workspaces with its own lockfile (bun.lockb, binary by default — text lockfile mode gives readable diffs). Commit it for reproducible installs.
• npm registry compatibility. bun install reads the npm registry and respects package.json semantics, so migration is usually bun install plus bun run away.
• Hot reloading. --hot watches and reloads on file changes — fast iteration in dev, never in production.
• Macros. Compile-time code execution (macro()) for codegen-like patterns without a build plugin — powerful, but keep macros simple and deterministic.
• Environment and dotenv. Bun loads .env files automatically — convenient, but ensure secrets still come from the environment in production, not committed files.

Practical workflow

1. Install and verify. Use the official install script from the Bun website, then confirm the version your team pins with bun --version.
   • Record the version in README/CI; Bun moves fast and behavior changes between minors.
2. Migrate or scaffold. In an existing Node project, run bun install (npm scripts keep working) or start fresh with bun init. Prefer the text lockfile for clean git diffs.
3. Replace the toolchain. Swap scripts to bun run, tests to bun test (Jest-style describe/it/expect mostly works), and builds to bun build ./src/index.ts --outdir=dist --target=bun.
   • Run the full test suite under both runtimes during migration; snapshot-test differences are the usual finding.
4. Build the server. Use Bun.serve for hot paths; keep framework code (Elysia, Hono) for routing structure. Put SQLite behind bun:sqlite for local-first persistence.
5. Handle WebSockets properly. Define open/message/close handlers, track connections in a Set with metadata, and implement application-level heartbeats — the same reliability rules as any socket server.

   const clients = new Set<ServerWebSocket<unknown>>();
   Bun.serve({
     fetch(req, server) {
       if (server.upgrade(req)) return;
       return new Response("websocket only", { status: 400 });
     },
     websocket: {
       open(ws) { clients.add(ws); },
       close(ws) { clients.delete(ws); },
       message(ws, msg) { /* handle */ },
     },
   });
   

6. Compile for distribution. bun build --compile produces a standalone executable — handy for CLIs and single-binary deploys without a runtime install.
7. Containerize. Use the official Bun image, copy package.json plus lockfile, run bun install --frozen-lockfile, then copy source — same layer-caching discipline as Node images.
8. Monitor in production. Track event-loop lag, memory, and request latency like any Node service; Bun's speed doesn't exempt it from observability.

Common pitfalls

• Assuming 100% Node parity — check Bun's compatibility tracker for the APIs you use (streams edge cases, cluster, some child_process behaviors) before cutting over.
• Binary lockfile diffs — bun.lockb is unreadable in PRs; use text lockfile mode if reviewability matters to your team.
• Native dependencies built for Node's V8 ABI — some need rebuilds or do not work under JavaScriptCore; test on the target platform.
• Skipping type checking — Bun runs TS without checking it; run tsc --noEmit in CI or type errors accumulate silently.
• Overusing watch mode in production — --hot is for development; production needs a process manager and graceful shutdown.
• Ignoring --frozen-lockfile in CI — without it, CI can install different versions than your machine.
• Treating Bun APIs as portable — Bun.serve, bun:sqlite, and bun:ffi do not exist in Node/Deno; isolate them behind adapters if you may switch runtimes.
• No graceful shutdown — Bun.serve needs explicit signal handling to drain connections on deploy; don't rely on defaults.
• SQLite concurrency assumptions — bun:sqlite is single-writer; high-write workloads need WAL mode or a client-server DB.
• Version churn — pinning matters more with a fast-moving runtime; unpinned CI picks up breaking changes.
• No .env discipline — auto-loaded .env files committed with secrets; keep them gitignored and document required vars.
• Forgetting bun outdated — dependencies drifting because installs are so fast nobody audits; review updates regularly.