Bun

curl -fsSL https://bun.com/install | bash   # macOS/Linux
powershell -c "irm bun.sh/install.ps1|iex"  # Windows
brew install oven-sh/bun/bun                # Homebrew
npm install -g bun                          # via npm
 
bun upgrade                  # latest; brew: brew upgrade bun
bun upgrade --canary         # nightly build
bun upgrade --stable         # back from canary
bun --version                # 1.4.2
bun --revision               # version + commit

bun init -y            # package.json, tsconfig, index.ts
bun init --react       # React app with Bun's dev server
bun add -d @types/bun  # types for the Bun global and bun:*

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "types": ["bun"],
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  }
}

preload = ["./src/instrument.ts"]  # before any bun run
# env = false                      # no automatic .env
 
[install]
exact = true                 # bun add saves "1.2.3"
linker = "isolated"          # or "hoisted"
minimumReleaseAge = 259200   # seconds (3 days)
minimumReleaseAgeExcludes = ["@types/bun"]
 
[install.scopes."@acme"]      # private registry
url = "https://npm.acme.dev/"
token = "$ACME_NPM_TOKEN"     # env var reference
 
[test]
preload = ["./test/setup.ts"]
coverage = true
coverageThreshold = 0.8
coverageSkipTestFiles = true
 
[run]
bun = true                   # "node" in scripts runs Bun

{
  "trustedDependencies": ["esbuild", "@prisma/engines"],
  "ignoreScripts": ["sharp"],
  "nativeDependencies": ["esbuild"]
}

{
  "overrides": {
    "qs": "6.13.0",
    "express": { "qs": "6.13.0" },
    "lodash@<4.17.21": "4.17.21"
  }
}

{
  "name": "acme",
  "private": true,
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^19.2.0",
      "zod": "^4.5.0"
    },
    "catalogs": {
      "testing": { "happy-dom": "^20.0.0" }
    }
  }
}

{
  "name": "@acme/ui",
  "dependencies": {
    "@acme/utils": "workspace:*",
    "react": "catalog:",
    "happy-dom": "catalog:testing"
  }
}

declare module "bun" {
  interface Env {
    DATABASE_URL: string;       // now string, not optional
    PORT?: string;
  }
}

type User = { id: string; name: string };
const users = new Map<string, User>();
 
const server = Bun.serve({
  port: 3000,             // default: $BUN_PORT/$PORT/3000
  routes: {
    "/health": new Response("ok"),        // static response
    "/favicon.ico": Bun.file("./favicon.ico"),
    "/users/:id": (req) => {             // req.params typed
      const user = users.get(req.params.id);
      return user
        ? Response.json(user)
        : new Response("not found", { status: 404 });
    },
    "/users": {                          // per-method
      GET: () => Response.json([...users.values()]),
      POST: async (req) => {
        const body = (await req.json()) as User;
        users.set(body.id, body);
        return Response.json(body, { status: 201 });
      },
    },
    "/api/*": Response.json({ error: "no route" }, {
      status: 404,
    }),
  },
  fetch() {                              // fallback
    return new Response("not found", { status: 404 });
  },
  error(err) {                           // thrown errors
    console.error(err);
    return new Response("internal error", { status: 500 });
  },
});
 
console.log(`listening on ${server.url}`);

type Data = { room: string; user: string };
 
Bun.serve({
  fetch(req, server) {
    const url = new URL(req.url);
    const ok = server.upgrade(req, {
      data: {
        room: url.searchParams.get("room") ?? "lobby",
        user: crypto.randomUUID(),
      },
    });
    return ok
      ? undefined
      : new Response("upgrade failed", { status: 400 });
  },
  websocket: {
    data: {} as Data,            // types ws.data
    open(ws) {
      ws.subscribe(ws.data.room);
    },
    message(ws, msg) {
      ws.publish(ws.data.room, `${ws.data.user}: ${msg}`);
    },
    close(ws) {
      ws.unsubscribe(ws.data.room);
    },
  },
});

Bun.serve({
  port: 443,
  tls: {
    key: Bun.file("./key.pem"),     // contents, not paths
    cert: Bun.file("./cert.pem"),
  },
  routes: {
    "/static/*": { dir: "./public" },  // 1.4: dir route
  },
  fetch: () => new Response("hi"),
});

