curl -fsSL https://bun.sh/install | bash

brew install oven-sh/bun/bun

bun --version

mkdir my-project && cd my-project
bun init

// index.ts
console.log("Hello via Bun!");

bun run index.ts

# Option 1: Regenerate lockfile
rm -rf node_modules pnpm-lock.yaml
bun install

# Option 2: Use existing lockfile (experimental)
bun install

veryone has migrated.

The package.json doesn't change:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "vitest"
  }
}

You still run bun run dev, bun run build, bun run test. Scripts work the same.

Testing & HTTP Server

Bun has its own test runner that's compatible with the Jest/Vitest API:

// sum.test.ts
import { expect, test } from "bun:test";
import { sum } from "./sum";

test("2 + 2 = 4", () => {
  expect(sum(2, 2)).toBe(4);
});

Run with:

bun test

What if I want to keep using Vitest? Works perfectly. Bun can run Vitest as a runtime:

bun run vitest

You get Bun's startup speed with Vitest's features. Best of both worlds.

Bun includes an HTTP server that leaves Express crying in a corner:

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

console.log("Server at http://localhost:3000");

It uses the standard fetch API (Request/Response), so if you're coming from Cloudflare Workers or Deno, you'll feel right at home.

Built-in Utilities (Env, SQLite, Bundler)

Bun loads .env automatically. No dotenv. No configuration.

# .env
DATABASE_URL=postgres://localhost/mydb

// index.ts
console.log(Bun.env.DATABASE_URL);

That's it. Works, period.

This blew my mind. Bun comes with SQLite built in:

import { Database } from "bun:sqlite";

const db = new Database("mydb.sqlite");
db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");
db.run("INSERT INTO users (name) VALUES (?)", ["Fernando"]);

const users = db.query("SELECT * FROM users").all();
console.log(users);

No installing better-sqlite3 or sql.js. It just works.

Bun can also bundle your code for production:

bun build ./index.ts --outdir ./dist

It's faster than esbuild (which was already ridiculously fast). For most projects, it generates equivalent bundles. If you need something more sophisticated (code splitting, advanced tree shaking), you'll probably still need Vite or webpack. But for many cases, this is enough.

Pitfall Guide

1. Native Bindings Recompilation: Packages relying on Node native addons (e.g., bcrypt, sharp) may require recompilation against Bun's Zig/JSC environment. Always audit node_modules for prebuild-install or node-gyp dependencies before migration.
2. V8 vs JavaScriptCore Quirks: Bun uses JavaScriptCore (Safari's engine) instead of V8. Code exploiting V8-specific optimizations, hidden classes, or engine internals may exhibit different behavior or performance degradation.
3. Windows Compatibility Limitations: Bun's first-class support targets macOS and Linux. Windows support exists but carries known limitations in file watching, process management, and native module compatibility. Avoid as a primary Windows development runtime until parity improves.
4. Yarn PnP Incompatibility: Bun does not support Yarn's Plug'n'Play resolution strategy. Projects relying on PnP must switch to standard node_modules hoisting before migration.
5. Production Readiness & Stability: Node.js has 15 years of resolved edge cases and enterprise hardening. Bun is stable for most workloads but may encounter rare runtime bugs in complex production architectures. Validate thoroughly in staging before production rollout.
6. Lockfile Transition Friction: During team migration, maintaining dual lockfiles (pnpm-lock.yaml and bun.lockb) can cause dependency drift. Enforce a single source of truth via CI checks and clear team communication.

Deliverables

📘 Bun Migration Blueprint A phased rollout strategy:

1. CI/CD First: Replace npm/pnpm install with bun install in pipelines to capture immediate time/cost savings with zero runtime risk.
2. Local Development: Switch developers to bun run for instant feedback loops and native TS/JSX execution.
3. Staging Validation: Run full test suites (bun test or bun run vitest) and HTTP benchmarks to verify compatibility.
4. Production Rollout: Deploy to non-critical services first, monitor cold start metrics, and expand gradually.

✅ Pre-Migration Checklist

• Audit dependencies for native bindings (node-gyp, prebuild-install)
• Verify Windows compatibility requirements for team members
• Confirm Yarn PnP is disabled or migrated to node_modules
• Update CI pipelines to cache bun.lockb and node_modules
• Establish rollback procedure (retain Node/pnpm binaries in CI matrix)
• Benchmark baseline metrics (install time, startup latency, test duration)

⚙️ Configuration Templates

• package.json script compatibility layer (unchanged, executed via bun run)
• .env auto-loading pattern (no dotenv dependency required)
• bun.lockb version control strategy (commit binary lockfile, ignore in .gitignore only if team enforces regeneration)
• HTTP server fetch handler template for edge/serverless migration