Bun: The Fast JavaScript Runtime

You clone a repo, run npm install, and go make coffee. Then CI does the same thing on every push. Then you add ts-node to run one TypeScript script, Jest plus ts-jest to test it, and a bundler config to ship it. None of these tools is slow on its own, but together they add a lot of waiting and a lot of config files.

Bun tries to fold all of that into one binary: a runtime, package manager, bundler, and test runner. It's written in Zig and runs on JavaScriptCore instead of V8. Below I'll cover how to install it, what each piece does, where it's actually faster, and the cases where I'd still stick with Node.js.

What You Get in One Binary

Install Bun and you get four tools that you'd normally pull in separately:

• Runtime: Execute JavaScript and TypeScript directly, with no transpilation step
• Package manager: bun install reads package.json and installs faster than npm, yarn, or pnpm
• Bundler: Bundle JavaScript/TypeScript for production, with ESM and CJS support
• Test runner: A Jest-compatible test runner built into the runtime, no extra dependencies

Jarred Sumner started the project, and v1.0 shipped in September 2023. It's open source under the MIT license.

Installation and Setup

Installing Bun is one command on macOS, Linux, or WSL. The install script drops a single binary in ~/.bun/bin/bun and adds it to your shell profile, so open a new terminal (or source your profile) before running bun.

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

# macOS with Homebrew
brew install oven-sh/bun/bun

# npm (if you already have Node.js)
npm install -g bun

# Verify installation
bun --version
# e.g. 1.1.34

# Interactive project init
bun init

# Create from a template
bun create react my-app       # React + Vite
bun create next my-app        # Next.js
bun create hono my-api        # Hono web framework
bun create elysia my-api      # Elysia (Bun-first framework)

# Change directory and run
cd my-app
bun run dev

# Run a TypeScript file directly
bun run index.ts

# Watch mode (re-run on file changes)
bun --watch run index.ts

# Execute a one-liner
bun -e "console.log(Bun.version)"

Bun as a Package Manager

This is the part you can adopt today without changing your runtime. bun install reads your existing package.json and pulls from the npm registry, but it keeps a global cache and links packages from it, so reinstalls on a warm machine are very quick.

Package Manager Commands

# Install all dependencies from package.json
bun install

# Install without devDependencies (production)
bun install --production

# Install frozen (fails if bun.lockb would change)
bun install --frozen-lockfile

# Force re-download (ignore cache)
bun install --force

# Add a dependency
bun add express
bun add zod

# Add a dev dependency
bun add -d typescript @types/express

# Add a peer dependency
bun add --peer react

# Remove a package
bun remove lodash

# Upgrade all packages
bun update

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

# Shorthand: only safe when the name isn't a built-in command
bun dev
bun build

# Run a local binary from node_modules
bun x tsc --version          # like npx but faster
bunx eslint src/              # alias for bun x

# package.json (root of a monorepo)
{
  "name": "my-monorepo",
  "workspaces": ["packages/*", "apps/*"]
}

# Install all workspace dependencies at once
bun install

# Run a script in a specific workspace
bun run --filter="@myapp/ui" build

# Run a script in all workspaces
bun run --filter="*" test

Lockfile: bun.lockb

Older Bun versions write a binary lockfile (bun.lockb) instead of a text file like package-lock.json. Commit it like any other lockfile. The downside is that diffs in pull requests are unreadable, which is why Bun 1.2 switched the default to a text bun.lock. If you're still on the binary format, you can print it as text:

# Print the binary lockfile as text (Yarn v1 lockfile format)
bun bun.lockb

Building HTTP Servers with Bun

Bun.serve() is built on the standard Request and Response objects, so if you've written a Cloudflare Worker or a Next.js route handler, it'll look familiar. It handles noticeably more requests per second than Node's http module in hello-world benchmarks, and WebSockets are built in. A minimal REST API:

const PORT = process.env.PORT ? Number(process.env.PORT) : 3000;

