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)