Bun 1.2+ Knowledge Patch Skill

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

Agent Skills: Bun 1.2+ Knowledge Patch

Install this agent skill to your local

Skill Files