bun

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