const file = Bun.file("data.json");     // lazy, no I/O yet
await file.exists();                    // boolean
file.size;                        // bytes (0 if missing)
file.type;                              // MIME type
const cfg = (await file.json()) as { port: number };
const text = await Bun.file("notes.md").text();
const bytes = await Bun.file("img.png").bytes();
                                  // Uint8Array
 
await Bun.write("out.txt", "hello\n");  // string
await Bun.write("copy.png", Bun.file("img.png")); // copy
await Bun.write(
  "page.html",
  await fetch("https://example.com"),
);                                       // Response body
await Bun.file("out.txt").delete();
 
const log = Bun.file("app.log").writer(); // FileSink
log.write("line 1\n");
log.write("line 2\n");
await log.end();                        // flush + close
 
const glob = new Bun.Glob("src/**/*.ts");
for await (const path of glob.scan(".")) {
  console.log(path);
}

import { $ } from "bun";
 
const branch = (await $`git branch --show-current`.text())
  .trim();
const files = await $`ls *.ts`.quiet();  // Buffers
const pkg = await $`cat package.json`.json();
for await (const line of $`git log --oneline -5`.lines()) {
  console.log(line);
}
 
const name = "my file; rm -rf /";        // escaped, safe
await $`touch ${name}`.cwd("/tmp");
await $`echo $FOO`.env({ ...process.env, FOO: "bar" });
 
const res = await $`exit 3`.nothrow().quiet();
res.exitCode;                             // 3, no throw
await $`bun build ./src/index.ts > dist/out.js`;

const proc = Bun.spawn(["git", "status", "--short"], {
  cwd: ".",
  stdout: "pipe",
  stderr: "pipe",
  env: { ...process.env, GIT_PAGER: "cat" },
});
const out = await new Response(proc.stdout).text();
const code = await proc.exited;           // exit code
 
const { stdout, exitCode } = Bun.spawnSync(["ls", "-la"]);
console.log(stdout.toString(), exitCode, out, code);

import { sql, SQL } from "bun";
 
// Postgres via DATABASE_URL / POSTGRES_URL / PG* env vars
type User = { id: number; email: string; name: string };
 
const email = "a@example.com";
const rows = await sql<User[]>`
  SELECT id, email, name FROM users
  WHERE email = ${email}            -- bound parameter
  LIMIT ${10}
`;
 
const input = { email: "b@example.com", name: "Bea" };
const [created] = await sql<User[]>`
  INSERT INTO users ${sql(input)} RETURNING *
`;                                 // object -> (cols) VALUES
await sql`INSERT INTO users ${sql([input, input])}`;
await sql`UPDATE users SET ${sql(input, "name")}
          WHERE id = ${1}`;        // pick columns
await sql`SELECT * FROM users WHERE id IN ${sql([1, 2])}`;
await sql`SELECT * FROM ${sql("users")}`; // identifier
 
await sql.begin(async (tx) => {    // BEGIN ... COMMIT
  await tx`UPDATE acct SET bal = bal - 10 WHERE id = 1`;
  await tx`UPDATE acct SET bal = bal + 10 WHERE id = 2`;
});                                // throw -> ROLLBACK
 
const pg = new SQL({
  url: "postgres://app:secret@localhost:5432/app",
  max: 20,                         // pool size
  idleTimeout: 30,                 // seconds
});
const mysql = new SQL("mysql://root:pw@localhost/app");
const lite = new SQL("sqlite://app.db");
await pg.close();
console.log(rows, created, mysql, lite);

import { Database } from "bun:sqlite";
 
const db = new Database("app.db", {
  create: true,
  strict: true,         // bind { id } instead of { $id }
});
db.run("PRAGMA journal_mode = WAL;");
db.run(`CREATE TABLE IF NOT EXISTS todos (
  id INTEGER PRIMARY KEY, title TEXT NOT NULL,
  done INTEGER NOT NULL DEFAULT 0)`);
 
type Todo = { id: number; title: string; done: number };
 
const byId = db.query<Todo, { id: number }>(
  "SELECT * FROM todos WHERE id = $id",
);                      // cached prepared statement
byId.get({ id: 1 });    // Todo | null
db.query<Todo, []>("SELECT * FROM todos").all(); // Todo[]
const add = db.prepare(
  "INSERT INTO todos (title) VALUES (?)",
);
const { lastInsertRowid, changes } = add.run("Write docs");
 
const addMany = db.transaction((titles: string[]) => {
  for (const t of titles) add.run(t);
  return titles.length;
});
addMany(["a", "b", "c"]);   // all-or-nothing
db.close();
console.log(lastInsertRowid, changes);

