Bun: The Complete Guide to the All-in-One JavaScript Runtime

Bun is an all-in-one JavaScript runtime, package manager, bundler, and test runner built from the ground up for speed. Written in Zig and powered by the JavaScriptCore engine (the same engine used by Safari), Bun delivers dramatically faster startup times, package installs, and HTTP throughput compared to Node.js. This guide covers every major feature of Bun in 2026, from the basics to advanced capabilities like SQLite integration, shell scripting, and macros.

Why Bun Is Fast: Zig and JavaScriptCore

Bun achieves its speed through two key architectural decisions. First, it is written in Zig, a low-level systems language designed for performance-critical software. Zig has no hidden control flow, no garbage collector, and compiles to highly optimized machine code. Second, Bun uses JavaScriptCore (JSC) from WebKit rather than V8 (used by Node.js and Deno). JSC has a faster startup time because it uses a lightweight interpreter tier before JIT compilation kicks in, whereas V8 eagerly compiles code. This means Bun scripts start executing almost instantly.

Installation and Getting Started

Bun installs as a single binary with no external dependencies. It works on macOS, Linux, and Windows (via WSL or native).

# Install Bun (macOS / Linux)
curl -fsSL https://bun.sh/install | bash

# Install via npm (alternative)
npm install -g bun

# Install via Homebrew (macOS)
brew install oven-sh/bun/bun

# Windows (native support)
powershell -c "irm bun.sh/install.ps1 | iex"

# Verify installation
bun --version  # 1.x.x

# Create a new project
bun init
# Creates: package.json, tsconfig.json, index.ts, README.md

# Run a TypeScript file directly (no config needed)
bun run index.ts

# Run with watch mode (auto-restart on changes)
bun --watch run index.ts

Package Manager: bun install

Bun includes the fastest JavaScript package manager available. It reads package.json, resolves dependencies from the npm registry, and writes to node_modules. The speed advantage comes from a binary lockfile (bun.lockb), parallel HTTP requests using native code, a global package cache, and symlink-based node_modules similar to pnpm.

# Install all dependencies from package.json
bun install

# Add a dependency
bun add express
bun add zod @types/node

# Add dev dependency
bun add -d typescript prettier eslint

# Add global package
bun add -g serve

# Remove a package
bun remove lodash

# Update all packages
bun update

# Run a script from package.json
bun run build
bun run dev

# CI mode: fail if lockfile is out of date
bun install --frozen-lockfile

# View lockfile as human-readable text
bun bun.lockb

# Execute a package binary (like npx)
bunx create-next-app@latest my-app
bunx prettier --write .

Install Speed Benchmarks

Bundler: bun build

Bun includes a production-ready JavaScript and TypeScript bundler. It supports tree shaking, code splitting, minification, source maps, and multiple output targets (browser, node, bun). It aims to be a faster alternative to esbuild and webpack for most use cases.

# Bundle for the browser
bun build ./src/index.ts --outdir ./dist --target browser

# Bundle for Node.js
bun build ./src/server.ts --outdir ./dist --target node

# Bundle for Bun runtime
bun build ./src/app.ts --outdir ./dist --target bun

# With minification and code splitting
bun build ./src/index.ts \
  --outdir ./dist \
  --target browser \
  --minify \
  --splitting \
  --sourcemap=external

# Programmatic API (build.ts)
const result = await Bun.build({
  entrypoints: ["./src/index.ts", "./src/worker.ts"],
  outdir: "./dist",
  target: "browser",
  minify: true,
  splitting: true,
  sourcemap: "external",
  naming: "[dir]/[name]-[hash].[ext]",
  define: {
    "process.env.NODE_ENV": JSON.stringify("production"),
  },
});

if (!result.success) {
  for (const msg of result.logs) {
    console.error(msg);
  }
}

Test Runner: bun test

Bun has a built-in test runner with a Jest-compatible API. It supports describe, test, expect, beforeAll, afterAll, beforeEach, afterEach, mocking, snapshots, and code coverage. Tests run significantly faster than Jest because there is no separate transpilation step and the runtime itself is faster.

// math.test.ts
import { describe, test, expect, beforeAll, mock } from "bun:test";

