Bun

Bun

Use this skill when work touches the Bun runtime, package manager, test runner, bundler, bunfig.toml, Node compatibility, or migrating installs/scripts to Bun.

Workflow

1. Inspect the local Bun surface:
   • bun --version / bun --revision (stable line is 1.3.x; prefer upgrading toward current stable when APIs matter).
   • Lockfile: bun.lock (text, default since 1.2) vs legacy bun.lockb.
   • package.json scripts, workspaces, catalogs, overrides, trustedDependencies.
   • bunfig.toml (project + optional global), .npmrc, @types/bun / tsconfig "types": ["bun"].
   • Whether code uses Bun-native APIs (Bun.serve, bun:sqlite, …) or Node APIs (node:*).
2. For day-to-day how-to, progressive adoption, and troubleshooting, follow usage-guide.md first.
3. Refresh docs when versions drift or the task touches Redis/SQL/HTTP3/FFI or lockfile/linker defaults. Start from source-map.md.
4. Route deeper detail:
   • Runtime APIs, HTTP, files, shell, SQLite/Redis/S3/SQL: runtime-apis.md.
   • Install, lockfile, workspaces, trust, bunx, CI: package-manager.md.
   • bun test, bun build, --compile, init/create: test-bundler-build.md.
   • Node compat, globals, watch/hot, bunfig overview: node-compat-config.md.
5. Prefer Bun-native APIs and bun / bunx commands for greenfield Bun projects. Keep Node APIs when the codebase is already Node-shaped and works.
6. Verify with the narrowest useful bun command (bun test, bun run, bun ci, or a focused Bun.serve smoke).

Core Judgment

• Bun is runtime + package manager + test runner + bundler in one binary — not “just a faster Node”.
• Prefer bun / bunx over npm / npx / yarn / pnpm in commands for Bun projects.
• Commit bun.lock. CI install: bun ci (frozen lockfile).
• Dependency lifecycle scripts are blocked by default unless trusted — check bun pm untrusted after adding native packages (sharp, etc.).
• New workspace lockfiles often default to isolated linker; legacy migrations may stay hoisted via configVersion.
• Prefer Bun.serve for new HTTP services; know the default 10s idle timeout (SSE needs server.timeout(req, 0)).
• Prefer bun:sqlite / Bun.SQL / Bun.redis over heavier Node clients when writing Bun-first code.
• bun --watch hard-restarts; bun --hot soft-reloads (globalThis persists) — good for servers.
• Bun flags go before run: bun --watch run dev, not bun run dev --watch.
• Bun.env is a launch snapshot; prefer process.env when values change at runtime.
• bun build does not typecheck or emit .d.ts — run tsc when types matter.
• bun:ffi and several features (HTTP/3, Redis pub/sub, Workers terminate) are experimental — prefer Node-API natives for production FFI.

Verification

Prefer repository-owned commands. For meaningful Bun work, cover the relevant subset:

• bun --version and confirm lockfile / linker expectations.
• Focused bun test (path or -t pattern); coverage / junit when CI cares.
• bun ci or bun install --frozen-lockfile after lockfile edits.
• Smoke bun run <entry> or Bun.serve with port: 0 + fetch.
• After native deps: bun pm untrusted / trust as needed.
• After bun build / --compile: run the output on the target platform.
• Node-compat migrations: run the same suite under Bun and note partial modules.

Report which checks ran, which did not, and any Bun version assumptions that remain.