bun

Bun Project Skill

Instruction priority

Follow explicit user constraints and higher-priority system/developer instructions over this skill. When the user narrows scope, forbids external tools, asks for chat-only output, or gives a conflicting workflow, adapt accordingly and briefly note any meaningful deviation.

Goal

Help agents make Bun-aware technical decisions in any Bun project. This skill is about Bun itself: core features, APIs, practical gotchas, and official docs.

Bun is one executable (bun) that combines runtime, package manager, script runner, test runner, bundler, HTTP server runtime, and tooling/CLI foundation.

Core mental model:

Bun = Web-standard APIs + Bun-native APIs + Node/npm compatibility

First checks in a project

1. Confirm Bun usage: bun.lock, bunfig.toml, package.json#packageManager, scripts using bun, imports from bun:*, Bun.* APIs, or bun:test.
2. Check version when behavior matters: bun --version and, if useful, bun --revision.
3. Prefer Bun-native commands in Bun projects:
   • install: bun install
   • run file/script: bun run <file-or-script> or bun <file>
   • test: bun test
   • type-check: bunx tsc --noEmit (Bun transpiles TS; it does not type-check)
   • build: bun build ... or Bun.build()
4. Actively consult the official Bun docs whenever a task touches a Bun feature/API/CLI option: https://bun.com/docs. Do this to learn the feature in context, verify current behavior, and discover newer or unfamiliar Bun capabilities. Do not rely on assumed/inherent knowledge for implementation-level details.

Core features to remember

• Runtime: runs JS/TS/TSX directly; supports Web APIs (fetch, Request, Response, streams, Blob, URL, crypto) and many Node APIs.
• Package manager: bun install, bun add, bun remove, bun update, bunx, bun.lock, workspaces, catalogs, lockfile/CI/security features.
• TypeScript: transpilation is built in; type-check separately with TypeScript.
• Environment/config: .env* loading, bunfig.toml, preload scripts, watch/hot/debug modes.
• Test runner: bun:test, mocks/spies, snapshots, coverage, watch, filters, reporters.
• Bundler: bun build, Bun.build, loaders, CSS, HTML imports, fullstack builds, standalone HTML, executable builds, bytecode, plugins.
• Core APIs: Bun.file, Bun.write, streams, binary data, Bun.$, Bun.spawn, Bun.Glob, bun:sqlite, Bun.sql, fetch.
• Servers: Bun.serve, Web-standard Request/Response, native routes, static/file responses, cookies, CSRF, WebSockets, SSE, lifecycle methods.
• CLIs/tools: shebangs, import.meta.main, Bun.argv, stdin/stdout/stderr, exit codes, shell automation, child processes, cron, executable builds.
• Advanced/on-demand APIs: Redis, S3, password/hash/secrets, DNS/TCP/UDP, Workers, WebView, JSONL, Markdown, Image, HTMLRewriter, TOML/YAML/JSON5, FFI, transpiler, plugins.

Official-docs-first rule

For Bun-specific implementation details, actively look up the official docs before changing code or giving exact guidance. This is mandatory when:

• using a Bun API, bun:* module, CLI flag, bunfig.toml, package-manager feature, test-runner feature, bundler option, or server/routing feature;
• behavior may depend on Bun version, platform, target, or runtime mode;
• the feature might be new, advanced, or unfamiliar;
• migrating Node/npm code to Bun or debugging Bun/Node compatibility.

Use docs not only for confirmation, but also for discovery: scan nearby docs sections to detect relevant Bun-native features the agent may not know about.

Practical rules

• Prefer Web APIs first, Bun-native APIs for server/tooling gaps, Node APIs for compatibility or existing packages.
• Do not assume Node behavior is identical; test migrations and edge cases.
• Bun.file() is lazy; read via .text(), .json(), .bytes(), or .stream().
• Bun.write() can write strings, bytes, blobs, streams, files, and responses.
• Use Bun.$ for concise shell-style automation; use Bun.spawn() when you need process control, streaming, environment, cwd, stdin/stdout handling, or exit status details.
• Always check fetch() responses (res.ok) before parsing.
• In Bun servers, route precedence matters; native routes are version-sensitive, so check current docs and installed Bun version.
• For CLIs, use import.meta.main, clear stdout/stderr separation, and process.exitCode instead of abrupt exits where possible.
• For security topics, prefer built-ins (Bun.password, Bun.CSRF, cookie helpers) but check current docs and avoid inventing security designs.

Focused references

Load only the reference needed for the task:

• references/REFERENCE.md — reference index and topic routing.
• references/runtime-package-test-build.md — runtime, TS, env/config, package manager, tests, bundler.
• references/core-apis.md — file I/O, streams, fetch, shell, spawn, SQLite, SQL, globs.
• references/servers.md — Bun.serve, routing, static files, cookies, CSRF, WebSockets, SSE.
• references/clis.md — CLI and automation patterns.
• references/advanced-apis.md — Redis, S3, security, networking, content processing, native interop.