The Complete Guide to Bun: From Beginner to Expert

bun run index.tsx       # TS and JSX supported out of the box
bun install <pkg>       # install a package
bun build ./index.tsx   # bundle a project for browsers
bun test                # run tests
bunx cowsay 'Hello!'    # execute a package

// Bun supports both Node.js style and Web-standard APIs
import { readFileSync } from "fs"; // Node.js API
const response = await fetch("https://api.example.com"); // Web-standard API

# npm install: ~170ms startup time
npm install
 
# Bun install: ~6ms startup time — 28x faster
bun install

import { expect, test } from "bun:test";
 
test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

bun build ./index.tsx --outdir ./out

# macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash
 
# Windows
powershell -c "irm bun.sh/install.ps1 | iex"
 
# Using npm
npm install -g bun
 
# Using Homebrew
brew install oven-sh/bun/bun
 
# Using Docker
docker pull oven/bun

bun --version

# Run a file
bun run index.js
bun run index.ts       # TypeScript runs directly
bun run index.tsx      # JSX runs directly
 
# Shorthand: you can omit "run"
bun index.tsx
 
# Run a package.json script
bun run dev
bun run build
 
# Watch mode
bun --watch run index.tsx

# Install all dependencies
bun install
 
# Add a package
bun add react
bun add react@19.1.1     # specific version
bun add -d typescript     # dev dependency
 
# Remove a package
bun remove react
 
# Global install
bun install -g cowsay
 
# CI/CD mode (frozen lockfile)
bun ci
# equivalent to bun install --frozen-lockfile

{
  "trustedDependencies": ["esbuild", "sharp"]
}

# Hoisted mode (traditional npm behavior)
bun install --linker hoisted
 
# Isolated mode (similar to pnpm, prevents phantom dependencies)
bun install --linker isolated

import { expect, test, describe } from "bun:test";
 
describe("Math operations", () => {
  test("addition", () => {
    expect(1 + 1).toBe(2);
  });
 
  test("async test", async () => {
    const data = await fetch("/api/data");
    expect(data.ok).toBe(true);
  });
});

# Run all tests
bun test
 
# Run a specific test file
bun test ./test/math.test.ts
 
# Filter tests by name
bun test --test-name-pattern "addition"
 
# Watch mode
bun test --watch
 
# Concurrent execution
bun test --concurrent
 
# Coverage report
bun test --coverage

import { beforeAll, beforeEach, afterEach, afterAll, test } from "bun:test";
 
beforeAll(() => {
  /* runs once before all tests */
});
beforeEach(() => {
  /* runs before each test */
});
afterEach(() => {
  /* runs after each test */
});
afterAll(() => {
  /* runs once after all tests */
});

import { test, expect, mock } from "bun:test";
 
const random = mock(() => Math.random());
 
test("mock test", () => {
  const val = random();
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

# CLI usage
bun build ./index.tsx --outdir ./out
bun build ./index.tsx --outdir ./out --target browser
bun build ./index.tsx --outdir ./out --watch

// JavaScript API
const result = await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  target: "browser", // "browser" | "bun" | "node"
});
// result => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }

# Compile into a standalone executable
bun build --compile ./index.tsx --outfile myapp
./myapp  # runs directly, no Bun installation needed

const server = Bun.serve({
  port: 3000,
  routes: {
    // Static routes
    "/api/status": new Response("OK"),
 
    // Dynamic routes (with parameters)
    "/users/:id": (req) => {
      return new Response(`Hello User ${req.params.id}!`);
    },
 
    // Per-HTTP method handlers
    "/api/posts": {
      GET: () => {
        const posts = db.query("SELECT * FROM posts").all();
        return Response.json(posts);
      },
      POST: async (req) => {
        const body = await req.json();
        return Response.json({ created: true, ...body }, { status: 201 });
      },
    },
 
    // Wildcard route
    "/api/*": Response.json({ message: "Not found" }, { status: 404 }),
  },
 
  // Fallback for unmatched routes
  fetch(req) {
    return new Response("Not Found", { status: 404 });
  },
});
 
console.log(`Server running at ${server.url}`);

// Hot-reload routes (without server restart)
server.reload({
  routes: {
    "/api/version": () => Response.json({ version: "2.0.0" }),
  },
});
 
// Stop the server
await server.stop(); // graceful stop
await server.stop(true); // force stop
 
// Get client IP
const address = server.requestIP(req);

// Read files
const text = await Bun.file("./hello.txt").text();
const buffer = await Bun.file("./data.bin").arrayBuffer();
const json = await Bun.file("./config.json").json();
 
// Check if a file exists
const exists = await Bun.file("./config.json").exists();
 
// Get file info
const stat = await Bun.file("./data.bin").stat();
console.log(stat.size);
 
// Write files
await Bun.write("./output.txt", "Hello, World!");
await Bun.write("./data.bin", new Uint8Array([1, 2, 3]));
 
// Stream writing
const file = Bun.file("./large.txt");
const writable = file.writer();
writable.write("chunk 1\n");
writable.write("chunk 2\n");
writable.end();

import { Database } from "bun:sqlite";
 
const db = new Database(":memory:"); // or "mydb.sqlite"
 
// Create a table
db.run("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");
 
// Insert data (prepared statement)
const insert = db.prepare("INSERT INTO users (name, email) VALUES ($name, $email)");
insert.run({ $name: "Alice", $email: "alice@example.com" });
insert.run({ $name: "Bob", $email: "bob@example.com" });
 
// Query data
const user = db.query("SELECT * FROM users WHERE name = $name").get({ $name: "Alice" });
// => { id: 1, name: "Alice", email: "alice@example.com" }
 
