Bun 1.2+ Knowledge Patch

Claude's baseline knowledge covers Bun through 1.1.x. This skill provides features from 1.2 (January 2025) onwards.

Quick Reference

HTTP Server (`Bun.serve`)

Feature	Example
Routes with params	`"/api/users/:id"` → `req.params.id`
Method handlers	`{ GET: fn, POST: fn }`
Static routes	`"/health": new Response("OK")`
HTML imports	`import page from "./index.html"`
Cookies	`req.cookies.set("name", "value")`
CSRF	`await Bun.CSRF.generate(sessionId)`

See references/http-server.md for routes, cookies, dev server, WebSocket proxy.

SQL & Database

Client	Connection
PostgreSQL	`import { sql } from "bun"`
MySQL/MariaDB	`new SQL("mysql://...")`
SQLite	`new SQL(":memory:")`
Redis	`import { redis } from "bun"`

const users = await sql`SELECT * FROM users WHERE age >= ${minAge}`;
await sql`INSERT INTO users ${sql(user, "name", "email")}`;

See references/sql-database.md for tagged templates, dynamic columns, Redis pub/sub.

S3 Storage (`Bun.s3`)

const file = s3.file("path/file.txt");
await file.text();  // Same API as Bun.file()
await file.write("data");
const url = s3.presign("file", { expiresIn: 3600 });

See references/s3-storage.md for bucket listing, upload options.

Test Runner (`bun:test`)

Feature	API
Fake timers	`jest.useFakeTimers()`
Concurrent tests	`test.concurrent()`
Retry flaky	`test("name", fn, { retry: 3 })`
Type testing	`expectTypeOf(x).toBeString()`
vi global	`vi.fn()`, `vi.mock()`, `vi.spyOn()`

See references/test-runner.md for matchers, mocking, configuration.

Package Manager

Command	Purpose
`bun outdated`	View outdated deps
`bun audit`	Security scan
`bun why <pkg>`	Dependency path
`bun pm pkg get/set`	Manage package.json
`bun pm version patch`	Bump version

See references/package-manager.md for workspaces, catalogs, linker modes.

Bundler (`bun build`)

Flag	Purpose
`--compile`	Standalone executable
`--target=bun-*`	Cross-compile
`--production`	Production HTML build
`--metafile` / `--metafile-md`	Bundle analysis
`--feature=X`	Compile-time flags

See references/bundler.md for plugins, JSX config, virtual files.

New APIs

API	Purpose
`Bun.markdown`	MD → HTML/React
`Bun.YAML`	YAML parse/stringify
`Bun.JSON5`	JSON5 with comments
`Bun.Archive`	Tar creation/extraction
`Bun.Terminal`	PTY support
`Bun.secrets`	OS credential storage

See references/new-apis.md for JSONC, JSONL, compression, text utilities.

Runtime & CLI

Feature	Example
Spawn timeout	`Bun.spawn({ cmd, timeout: 1000 })`
CPU profiling	`bun --cpu-prof script.js`
Heap profiling	`bun --heap-prof script.js`
Fetch proxy	`fetch(url, { proxy: "http://..." })`

See references/runtime-cli.md for spawn options, profiling, CLI flags.

Node.js Compatibility

API	Status
`fs.glob`	Supported
`node:http2`	Supported
`node:vm`	SourceTextModule, SyntheticModule
`node:inspector`	Profiler API
`ReadableStream.json()`	Direct consumption

See references/node-compat.md for full compatibility details.

Reference Files

File	Contents
`http-server.md`	Routes, static, cookies, HTML imports, dev server
`sql-database.md`	Postgres, MySQL, SQLite, Redis clients
`s3-storage.md`	S3 client, presigned URLs, bucket listing
`test-runner.md`	Matchers, mocking, fake timers, concurrent
`package-manager.md`	Install, audit, workspaces, catalogs
`bundler.md`	Compile, plugins, metafile, feature flags
`new-apis.md`	Markdown, YAML, JSON5, Archive, Terminal
`node-compat.md`	fs.glob, vm, inspector, streams
`runtime-cli.md`	Spawn, profiling, CLI flags

Critical Examples

Full-Stack Server with Routes

import homepage from "./index.html";  // Auto-bundles JS/CSS
import { sql } from "bun";

Bun.serve({
  routes: {
    "/": homepage,
    "/api/users/:id": (req) => {
      const { id } = req.params;
      return Response.json({ id });
    },
    "/api/users": {
      GET: async () => Response.json(await sql`SELECT * FROM users`),
      POST: async (req) => {
        const { name } = await req.json();
        const [user] = await sql`INSERT INTO users (name) VALUES (${name}) RETURNING *`;
        return Response.json(user);
      },
    },
  },
});

Cookies

// In route handler
req.cookies.set("session", token, { httpOnly: true, sameSite: "strict" });
req.cookies.get("session");
req.cookies.delete("session");

SQL Dynamic Columns

// Insert/update specific columns from object
await sql`INSERT INTO users ${sql(user, "name", "email")}`;
await sql`UPDATE users SET ${sql(user, "name")} WHERE id = ${user.id}`;

// WHERE IN with array
await sql`SELECT * FROM users WHERE id IN ${sql([1, 2, 3])}`;

Test Runner Essentials

import { test, expect, jest, mock } from "bun:test";

test("with fake timers", () => {
  jest.useFakeTimers();
  setTimeout(() => {}, 1000);
  jest.advanceTimersByTime(1000);
  jest.useRealTimers();
});

test.concurrent("runs in parallel", async () => {});
test("retry flaky", () => {}, { retry: 3 });