| name | bun |
| description | Bun runtime patterns. Use when running bun commands, working with package.json/bun.lock, writing TypeScript scripts under Bun, or developing Claude Code plugins. |
Bun
bunx
Put --bun before the executable name to force the Bun runtime over Node shebangs. Use -p/--package when the binary name differs from the package name (e.g., bunx -p @angular/cli ng).
See references/bunx.md
Lockfile
bun.lock is a text-based lockfile. Resolve merge conflicts by deleting it and running bun install to regenerate — never merge it.
See references/lockfile.md
Resolution
Runtime flags must precede the script path: bun --cwd ./packages/app run dev. Never use .js extensions in TypeScript imports — Bun resolves them natively.
See references/resolution.md
Shell
Bun.$ is a tagged template for shell execution. Use response methods (.text(), .json(), .lines()) to extract output, .nothrow() to handle failures without exceptions, and pipe/redirect syntax to compose commands.
See references/shell.md
Subprocess
Bun.spawn spawns subprocesses with streaming I/O; Bun.spawnSync runs synchronously. Configure stdin/stdout/stderr, environment variables, and working directory. Check exitCode for errors.
See references/spawn.md
File I/O
Bun.file() creates file handles with .text(), .json(), .arrayBuffer(), and .stream() methods. Bun.write() writes content to files or stdout/stderr. Both support streaming for large files.
See references/file-io.md
Testing
Bun runs tests in a single process. Use describe/it/test for structure, expect matchers for assertions, lifecycle hooks (beforeEach, afterEach) for setup/teardown, mock() for function mocking, and .toMatchSnapshot() for snapshot testing. Set AGENT=1 to suppress passing test output.
See references/testing.md
