Bun JavaScript Runtime Guide — Faster Node.js Alternative

What Is Bun?

Bun is an all-in-one JavaScript runtime built on JavaScriptCore (Safari's JS engine) rather than V8. It ships as a single binary that replaces Node.js, npm, webpack, and Jest with a dramatically faster alternative.

Key benchmarks: Bun installs packages 25x faster than npm, starts processes 4x faster than Node.js, and runs HTTP servers at 2-3x the throughput. These gains come from using Zig (a low-level systems language) for the runtime internals and JavaScriptCore's optimized startup.

Installation and Basic Usage

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

# Or with npm (for project-local installs)
npm install -g bun

# Run a JavaScript file
bun run index.ts   # TypeScript works natively, no compilation step

# Start a project
bun init
bun add express      # Install packages (npm-compatible)
bun install          # Install from package.json (reads npm lockfile)

Bun as a Package Manager

# Replace npm install with bun install (25x faster)
bun install

# Add a package
bun add react react-dom
bun add -d typescript @types/react

# Remove a package  
bun remove lodash

# Run scripts from package.json
bun run build
bun run test

Bun uses a binary lockfile (bun.lockb) instead of JSON, which is why installs are so fast. Run bun install --frozen-lockfile in CI for reproducible installs.

Built-in HTTP Server

// server.ts — native Bun HTTP server
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url)
    
    if (url.pathname === '/') {
      return new Response('Hello from Bun!')
    }
    
    if (url.pathname === '/json') {
      return Response.json({ status: 'ok', runtime: 'bun' })
    }
    
    return new Response('Not Found', { status: 404 })
  },
})

console.log(`Server running at http://localhost:${server.port}`)

Bun Test Runner

// math.test.ts
import { expect, test, describe } from 'bun:test'
import { add, multiply } from './math'

describe('math utilities', () => {
  test('adds two numbers', () => {
    expect(add(2, 3)).toBe(5)
  })
  
  test('multiplies two numbers', () => {
    expect(multiply(3, 4)).toBe(12)
  })
})

// Run tests
// bun test
// bun test --watch
// bun test --coverage

The test runner is Jest-compatible — most Jest tests run without modification. Test files are detected by the *.test.ts or *.spec.ts naming convention.

Frequently Asked Questions

Is Bun production-ready?

Bun 1.0 was released in September 2023 and is used in production by companies like Vercel and Stripe for tooling tasks. For server applications, Node.js still has a more mature ecosystem, but Bun is viable for new projects.

Does Bun support all Node.js APIs?

Bun implements most Node.js APIs including fs, path, http, crypto, and child_process. Compatibility is ~95% for common packages. The compatibility table lists gaps.

Can I use Bun with Next.js?

Yes. Run bun create next-app to scaffold a Next.js project using Bun as the package manager. The dev server (bun run dev) runs Next.js on Node.js internals while using Bun's fast package resolution.