const allUsers = db.query("SELECT * FROM users").all();
// => [{ id: 1, name: "Alice", ... }, { id: 2, name: "Bob", ... }]
 
// Transactions
const insertMany = db.transaction((users) => {
  for (const user of users) {
    insert.run(user);
  }
});
 
insertMany([
  { $name: "Charlie", $email: "charlie@example.com" },
  { $name: "Diana", $email: "diana@example.com" },
]);

db.run("PRAGMA journal_mode = WAL;");

class User {
  name: string;
  email: string;
  get displayName() {
    return this.name.toUpperCase();
  }
}
 
const users = db.query("SELECT name, email FROM users").as(User).all();
console.log(users[0].displayName); // "ALICE"

const server = Bun.serve({
  port: 3000,
  fetch(req, server) {
    // Upgrade HTTP request to WebSocket
    if (server.upgrade(req)) return;
    return new Response("WebSocket upgrade failed", { status: 500 });
  },
  websocket: {
    open(ws) {
      console.log("Client connected");
      ws.subscribe("chat");
    },
    message(ws, message) {
      // Publish to all clients subscribed to "chat"
      server.publish("chat", message);
    },
    close(ws) {
      console.log("Client disconnected");
      ws.unsubscribe("chat");
    },
  },
});

// Reads directly; .env file is auto-loaded
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;
 
// Load from a specific file
// bun --env-file=.env.production run index.ts

import { $ } from "bun";
 
// Run a command
const result = await $`echo "Hello, World!"`.text();
console.log(result); // "Hello, World!\n"
 
// Piping
const files = await $`ls`.text();
const filtered = await $`grep .ts <<< ${files}`.text();
 
// With error handling
try {
  await $`git push`;
} catch (e) {
  console.error("Push failed:", e);
}

// Spawn a child process
const proc = Bun.spawn(["echo", "Hello"], {
  stdout: "pipe",
  stderr: "pipe",
});
 
const text = await new Response(proc.stdout).text();
console.log(text); // "Hello\n"
 
const exitCode = await proc.exited;
console.log(`Exit code: ${exitCode}`);

const lib = dlopen("./mylib.so", {
  add: {
    args: ["int", "int"],
    returns: "int",
  },
});
 
console.log(lib.symbols.add(1, 2)); // 3

# Step 1: Install Bun in an existing Node.js project
npm install -g bun
 
# Step 2: Install dependencies with Bun (generates bun.lock)
bun install
 
# Step 3: Run scripts with Bun
bun run dev    # replaces npm run dev
bun test       # replaces npm test
 
# Step 4: For scripts using Node.js CLI tools, use the --bun flag
bun run --bun vite

const plugin = Bun.plugin({
  name: "my-plugin",
  target: "browser",
  setup(build) {
    build.onLoad({ filter: /\.custom$/ }, (args) => {
      const content = Bun.file(args.path).text();
      return {
        contents: `export default ${JSON.stringify(content)}`,
        loader: "js",
      };
    });
  },
});

# bunfig.toml
 
# Runtime configuration
[run]
# Preload modules
preload = ["./setup.ts"]
 
# Package manager configuration
[install]
# Install optional dependencies
optional = true
# Install dev dependencies
dev = true
# Installation strategy
linker = "hoisted"
# Minimum release age (supply chain attack prevention)
minimumReleaseAge = 259200
 
# Test configuration
[test]
# Coverage
coverage = true
# Retry count
retry = 3
# Timeout in milliseconds
timeout = 5000

import myReactApp from "./index.html";
 
Bun.serve({
  routes: {
    "/": myReactApp,
    "/api/data": () => Response.json({ message: "Hello" }),
  },
});

const worker = new Worker(new URL("./worker.ts", import.meta.url));
 
worker.postMessage({ type: "process", data: [1, 2, 3] });
 
worker.onmessage = (event) => {
  console.log("Worker result:", event.data);
};

bun init
# Select "Blank" template, then:
bun add express
bun add -d @types/express

import express from "express";
const app = express();
 
app.get("/", (req, res) => {
  res.json({ message: "Hello from Bun!" });
});
 
app.listen(3000, () => console.log("Running on http://localhost:3000"));

import { Database } from "bun:sqlite";
 
const db = new Database(":memory:");
db.run("CREATE TABLE todos (id INTEGER PRIMARY KEY, text TEXT, done INTEGER DEFAULT 0)");
 
const server = Bun.serve({
  port: 3000,
  routes: {
    "/api/todos": {
      GET: () => {
        const todos = db.query("SELECT * FROM todos").all();
        return Response.json(todos);
      },
      POST: async (req) => {
        const { text } = await req.json();
        db.run("INSERT INTO todos (text) VALUES (?)", [text]);
        return Response.json({ success: true }, { status: 201 });
      },
    },
    "/api/todos/:id": (req) => {
      const todo = db.query("SELECT * FROM todos WHERE id = ?").get(req.params.id);
      if (!todo) return new Response("Not Found", { status: 404 });
      return Response.json(todo);
    },
  },
});

import { test, expect, beforeAll } from "bun:test";
import { Database } from "bun:sqlite";
 
let db: Database;
 
beforeAll(() => {
  db = new Database(":memory:");
  db.run("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
  db.run("INSERT INTO users (name) VALUES ('Alice')");
});
 
test("query user", () => {
  const user = db.query("SELECT * FROM users WHERE name = ?").get("Alice");
  expect(user).toBeDefined();
  expect(user.name).toBe("Alice");
});
 
test("all users", () => {
  const users = db.query("SELECT * FROM users").all();
  expect(users).toHaveLength(1);
});