const server = Bun.serve({
  port: PORT,
  async fetch(req) {
    const url = new URL(req.url);

    // GET /
    if (url.pathname === "/" && req.method === "GET") {
      return Response.json({ message: "Hello from Bun!", version: Bun.version });
    }

    // GET /users
    if (url.pathname === "/users" && req.method === "GET") {
      const users = [
        { id: 1, name: "Alice" },
        { id: 2, name: "Bob" },
      ];
      return Response.json(users);
    }

    // POST /users
    if (url.pathname === "/users" && req.method === "POST") {
      const body = await req.json();
      // ... save to database
      return Response.json({ created: true, user: body }, { status: 201 });
    }

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

console.log(`Listening on http://localhost:${server.port}`);

bun run server.ts
# Listening on http://localhost:3000

WebSocket Support

You don't need the ws package. Add a websocket handler next to fetch and call server.upgrade():

Bun.serve({
  port: 3000,
  fetch(req, server) {
    // Upgrade HTTP request to WebSocket
    if (server.upgrade(req)) return; // upgrade succeeded
    return new Response("Use WebSocket", { status: 426 });
  },
  websocket: {
    open(ws) {
      console.log("Client connected");
      ws.send("Welcome!");
    },
    message(ws, data) {
      console.log("Received:", data);
      ws.send(`Echo: ${data}`);
    },
    close(ws) {
      console.log("Client disconnected");
    },
  },
});

Bun's Built-in Test Runner

The test runner copies Jest's API on purpose: describe, it, expect, beforeEach, afterAll, and mocks all look the same. Most Jest suites move over with few or no changes, and TypeScript test files run without ts-jest.

import { describe, it, expect, beforeEach, mock } from "bun:test";

// Simple utility being tested
function add(a: number, b: number) {
  return a + b;
}

describe("add()", () => {
  it("adds two positive numbers", () => {
    expect(add(2, 3)).toBe(5);
  });

  it("handles negative numbers", () => {
    expect(add(-1, 1)).toBe(0);
  });

  it("returns the correct type", () => {
    expect(typeof add(1, 2)).toBe("number");
  });
});

// Mocking
const fetchData = mock(async (id: number) => {
  return { id, name: "Mocked User" };
});

describe("fetchData()", () => {
  it("calls the mock once", async () => {
    const result = await fetchData(1);
    expect(fetchData).toHaveBeenCalledTimes(1);
    expect(result.name).toBe("Mocked User");
  });
});

# Run all test files
bun test

# Watch mode
bun test --watch

# Run a specific file
bun test math.test.ts

# Run tests matching a pattern
bun test --test-name-pattern "adds two"

# Code coverage
bun test --coverage

Bun's Bundler

bun build bundles JavaScript and TypeScript for browsers, Bun, or Node. It handles ESM, CommonJS, CSS, and static assets. It doesn't have the plugin ecosystem of Webpack or Rollup, so I wouldn't move a heavily customized frontend build to it. For server code, small libraries, and quick build steps, it's fast and needs almost no config.

# Bundle for browser (default target)
bun build ./src/index.ts --outdir ./dist

# Minified production build
bun build ./src/index.ts --outdir ./dist --minify

# Bundle as CommonJS module
bun build ./src/lib.ts --outdir ./dist --format cjs

# Bundle with sourcemaps
bun build ./src/index.ts --outdir ./dist --sourcemap external

# Bundle everything into a single file
bun build ./src/index.ts --outfile ./dist/bundle.js

# Target specific environments
bun build ./src/index.ts --target browser   # Browser (default)
bun build ./src/index.ts --target bun       # Bun runtime
bun build ./src/index.ts --target node      # Node.js

Using the Bundler API

You can also call the bundler from a build script, which is handy once the CLI flags get long:

const result = await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  minify: true,
  sourcemap: "external",
  target: "browser",
  define: {
    "process.env.NODE_ENV": '"production"',
  },
  plugins: [
    // Bun has a plugin API compatible with esbuild plugins
  ],
});

if (!result.success) {
  console.error("Build failed:", result.logs);
  process.exit(1);
}

console.log(`Built ${result.outputs.length} files`);

TypeScript and JSX Without Config

You don't need to install typescript, set up tsconfig.json for execution, or run tsc first. Bun's own transpiler strips the types when it loads the file.

// Bun reads jsxImportSource from tsconfig.json automatically
// No Babel, no extra config needed

import { renderToString } from "react-dom/server";

function App() {
  return (
    <html>
      <head><title>My App</title></head>
      <body>
        <h1>Hello from Bun + React SSR!</h1>
      </body>
    </html>
  );
}

const html = renderToString(<App />);

Bun.serve({
  port: 3000,
  fetch() {
    return new Response(html, {
      headers: { "Content-Type": "text/html" },
    });
  },
});

Bun vs Node.js: Performance Comparison

Treat the numbers below as rough ballpark figures, roughly in line with what Bun publishes and what community benchmarks report. They depend heavily on hardware, project size, and network. The install and startup gains show up in almost any project. The requests-per-second gap is from hello-world servers. Once your handler waits on a database, that gap shrinks a lot.

Node.js Compatibility

Bun aims to be fully compatible with Node.js, and most npm packages and Node code run unchanged. What it implements:

• Node.js built-in modules: fs, path, http, crypto, stream, os, events, and more
• CommonJS and ESM: Both module systems work, and you can mix them
• npm packages: Works with Express, Fastify, Prisma, Drizzle, Mongoose, and most popular packages
• Environment variables: process.env, .env file loading built-in (no dotenv needed). This one can surprise you: Bun loads .env from the working directory automatically, so a stray local .env can override what you expected in a container or CI job
• Web APIs: fetch, Request, Response, WebSocket, URL, crypto (Web Crypto)

Built-in SQLite With No Dependencies

For small backends, scripts, and local tooling, bun:sqlite saves you a native dependency. It's a synchronous SQLite client with an API modeled on better-sqlite3, and there's nothing to install or compile:

import { Database } from "bun:sqlite";

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

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

// Prepared statement (reusable, prevents SQL injection)
const insertUser = db.prepare(
  "INSERT INTO users (name, email) VALUES ($name, $email)"
);

// Insert a user
insertUser.run({ $name: "Alice", $email: "alice@example.com" });
insertUser.run({ $name: "Bob",   $email: "bob@example.com" });

// Query all users
const allUsers = db.query("SELECT * FROM users").all();
console.log(allUsers);
// [{ id: 1, name: 'Alice', email: 'alice@example.com', ... }, ...]

// Query a single user
const getById = db.prepare("SELECT * FROM users WHERE id = $id");
const user = getById.get({ $id: 1 });
console.log(user?.name); // "Alice"

db.close();

When to Use Bun vs Node.js

Bun can't replace Node.js everywhere yet. Some native addons (.node files), some Webpack plugins, and a handful of npm packages that reach into Node internals can still break. This is roughly how I'd decide:

How I'd Adopt Bun (and Where I'd Hold Off)

You don't have to switch everything at once, and I wouldn't. Bun's pieces are separate enough that you can take the low-risk ones first and stop wherever things get uncomfortable.

Where I'd hold off: anything that depends on native addons, apps whose hosting platform only officially supports Node, and teams where nobody has time to chase down the occasional compatibility bug. Node is boring in a good way, with long-term support releases and a huge pool of people who've already hit your error message. Bun moves fast, which is great for features but means you should pin its version (in CI and in your Dockerfile) instead of pulling latest.

If you just want to see whether it's worth it, run bun install on a project you already have and time it against your current package manager. That takes five minutes and tells you more than any benchmark table.

Mayur Dabhi

Full Stack Developer with 5+ years of experience building scalable web applications with Laravel, React, and Node.js.