import { redis, RedisClient } from "bun";
 
// default client reads REDIS_URL / VALKEY_URL
await redis.set("greeting", "hi");
await redis.get("greeting");          // string | null
await redis.set("session:1", "data", "EX", 3600);
await redis.incr("hits");
await redis.expire("hits", 60);
await redis.hmset("user:1", ["name", "Ada", "role", "dev"]);
await redis.hget("user:1", "name");
await redis.send("LPUSH", ["queue", "job-1"]); // any cmd
 
const pub = new RedisClient("redis://localhost:6379");
const sub = await pub.duplicate(); // subscriber: own conn
await sub.subscribe("events", (message, channel) => {
  console.log(channel, message);
});
await pub.publish("events", "deployed");
pub.close();

import { s3, S3Client } from "bun";
 
// Bun.s3 reads S3_* then AWS_* env vars
const obj = s3.file("reports/2026-09.json");  // lazy
await obj.write(JSON.stringify({ ok: true }), {
  type: "application/json",
});
const data = (await obj.json()) as { ok: boolean };
await obj.exists();
const url = obj.presign({ expiresIn: 3600 }); // sync
await obj.delete();
 
const r2 = new S3Client({
  accessKeyId: process.env.R2_KEY,
  secretAccessKey: process.env.R2_SECRET,
  bucket: "assets",
  endpoint: "https://ACCOUNT.r2.cloudflarestorage.com",
});
await r2.write("hello.txt", "hi");     // upload
const list = await r2.list({ prefix: "img/", maxKeys: 100 });
console.log(data, url, list.contents?.length);

const hash = await Bun.password.hash("hunter2");  // argon2id
await Bun.password.verify("hunter2", hash);        // true
 
await Bun.password.hash("hunter2", {
  algorithm: "bcrypt",
  cost: 12,                 // 4-31
});
 
Bun.hash("some key");       // wyhash, bigint, not crypto
const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello");
hasher.digest("hex");       // string
new Bun.CryptoHasher("sha256", "secret-key") // HMAC
  .update("payload")
  .digest("base64");
crypto.randomUUID();        // web crypto global
Bun.randomUUIDv7();         // time-ordered UUID

const result = await Bun.build({
  entrypoints: ["./src/index.tsx"],
  outdir: "./dist",
  target: "browser",        // "browser" | "bun" | "node"
  format: "esm",            // "esm" | "cjs" | "iife"
  splitting: true,          // shared chunks
  minify: true,
  sourcemap: "linked",
  external: ["react", "react-dom"],
  define: {
    __VERSION__: JSON.stringify("1.2.0"),
  },
  env: "PUBLIC_*",          // inline PUBLIC_* env vars
  naming: "[dir]/[name]-[hash].[ext]",
});
 
if (!result.success) {
  for (const log of result.logs) console.error(log);
  process.exit(1);
}
for (const out of result.outputs) {
  console.log(out.kind, out.path, out.size);
}

bun build ./src/cli.ts --compile --outfile mycli
bun build ./src/cli.ts --compile --minify --bytecode \
  --sourcemap --target=bun-linux-x64 --outfile mycli
bun build ./src/server.ts --compile \
  --asset ./public --outfile server        # embed files
bun build ./index.html --compile --target=browser \
  --outdir dist                            # one HTML file

import {
  afterEach, beforeAll, describe, expect, mock, spyOn,
  setSystemTime, test,
} from "bun:test";
import { add, fetchUser } from "./math.ts";
 
describe("add", () => {
  test("sums", () => {
    expect(add(1, 2)).toBe(3);
  });
  test.each([[1, 1, 2], [2, 3, 5]])(
    "%i + %i = %i",
    (a, b, sum) => expect(add(a, b)).toBe(sum),
  );
});
 
test("mocks and spies", async () => {
  const cb = mock((n: number) => n * 2);
  cb(2);
  expect(cb).toHaveBeenCalledWith(2);
  expect(cb.mock.calls).toEqual([[2]]);
 
  const spy = spyOn(globalThis, "fetch").mockResolvedValue(
    Response.json({ id: "1", name: "Ada" }),
  );
  await expect(fetchUser("1")).resolves.toEqual({
    id: "1",
    name: "Ada",
  });
  expect(spy).toHaveBeenCalledTimes(1);
});
 
