Bun Best Practices

Foundational knowledge for Bun adoption decisions. Bun serves two distinct roles—understand when each applies.

Two Distinct Roles

Bun as Package Manager

Replaces pnpm/npm/yarn for dependency management:

• bun install — Install dependencies (fast, binary lockfile)

• bun add <pkg> — Add dependency

• bun remove <pkg> — Remove dependency

• bun --filter <workspace> — Run in specific workspace

Key differences from pnpm:

• Lockfile: bun.lock (binary) vs pnpm-lock.yaml (YAML)

• Workspaces: Defined in root package.json , no separate pnpm-workspace.yaml

• Speed: Significantly faster installs due to binary lockfile and caching

Bun as Runtime

Replaces Node.js for executing JavaScript/TypeScript:

• bun run script.ts — Execute TypeScript directly (no tsc)

• bun test — Built-in test runner (Jest-compatible API)

• bun build — Bundle for production

• Native SQLite, file I/O, HTTP server optimizations

Key differences from Node.js:

• TypeScript: Transpilation, not full tsc checking (use tsc --noEmit for types)

• APIs: Some Node.js APIs missing or behave differently

• Performance: Often 2-10x faster for I/O-heavy workloads

Decision Tree: When to Use Bun

┌─────────────────────────────────────────────────────────┐ │ Consider Bun When: │ ├─────────────────────────────────────────────────────────┤ │ ✅ CLI tools (fast startup, no cold boot) │ │ ✅ Edge functions (lightweight runtime) │ │ ✅ Internal dev tools (team controls deployment) │ │ ✅ New greenfield projects (no legacy constraints) │ │ ✅ Scripts/automation (fast execution) │ │ ✅ Projects with simple dependency trees │ └─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐ │ Prefer pnpm When: │ ├─────────────────────────────────────────────────────────┤ │ ⚠️ Expo/EAS builds (Node.js required) │ │ ⚠️ Vercel serverless (limited Bun support) │ │ ⚠️ Complex native module dependencies │ │ ⚠️ Team unfamiliar with Bun quirks │ │ ⚠️ Production apps needing maximum stability │ │ ⚠️ Projects with extensive Node.js API usage │ └─────────────────────────────────────────────────────────┘

Hybrid Setup Pattern

Many projects benefit from using both:

monorepo/ ├── apps/ │ ├── web/ # Next.js app → pnpm (Vercel deployment) │ └── mobile/ # Expo app → pnpm (EAS requires Node) ├── packages/ │ └── shared/ # Shared utilities → either works ├── tools/ │ └── cli/ # Internal CLI → Bun (fast startup) └── scripts/ # Build/deploy scripts → Bun (fast execution)

Rule of thumb:

• External-facing production apps → pnpm (stability)

• Internal tools and scripts → Bun (speed)

Workspace Configuration

pnpm (separate file)

pnpm-workspace.yaml

packages:

• 'apps/*'
• 'packages/*'

Bun (in package.json)

{ "workspaces": ["apps/", "packages/"] }

Migration note: Remove pnpm-workspace.yaml when switching to Bun; add workspaces to root package.json .

Anti-Patterns

1. Assuming Full Node.js Compatibility

Wrong:

// Assuming all Node.js APIs work identically import { fork } from 'child_process'; fork('./worker.js'); // May behave differently in Bun

Right:

// Test critical Node.js API usage before migration // Check: https://bun.sh/docs/runtime/nodejs-apis

2. Mixing Lockfiles

Wrong:

project/ ├── bun.lock ├── pnpm-lock.yaml # Both present = confusion └── package.json

Right:

project/ ├── bun.lock # OR pnpm-lock.yaml, not both └── package.json

3. Skipping CI Migration

Wrong:

Still using pnpm in CI

• uses: pnpm/action-setup@v4
• run: pnpm install

Right:

Match local tooling

• uses: oven-sh/setup-bun@v2
• run: bun install

4. Ignoring Platform Support

Wrong:

// Deploying to platform that doesn't support Bun runtime export default async function handler(req, res) { // Assumes Bun runtime features }

Right:

// Verify deployment target supports Bun // Vercel: experimental Bun runtime flag // Netlify: Node.js only (as of 2025) // Fly.io: Full Bun support

Performance Benchmarking

Before migrating, benchmark your specific workflows:

Install time comparison

time pnpm install time bun install

Script execution comparison

time pnpm run build time bun run build

Test runner comparison

time pnpm test time bun test

Only migrate if Bun provides measurable benefit for YOUR project.

Related References

• references/workspace-config.md — Workspace migration details

• references/compatibility-matrix.md — Framework/tool compatibility

• references/ci-cd-patterns.md — CI/CD configuration patterns

• references/hybrid-setup.md — Running Bun + pnpm together

Related Skills

• /check-bun — Audit project for Bun compatibility

• /fix-bun — Fix Bun migration issues

• /bun — Full Bun migration orchestrator