describe("math utilities", () => {
  test("adds two numbers", () => {
    expect(2 + 3).toBe(5);
  });

  test("array contains value", () => {
    const fruits = ["apple", "banana", "cherry"];
    expect(fruits).toContain("banana");
    expect(fruits).toHaveLength(3);
  });

  test("object matching", () => {
    const user = { name: "Alice", age: 30, role: "admin" };
    expect(user).toMatchObject({ name: "Alice", role: "admin" });
  });

  test("async operations", async () => {
    const data = await Promise.resolve({ status: "ok" });
    expect(data.status).toBe("ok");
  });

  test("error throwing", () => {
    expect(() => { throw new Error("fail"); }).toThrow("fail");
  });
});

// Mocking example
const mockFetch = mock(() => Promise.resolve({ ok: true }));
test("mock function", () => {
  mockFetch();
  expect(mockFetch).toHaveBeenCalledTimes(1);
});

Test Runner CLI Options

# Run all tests
bun test

# Run specific test file
bun test src/utils.test.ts

# Watch mode
bun test --watch

# With code coverage
bun test --coverage

# Filter tests by name
bun test --test-name-pattern "math"

# Set timeout (default 5000ms)
bun test --timeout 10000

HTTP Server: Bun.serve()

Bun.serve() is a high-performance HTTP server built into the runtime. It uses the Web standard Request and Response APIs, supports WebSocket upgrades, TLS, streaming, and can handle over 100,000 requests per second on modest hardware.

// server.ts — High-performance 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 === "/api/users") {
      const users = [
        { id: 1, name: "Alice" },
        { id: 2, name: "Bob" },
      ];
      return Response.json(users);
    }

    if (url.pathname === "/api/stream") {
      const stream = new ReadableStream({
        start(controller) {
          controller.enqueue("chunk 1\n");
          controller.enqueue("chunk 2\n");
          controller.close();
        },
      });
      return new Response(stream);
    }

    return new Response("Not Found", { status: 404 });
  },
});

console.log("Server running at http://localhost:" + server.port);

WebSocket Server

// WebSocket server with Bun.serve()
Bun.serve({
  port: 3000,
  fetch(req, server) {
    // Upgrade HTTP request to WebSocket
    if (server.upgrade(req)) {
      return; // Return nothing if upgraded
    }
    return new Response("Upgrade failed", { status: 500 });
  },
  websocket: {
    open(ws) {
      console.log("Client connected");
      ws.send("Welcome!");
    },
    message(ws, message) {
      console.log("Received:", message);
      ws.send("Echo: " + message);
    },
    close(ws) {
      console.log("Client disconnected");
    },
  },
});

File I/O: Bun.file() and Bun.write()

Bun provides optimized file I/O APIs that are significantly faster than Node.js equivalents. Bun.file() creates a lazy reference to a file, and Bun.write() writes data to disk. Both support text, JSON, ArrayBuffer, Blob, and streams.

// Reading files
const file = Bun.file("./data.json");
console.log(file.size);       // File size in bytes
console.log(file.type);       // MIME type

const text = await file.text();       // Read as string
const json = await file.json();       // Parse as JSON
const buffer = await file.arrayBuffer(); // Read as ArrayBuffer
const bytes = await file.bytes();     // Read as Uint8Array

// Writing files
await Bun.write("output.txt", "Hello, Bun!");
await Bun.write("data.json", JSON.stringify({ key: "value" }));
await Bun.write("copy.txt", Bun.file("original.txt"));

// Write Response body to file
const response = await fetch("https://example.com/data.json");
await Bun.write("downloaded.json", response);

// Streaming large files
const writer = Bun.file("large-output.txt").writer();
writer.write("line 1\n");
writer.write("line 2\n");
writer.flush();
writer.end();

Built-in SQLite: bun:sqlite

Bun includes a native SQLite client via the bun:sqlite module. There is no need to install any npm package. It is one of the fastest SQLite bindings available for any JavaScript runtime, supporting prepared statements, transactions, WAL mode, and typed results.

// Built-in SQLite — no npm install needed
import { Database } from "bun:sqlite";

// Open or create a database
const db = new Database("myapp.db");

// Enable WAL mode for better concurrent performance
db.exec("PRAGMA journal_mode = WAL");

// Create a table
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
  )
