curl -fsSL https://bun.sh/install | bash
# Or macOS Homebrew:
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

Package Scripts Compatibility

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

Execute identically: bun run dev, bun run build, bun run test.

Native Test Runner

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

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

bun test

Vitest remains fully compatible: bun run vitest leverages Bun's startup speed with Vitest's assertion ecosystem.

High-Performance HTTP Server

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

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

Uses standard Web fetch API (Request/Response). Drop-in compatible with Cloudflare Workers/Deno patterns.

Environment Variables & Built-in SQLite

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

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

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);

Zero-dependency database access. No better-sqlite3 or sql.js required.

Production Bundling

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

Outperforms esbuild with equivalent output. For advanced code-splitting/tree-shaking, Vite/webpack remain viable fallbacks.

Pitfall Guide

1. Native Binding Recompilation: Packages relying on Node C++ addons (e.g., bcrypt, sharp) may require recompilation against Bun's JavaScriptCore environment. Verify node_modules compatibility before production rollout.
2. V8-Specific Quirks: Bun uses JavaScriptCore, not V8. Code exploiting V8 internals, hidden classes, or engine-specific optimizations may exhibit unexpected behavior or performance degradation.
3. Windows Platform Limitations: First-class support targets macOS/Linux. Windows deployments may encounter path resolution edge cases or missing POSIX APIs. Validate thoroughly if Windows is your primary CI/CD host.
4. Yarn PnP Incompatibility: Bun does not support Yarn Plug'n'Play. Migration requires standard node_modules resolution. Convert PnP projects to node_modules before switching lockfiles.
5. Production Readiness vs. CI/CD Validation: Bun is stable but lacks Node's 15-year bug-resolution history. Critical production systems should migrate CI/CD pipelines first to measure install speed gains and dependency compatibility before touching runtime deployments.
6. Lockfile Coexistence Conflicts: During team transitions, mixing pnpm-lock.yaml and bun.lockb can cause phantom dependency resolution. Enforce consistent tooling via packageManager field in package.json or CI environment checks.

Deliverables

📦 Migration Blueprint

• Phase 1: CI/CD pipeline swap (npm install → bun install)
• Phase 2: Local dev environment validation (bun run dev)
• Phase 3: Test suite migration (bun test or bun run vitest)
• Phase 4: Staging runtime validation (HTTP server & native bindings)
• Phase 5: Production rollout with feature flags

✅ Pre-Migration Checklist

• Audit package.json for native C++ bindings
• Verify V8-specific code paths or engine hacks
• Confirm Windows CI runners meet Bun compatibility requirements
• Backup existing lockfile & node_modules
• Run bun install in isolated branch & validate dependency tree
• Benchmark cold-start & test execution times

⚙️ Configuration Templates

// package.json (toolchain declaration)
{
  "packageManager": "bun@1.1.x"
}

// tsconfig.json (Bun-optimized)
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true
  }
}

# .github/workflows/ci.yml (Bun cache example)
- name: Setup Bun
  uses: oven-sh/setup-bun@v1
- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: ~/.bun/install/cache
    key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}

📚 Official Resources

• Bun Documentation
• Node.js Compatibility Guide
• Awesome Bun Ecosystem