Building Your First Project with Bun 2.0: Migration Guide

Bun 2.0 is no longer experimental. Following Anthropic’s acquisition and Claude Code CLI’s $1B ARR success running on Bun, the JavaScript runtime has reached enterprise stability with 95-98% Node.js compatibility. If slow npm installs bottleneck your CI/CD or you’re tired of TypeScript build steps, migrating to Bun offers 20-40x faster package installs and native TypeScript execution. This tutorial walks through migrating a real Node.js project to Bun, covering installation, compatibility checks, and deployment.

Why Bun Matters in 2026

Bun is an all-in-one JavaScript toolkit: runtime, package manager, bundler, and test runner combined. Written in Zig and powered by JavaScriptCore instead of V8, Bun dramatically reduces startup times and memory usage compared to Node.js.

The numbers are compelling. Bun installs a 50-dependency project in 0.8 seconds—17x faster than npm. For an 847-package monorepo, npm takes 32 seconds while Bun finishes in 1.2 seconds. That’s a 26.7x speedup. Vercel’s internal testing shows a 28% latency reduction in CPU-bound Next.js rendering workloads when switching from Node.js to Bun.

Anthropic’s acquisition validates Bun’s production readiness. Claude Code, which hit $1B ARR, runs on Bun with millions of monthly downloads. This isn’t a side project anymore—it’s enterprise-grade infrastructure backed by a company that depends on it for critical services.

Installation: Get Bun Running in 60 Seconds

Installing Bun is straightforward. On macOS and Linux, use the official installation script:

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

For Windows, Homebrew, or Docker installations, check the official Bun installation guide. After installation, verify it worked:

bun --version

You should see version 1.x.x or higher. If the command isn’t found, restart your terminal or add Bun’s bin directory to your PATH.

Migrating Your Node.js Project

The migration process has five steps. We’ll use a sample Express API project as an example.

Step 1: Replace Your Package Manager

Bun’s package manager is a drop-in replacement for npm. Remove your existing lockfile and install dependencies with Bun:

rm package-lock.json bun install

This generates bun.lockb, Bun’s binary lockfile. The lockfile format is compatible with your existing package.json—no changes needed. On our test project with 847 dependencies, this step completed in 1.2 seconds versus npm’s 32 seconds.

Step 2: Update package.json Scripts

Replace Node.js commands with Bun equivalents in your scripts section:

{   "scripts": {     "dev": "bun run src/index.ts",     "start": "bun run src/index.ts",     "test": "bun test"   } }

Notice TypeScript files run directly without a build step. No tsc, no ts-node, no compilation. Bun transpiles TypeScript internally and executes immediately.

Step 3: Test Compatibility

Run your development server to verify everything works:

bun run dev

If your project uses pure JavaScript packages and standard Node.js APIs like http, fs, or path, it should work without changes. Popular frameworks like Express, Fastify, and Next.js are fully compatible.

Step 4: Audit Native Dependencies

Here’s where most migration failures happen. Bun uses JavaScriptCore, not V8, so native addons compiled with node-gyp won’t work. Check for problematic dependencies:

npm list | grep "node-gyp"

If you see packages like bcrypt, sharp, or sqlite3, you’ll need replacements:

• bcrypt → bcryptjs (pure JavaScript implementation)
• sharp → Use the experimental WASM build
• sqlite3 → Bun.sql (Bun’s built-in SQLite support)

The Bun Node.js compatibility documentation lists known issues and workarounds. As of 2026, Bun achieves 95-98% compatibility, but that remaining 2-5% can block your migration if your stack depends on incompatible packages.

Step 5: Handle TypeScript Configuration

While Bun runs TypeScript without configuration, you should still run type checking during development. Bun’s transpiler doesn’t perform type checking—it just strips types and executes. Add this to your CI pipeline or pre-commit hooks:

tsc --noEmit

This validates types without generating output files. If you initialized your project with bun init, a compatible tsconfig.json is already generated with recommended settings like "moduleResolution": "bundler".

Deployment: Taking Bun to Production

Several major platforms now support Bun natively. Here’s how to deploy on the most popular ones.

Vercel Deployment

Vercel’s Bun runtime is in Public Beta. Create a vercel.json file:

{   "runtime": "bun" }

Deploy normally with vercel deploy. Vercel’s internal testing shows a 28% reduction in average latency for CPU-bound Next.js workloads when using Bun instead of Node.js.

Docker Deployment

For platforms like Render, Railway, or any container-based environment, use Bun’s official Docker image:

FROM oven/bun:latest WORKDIR /app COPY package.json bun.lockb ./ RUN bun install COPY . . CMD ["bun", "run", "start"]

This Dockerfile mirrors the standard Node.js pattern but uses oven/bun as the base image. Build and deploy as you would any containerized application.

AWS Lambda and Other Platforms

AWS Lambda supports Bun through custom runtimes. Render offers native Bun support without Docker. Railway and Fly.io support Bun via Docker deployments. Platform adoption is accelerating—check your provider’s documentation for the latest Bun support status.

When to Migrate (and When to Wait)

Bun isn’t the right choice for every project. Here’s a decision framework based on real-world 2026 production usage.

Green light—migrate now:

• New TypeScript projects (greenfield development)
• HTTP APIs without native addons (Express, Fastify, Hono)
• Serverless functions on Vercel, AWS Lambda, or edge platforms
• Projects bottlenecked by slow npm install times in CI/CD

Yellow light—test first:

• Existing Node.js apps with complex dependency trees
• Projects using Worker Threads heavily (basic usage works, complex patterns have gaps)
• Apps with native modules (audit compatibility before committing)

Red light—stay on Node.js:

• Heavy reliance on node-gyp native addons with no alternatives
• Complex vm module sandboxing requirements (Bun’s implementation is fragile)
• Advanced cluster module patterns (partial support, edge cases exist)

The safe hybrid approach: use bun install for package management to get 20-40x faster installs, but keep Node.js as your production runtime until you’ve validated all dependencies. This provides immediate CI/CD speed gains with zero migration risk.

Real-World Performance Gains

Let’s quantify the benefits with real benchmarks from 2026:

Benchmark	npm/Node.js	Bun	Speedup
50-dependency install	13.6s	0.8s	17x
847-package monorepo	32s	1.2s	26.7x
HTTP requests/sec	Baseline	3-4x more	3-4x

These aren’t synthetic benchmarks. They’re from PkgPulse’s 2026 performance analysis and production deployments. For teams running hundreds of CI/CD builds daily, a 26x install speedup translates to hours of saved developer time and reduced infrastructure costs.

Why is Bun so much faster? Three reasons: it’s written in Zig (compiled native code versus Node’s JavaScript package manager), it uses approximately 165,000 system calls for a typical install versus npm’s 1,000,000+, and its binary lockfile format parses faster than JSON or YAML.

The Bottom Line

Bun 2.0 is production-ready for the right use cases in 2026. With 95-98% Node.js compatibility, Anthropic’s backing, and major platform support from Vercel and Render, it’s no longer a risky experiment. Start with bun install to accelerate your CI/CD pipeline. If you’re starting a new TypeScript project or building serverless APIs, Bun offers substantial performance gains with minimal migration effort.

The JavaScript runtime ecosystem is fragmenting between Bun, Node.js, and Deno. That’s not a problem—it’s healthy competition driving innovation. Developers now have options optimized for different workloads. For performance-critical applications where install speed and runtime efficiency matter, Bun delivers measurable improvements backed by real-world production usage.