Bun Runtime

Bun Runtime

Bun is a Node-compatible JS runtime, package manager, bundler, and test runner — all one binary, written in Zig. Faster than Node + pnpm + tsc + vitest combined for most workloads. Trade-off: 95% Node compatibility, not 100%.

When to use

• New TS/JS project — install speed alone is worth it.
• Build/test bottleneck on your CI.
• Edge-deploy compatible (Cloudflare Workers / Vercel) — Bun runs on Vercel as of 2025.
• CLI tools — bun build --compile produces single-binary executables.

When NOT to use

• Production runtime for a Node app with deep ecosystem deps you haven't tested.
• Apps using native modules that haven't been ported (rare; check your node_modules).
• Any case where "must be 100% Node identical" is a hard requirement.

What Bun replaces

| Tool | Replaced by | |---|---| | Node | bun run (runtime) | | npm/pnpm/yarn | bun install | | ts-node / tsx | Native — Bun runs .ts files directly | | nodemon | bun --hot | | webpack/esbuild/vite (for libs) | bun build | | jest/vitest | bun test | | dotenv | Built-in .env loading |

Migration from Node + pnpm

# In existing repo
bun install                              # reads package.json, replaces node_modules
bun pm ls                                # verify deps installed

# Run scripts
bun run dev                              # uses package.json scripts
bun run build

# Replace runtime
node server.js  →  bun server.js
ts-node script.ts  →  bun script.ts      # no compile step

# Replace tests
vitest  →  bun test                      # if you used vitest's globals

package.json scripts work as-is. bun install produces a bun.lockb (binary lockfile); commit it; delete pnpm-lock.yaml / package-lock.json when fully migrated.

Built-in HTTP server (zero deps)

// server.ts
const server = Bun.serve({
  port: 3000,
  async fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/healthz") return new Response("ok");
    if (url.pathname.startsWith("/api/")) return handleApi(req);
    return new Response("not found", { status: 404 });
  },
});

console.log(`Listening on ${server.port}`);

Bun.serve is roughly 4x faster than Express for raw throughput. It speaks the standard Request/Response Web API — code is portable to Cloudflare Workers and Deno.

Built-in SQLite

import { Database } from "bun:sqlite";
const db = new Database("app.sqlite");
db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)");
const insert = db.prepare("INSERT INTO users (email) VALUES (?)");
insert.run("a@b.com");
const rows = db.query("SELECT * FROM users").all();

Faster than better-sqlite3, no native compile step, ships with the runtime. Replaces a lot of "small persistent state" use cases for CLI tools.

Built-in test runner

// users.test.ts
import { describe, expect, test } from "bun:test";
import { greet } from "./users";

describe("greet", () => {
  test("returns hello", () => {
    expect(greet("Mahesh")).toBe("Hello, Mahesh");
  });
});

bun test                                # run all *.test.ts
bun test --coverage                     # built-in coverage
bun test --watch
bun test users                          # name filter

Jest-compatible API. Migration from Vitest is mostly imports.

.env loading (built-in)

Bun automatically loads .env, .env.local, .env.. No dotenv package. .env.local overrides .env; both are loaded before your app code runs.

Building a single-binary CLI

bun build --compile --target=bun-linux-x64 --outfile=mycli ./src/cli.ts

Produces a 50–80MB binary that includes the runtime. No node install needed on target machine. Cross-compile for darwin-x64, darwin-arm64, linux-x64, linux-arm64, win-x64.

Performance reality check

• bun install is 5–25x faster than npm install, 2–10x faster than pnpm.
• bun run vs node runtime is 1.1–1.5x faster on typical Node workloads (not 3x like marketing claims).
• bun build is comparable to esbuild.
• bun test is 2–5x faster than vitest.

The compounded CI win (install + test + build) is the real story. A 4-min CI becomes 90s.

Compatibility gotchas

| Issue | Workaround | |---|---| | Some node: modules incomplete (node:cluster, node:vm) | Check bun --print 'process.versions.bun' and feature support before relying | | Native modules requiring node-gyp | Most work; some need rebuilding. bun pm trust | | npm-only postinstall hooks | Bun doesn't run lifecycle scripts by default — bun install --trust | | Differences in process.env mutation | Bun freezes process.env after start in production; mutate before serving | | Worker threads API surface | Mostly works; some edge cases differ |

Run your Node test suite under Bun before committing to it as runtime.

Edge deploy

Cloudflare Workers: standard Worker syntax (no Bun APIs); use Bun for bun build step in CI. Vercel: now supports Bun directly as runtime; specify in vercel.json "build": { "env": { "BUN_RUNTIME": "1" } } or use bun install in build step.

Anti-patterns

• Mixing bun install and npm install in the same repo — divergent lockfiles, irreproducible builds. Pick one.
• Committing node_modules "for safety" — lockfile + bun install is reproducible.
• Using bun: imports in code that may run on Node — breaks portability. Either commit fully or feature-detect.
• Production runtime without testing the actual Node deps — 5% incompatibility usually means 1–2 packages bite. Test before betting prod on it.
• Relying on bun build for production library bundling without testing the output — output differs from Vite/Rollup in subtle ways for libs.
• Using Bun.serve then trying to deploy to Lambda — Lambda expects a handler, not a server. Use Hono or similar abstraction.
• bun --hot in production — dev-only. bun run for prod.
• Running bun test for end-to-end browser tests — Bun doesn't have a browser. Use Playwright separately.
• Skipping bun test --coverage because "it might miss edges" — it works fine; the coverage tool is honest about what it sees.

Verify it worked

• [ ] bun install in a fresh clone is < 5s for a typical app.
• [ ] bun test passes the same suite that worked under Node + vitest.
• [ ] bun run build produces the expected output.
• [ ] All native deps work (bun pm ls --all shows no errors).
• [ ] Production app under bun server.js handles the same load as node server.js without crashing.
• [ ] CI time is materially shorter than the Node baseline.
• [ ] .env.local overrides .env automatically (no dotenv import).
• [ ] Single-binary bun build --compile runs on a target machine without Node installed.
• [ ] bun --hot reloads the server on file change.
• [ ] No mixing of npm install / bun install — only bun.lockb exists.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MaheshAwasare
• Source: MaheshAwasare/claude-skills-pro
• License: MIT

Install and usage instructions live in the source repository linked above.