test("snapshot", () => {
  expect({ theme: "dark", size: 2 }).toMatchSnapshot();
  expect(add(2, 2)).toMatchInlineSnapshot(`4`);
});
 
beforeAll(() => setSystemTime(new Date("2026-01-01")));
afterEach(() => mock.restore());   // undo spyOn
 
test.todo("edge cases", () => {});
test.skipIf(process.platform === "win32")("posix", () => {});
test("slow", async () => {}, { timeout: 10_000, retry: 2 });

const server = Bun.serve({
  port: Number(process.env.PORT ?? 3000),
  routes: {
    "/health": new Response("ok"),
    "/api/items/:id": {
      GET: (req) => Response.json({ id: req.params.id }),
      DELETE: () => new Response(null, { status: 204 }),
    },
  },
  fetch: () => new Response("not found", { status: 404 }),
});
 
let closing = false;
async function shutdown(signal: string) {
  if (closing) return;
  closing = true;
  console.log(`${signal}: draining`);
  const force = setTimeout(() => process.exit(1), 10_000);
  await server.stop();      // waits for in-flight requests
  clearTimeout(force);
  process.exit(0);
}
process.on("SIGINT", () => void shutdown("SIGINT"));
process.on("SIGTERM", () => void shutdown("SIGTERM"));

import { $ } from "bun";
 
const dirty = await $`git status --porcelain`.text();
if (dirty.trim()) {
  console.error("working tree not clean");
  process.exit(1);
}
 
const level = Bun.argv[2] ?? "patch"; // bun release.ts minor
await $`bun test`;
await $`bun run build`;
await $`bun pm version ${level} -m ${"release: v%s"}`;
const { version } = await Bun.file("package.json").json();
await $`git push --follow-tags`;
console.log(`released v${version}`);

import { Database } from "bun:sqlite";
 
type Todo = { id: number; title: string; done: number };
 
export function todoRepo(path = "todos.db") {
  const db = new Database(path, { strict: true }); // creates
  db.run(`CREATE TABLE IF NOT EXISTS todos (id INTEGER
    PRIMARY KEY, title TEXT NOT NULL, done INT DEFAULT 0)`);
  const byId = (sql: string) =>
    db.query<Todo, { id: number }>(sql);
  const all = db.query<Todo, []>("SELECT * FROM todos");
  const one = byId("SELECT * FROM todos WHERE id = $id");
  const add = db.query<Todo, { title: string }>(
    "INSERT INTO todos (title) VALUES ($title) RETURNING *");
  const done = byId(
    "UPDATE todos SET done = 1 WHERE id = $id RETURNING *");
  const del = byId("DELETE FROM todos WHERE id = $id");
  return {
    list: () => all.all(),
    find: (id: number) => one.get({ id }),
    create: (title: string) => add.get({ title }),
    complete: (id: number) => done.get({ id }),
    remove: (id: number) => del.run({ id }).changes > 0,
  };
}

const targets = [
  "bun-linux-x64",
  "bun-linux-arm64",
  "bun-darwin-arm64",
  "bun-windows-x64",
] as const;
 
for (const target of targets) {
  const out = await Bun.build({
    entrypoints: ["./src/cli.ts"],
    compile: { target, outfile: `./bin/mycli-${target}` },
    minify: true,
    sourcemap: "linked",
    bytecode: true,               // faster startup
    define: { VERSION: JSON.stringify("1.0.0") },
  });
  if (!out.success) throw new AggregateError(out.logs);
}

mkdir acme && cd acme && bun init -y
mkdir -p apps/api packages/utils
cd packages/utils && bun init -y && cd ../..
cd apps/api && bun init -y && cd ../..
# root package.json: "private": true,
#   "workspaces": ["apps/*", "packages/*"]
# packages/utils/package.json: "name": "@acme/utils"
bun add @acme/utils@workspace:* --filter api
bun install                     # links + one bun.lock
bun --filter '*' test           # run tests everywhere
bun --filter api dev            # one app

async function* lines(path: string) {
  const stream = Bun.file(path)
    .stream()
    .pipeThrough(new TextDecoderStream());
  let buf = "";
  for await (const chunk of stream) {
    buf += chunk;
    const parts = buf.split(/\r?\n/);
    buf = parts.pop() ?? "";         // keep partial line
    yield* parts;
  }
  if (buf) yield buf;
}
 
let errors = 0;
for await (const line of lines("huge.log")) {
  if (line.includes("ERROR")) errors++;
}
console.log(`${errors} errors`);