bun-dev

Bun Dev

The single Bun skill: self-contained knowledge (below) + an opinionated rule set (rules/) + an optional native audit/fix engine (codex-dev bun). It works with zero tooling; the Power Tools section adds automation when codex-dev is installed.

Product summary

Bun is an all-in-one JavaScript/TypeScript toolkit: a fast runtime (drop-in Node.js replacement on JavaScriptCore), package manager, bundler, and test runner, all shipped as one bun binary. Key files: bunfig.toml (config), bun.lock (text lockfile, default since Bun 1.2), package.json. Primary commands: bun run, bun install / bun ci, bun build, bun test. Full docs: https://bun.com/docs (agent index: https://bun.com/docs/llms.txt).

When to use

• Runtime: execute .ts/.tsx/.jsx/.js directly (bun run <file> or bun <file>).
• Package manager: bun install / bun add / bun ci; lockfile + workspace mgmt.
• Bundler: bun build for browsers/servers; single-file executables (--compile).
• Test runner: Jest-compatible bun test with scale flags for CI.
• Servers / IO: Bun.serve(), Bun.file(), Bun.write(), bun:sqlite, Bun.$.
• Monorepos: bun install, bun run --filter, --workspaces, --parallel.
• Vercel: deploy Functions on the Bun runtime (Beta).

Quick reference

Essential commands (full cheatsheet: references/ref-bun-cli-cheatsheet.md):

Task	Command
Run a file / script	bun index.ts / bun run start
Install deps	bun install (writes bun.lock)
Deterministic CI install	bun ci
Add / remove	bun add react / bun add -d @types/bun / bun remove react
Audit deps	bun audit
Run tests	bun test (--coverage, --shard=M/N, --changed)
Build a bundle	bun build ./index.ts --outdir ./dist
Execute a package	bunx <bin>

Decision guidance

bun run vs bun <file>:

Scenario	Use
Script from package.json	bun run start
A file directly	bun index.ts (or bun run index.ts)
A system command / package bin	bun run <cmd> / bunx <bin>

hoisted vs isolated linker (see pm-linker-and-streaming-install):

Linker	Use when
hoisted	Traditional flat node_modules; default for single packages.
isolated	Strict, pnpm-style isolation; prevents phantom deps; faster in monorepos.

Bun.serve() vs a framework, and bun build vs bun run:

Choice	Use when
Bun.serve()	Simple APIs/static servers, zero deps (Bun runtime only, not Vercel).
Express/Hono/Elysia	Middleware, validation, ecosystem integrations.
bun run	Executing source directly (dev, scripts, CLIs).
bun build	Bundling for production, single-file executables, browser output.

Bun as runtime vs Bun as package-manager only is the operating-model spine - see runtime-bun-vs-node-choose and references/ref-bun-package-manager-fallbacks.md.

Gotchas

• Lockfile is text now: Bun 1.2+ writes bun.lock; bun.lockb is legacy. Commit the lockfile; migrate binaries with bun install --save-text-lockfile --frozen-lockfile --lockfile-only.
• Lifecycle scripts disabled by default: bun install skips postinstall for security; add trusted packages to trustedDependencies in package.json.
• run flags go before the script: bun --watch run dev works; bun run dev --watch passes --watch to the script.
• require() + top-level await: a file using top-level await cannot be require()'d; use import / dynamic import().
• Env vars in bundles: bun build does not inline process.env unless you pass --env inline (or --env PUBLIC_*).
• Bun.serve() idle timeout: closes idle connections after ~10s; set idleTimeout (or server.timeout(req, 0)) for SSE / long-lived streams.
• Workspaces need names: every workspace package must have a name in its package.json.
• --bun to force Bun for Node-shebang bins: bun run --bun <bin> (or [run] bun = true in bunfig.toml) - see runtime-bun-run-bun-flag.
• Bun.serve() is unsupported on Vercel Functions - see vercel-bun-runtime-limitations.

Rules (opinionated operating model)

Open a rule for the "do this / not that" with exact commands. Full list: rules/_index.md. Route by priority:

