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](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](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](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](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](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](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](references/testing.md)