Bun: The Fast JavaScript Runtime

# 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)"

# Print lockfile as human-readable YAML
bun bun.lockb

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

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");
    },
  },
});

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

# 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

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`);

// 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" },
    });
  },
});

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();