`);

// Prepared statements (safe from SQL injection)
const insertUser = db.prepare(
  "INSERT INTO users (name, email) VALUES (?, ?)"
);
insertUser.run("Alice", "alice@example.com");
insertUser.run("Bob", "bob@example.com");

// Query with typed results
const allUsers = db.prepare("SELECT * FROM users").all();
console.log(allUsers);
// [{ id: 1, name: "Alice", ... }, { id: 2, name: "Bob", ... }]

// Transactions for batch operations
const insertMany = db.transaction((users) => {
  for (const user of users) {
    insertUser.run(user.name, user.email);
  }
});

insertMany([
  { name: "Charlie", email: "charlie@example.com" },
  { name: "Diana", email: "diana@example.com" },
]);

Shell Scripting: Bun Shell

Bun includes a cross-platform shell (Bun.$) that lets you run shell commands directly from JavaScript or TypeScript. It works on macOS, Linux, and Windows without requiring bash. You can pipe commands, redirect output, and use template literals for interpolation.

// Bun Shell — cross-platform shell scripting
import { $ } from "bun";

// Run a command and get output
const result = await $`ls -la`.text();
console.log(result);

// Pipe commands
const count = await $`cat package.json | wc -l`.text();
console.log("Lines:", count.trim());

// Use variables safely (auto-escaped)
const filename = "my file.txt";
await $`touch ${filename}`;
await $`echo "hello" > ${filename}`;

// Redirect output to a file
await $`echo "build log" > build.log`;

// Check exit code
const proc = await $`grep -r "TODO" src/`.nothrow();
if (proc.exitCode === 0) {
  console.log("Found TODOs:", proc.text());
} else {
  console.log("No TODOs found");
}

// Run in background
const server = $`bun run server.ts`.spawn();
// ... do other work ...
server.kill();

Macros: Compile-Time Code Execution

Bun macros allow you to run JavaScript functions at bundle time and inline the results into the output. This is useful for embedding build metadata, reading configuration files, or generating code at compile time rather than runtime.

// macros.ts — runs at compile time, NOT runtime
export function getBuildTime() {
  return new Date().toISOString();
}

export function getGitCommit() {
  const proc = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"]);
  return proc.stdout.toString().trim();
}

// app.ts — import with { type: "macro" }
import { getBuildTime, getGitCommit } from "./macros" with { type: "macro" };

// These calls are evaluated at bundle time
// and replaced with their return values
console.log("Built at:", getBuildTime());
console.log("Commit:", getGitCommit());

// After bundling, the output becomes:
// console.log("Built at:", "2026-02-28T10:30:00.000Z");
// console.log("Commit:", "a1b2c3d");

Bun vs Node.js vs Deno: Feature Comparison

Here is a detailed comparison of the three major JavaScript runtimes in 2026.

Best Practices for Using Bun in Production

• Lockfile management: Commit bun.lockb to version control for reproducible installs. Use --frozen-lockfile in CI pipelines to ensure lockfile consistency.
• HTTP services: Use Bun.serve() for new HTTP services. It outperforms Express and Fastify on raw throughput while using standard Web APIs.
• SQLite usage: Leverage the built-in SQLite for local databases, caching layers, and session storage instead of adding external dependencies.
• Bundling: Use bun build with --minify and --splitting for production frontend bundles. Enable source maps for debugging.
• Environment variables: Take advantage of automatic .env loading. Bun reads .env, .env.local, and .env.production without the dotenv package.
• Testing: Write tests using bun test with the built-in Jest-compatible API. No configuration or extra packages needed.

Migrating from Node.js to Bun

Migrating an existing Node.js project to Bun is straightforward because Bun implements the vast majority of Node.js APIs. Here is a step-by-step approach.

// Step 1: Replace npm/yarn/pnpm with bun
# Delete old lockfiles and node_modules
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml

# Install with Bun
bun install

// Step 2: Update package.json scripts
// Before:
// "dev": "nodemon src/server.ts"
// "test": "jest --coverage"
// "build": "tsc && webpack"

// After:
// "dev": "bun --watch src/server.ts"
// "test": "bun test --coverage"
// "build": "bun build src/index.ts --outdir dist"

// Step 3: Remove unnecessary devDependencies
bun remove ts-node nodemon dotenv jest ts-jest
# Bun handles TypeScript, watching, .env, and testing natively

// Step 4: Update imports (most work as-is)
// Node.js built-in modules work without changes:
import fs from "node:fs";
import path from "node:path";
import crypto from "node:crypto";
// These all work identically in Bun

When to Choose Bun Over Node.js or Deno

Frequently Asked Questions