Priority	Category	Prefix	Key rules
1	Package manager + lockfiles	pm-	pm-no-mixed-lockfiles, pm-commit-bun-lockb, pm-bun-install-ci-frozen-lockfile, pm-linker-and-streaming-install, pm-bun-audit-security
1	Runtime selection	runtime-	runtime-bun-vs-node-choose, runtime-bun-run-bun-flag, runtime-bun-shell, runtime-env-files
1	Vercel Bun runtime	vercel-	vercel-bun-runtime-enable, vercel-bun-runtime-limitations, vercel-nextjs-bun-runtime-scripts
2	Scripts + monorepos	scripts-	scripts-bun-run-parallel-sequential, scripts-bun-filter-and-workspaces
2	TypeScript + tooling	tsconfig-, tooling-	tsconfig-bun-recommended, tsconfig-bun-types, tooling-bunfig
3	Testing	test-	test-bun-test-runner, test-bun-retry, test-mocking-and-spying
3	Build + bundling	build-	build-bun-build-bundler, build-compile-executables, build-bun-compile-browser
4	Performance	perf-	perf-prefer-bun-native-apis
5	Migration + troubleshooting	migrate-, troubleshooting-	migrate-node-to-bun-checklist, troubleshooting-esm-cjs-and-exports

Power Tools (optional - requires codex-dev)

When the codex-dev binary is installed, the native engine audits, safe-fixes, validates, and keeps references current. Skip this section entirely if you only need the knowledge and rules above.

Quick start:

codex-dev --json bun audit --root .          # report Bun findings
codex-dev --json bun fixes plan --root .     # preview safe fixes (diffs + hashes)
codex-dev --json bun fixes apply --root .    # apply safe rewrites (+ rollback artifact)
codex-dev --json bun validate run --root . --fail-on warn

Full command surface:

• codex-dev bun audit --root .: report Bun findings.
• codex-dev bun rules list: print rule ids.
• codex-dev bun rules show <rule-id>: print one rule.
• codex-dev bun fixes plan --root .: safe fix candidates with hashes and diffs.
• codex-dev bun fixes apply --root .: apply safe rewrites; rollback artifact under external dev-skills state.
• codex-dev bun validate plan --root .: print validation commands.
• codex-dev bun validate run --root . --fail-on warn: audit then validate.
• codex-dev bun benchmark --root .: time audit and fix planning.
• codex-dev bun references status: inspect reference hashes and integrity.
• codex-dev bun references plan: fetch vendor docs and preview changed references.
• codex-dev bun references sync: refresh tracked references and rebuild indexes.
• codex-dev bun doctor: inspect paths, version pin, and integrity.
• codex-dev tool import: import an external JSON report into a task capsule.

Platform state: config bun-platform.config.json (keys: disabledRules, severityOverrides, adapters, includePaths, excludeDirs, baseline, maxFiles, maxBytes, validationCommands, writeCache); external config/state/cache under ${XDG_*}/dev-skills/bun-platform. Audit cache is read-only unless --write-cache; safe fixes write rollback artifacts under external state, never in the repo. Example template: assets/templates/bun-platform.config.example.json.

References

Prefer rules for decisions; references for exact commands or API details. Start at references/index.md.

Topic	Reference
CLI + workflow cheatsheet	references/ref-bun-cli-cheatsheet.md
Built-in APIs cheatsheet	references/ref-bun-builtins-cheatsheet.md
Latest release notes	references/ref-bun-release-notes-latest.md
Capability map	references/ref-bun-capabilities-latest.md
Package-manager fallbacks	references/ref-bun-package-manager-fallbacks.md
Vercel Bun runtime	references/ref-vercel-bun-runtime.md

Freshness: vendored references are snapshots for a pinned Bun version. For anything newer or not covered here (e.g. Bun.WebView, Bun.cron, markdown entrypoints), consult the live docs at https://bun.com/docs/llms.txt rather than assuming the snapshot is current. With codex-dev, refresh snapshots via codex-dev bun references plan then codex-dev bun references sync.

Verification checklist

Before submitting Bun work:

• bun install resolves cleanly; bun.lock is committed (single lockfile).
• bun test passes (bun test --coverage if coverage is required).
• bun run build (or equivalent) succeeds.
• bunfig.toml / tsconfig.json match project needs (linker, moduleResolution).
• @types/bun installed for TypeScript; bun run (no args) lists scripts.
• bun audit reviewed for advisories.
• With codex-dev: codex-dev --json bun audit --root . is clean or triaged.