bun-knowledge-patch

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
--target=browser	Self-contained HTML

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