Tooling

The package.json scripts and helper utilities you'll actually use day-to-day.

Build

Command	Purpose
bun bd	Debug build at ./build/debug/bun-debug. Do not set a timeout.
bun bd <args>	Build, then run with <args>. The recommended way to run your build.
bun run build	Same as bun bd.
bun run build:release	Release build.
bun run build:local	Debug build with locally-built WebKit.
bun run build:asan	Debug build with AddressSanitizer.
bun run build --build-dir=path	Park the build dir somewhere safe (for benchmarking baselines).

The build script is scripts/build.ts. Read its header for the full arg-routing rules.

Test

Command	Purpose
bun bd test <file>	Run a test with the debug build.
bun bd test <fuzzy>	Fuzzy-match the file path.
bun bd test <file> -t "name"	Filter by test name.
USE_SYSTEM_BUN=1 bun test <file>	Run against the installed Bun (used to verify the bug exists on main).
bun test test/integration/bun-types/bun-types.test.ts	Type-only test, no rebuild needed.

Lint and format

Command	Purpose
bun run lint	Run all linters.
bun run prettier	Format JS/TS/MD.
bun run zig:check-all	Compile-check Zig for Linux + macOS + Windows. Use after platform-specific changes.

CI

Requires the BuildKite CLI (brew install buildkite/buildkite/bk) and a read-scoped token in BUILDKITE_API_TOKEN.

Command	Purpose
bun run ci:errors	Rendered test failures for the current branch's latest build.
bun run ci:errors '#26173'	By PR number / URL / branch / build number.
bun run ci:status	Counts of passed / failed / running jobs.
bun run ci:logs	Save full logs for failed jobs to ./tmp/ci-<build>/.
bun run ci:find	Just the build number, for composing with raw bk.
bun run ci:watch	Tail the current branch's build until it finishes.

bk directly is fine for anything else: bk build list, bk job log, bk artifacts, bk api.

If output looks wrong (mis-parsed annotation, confusing wording), fix scripts/find-build.ts rather than working around it.

PR review

bun run pr:comments
bun run pr:comments 28838
bun run pr:comments '#28838'
bun run pr:comments https://github.com/oven-sh/bun/pull/28838
bun run pr:comments --include-resolved
bun run pr:comments --json | jq '.[] | select(.user == "...")'

gh pr view --comments only shows issue-stream comments. The script above pulls all three GitHub comment endpoints and labels each entry.

Codegen

Codegen runs as part of bun bd — you don't invoke it manually. The scripts:

• src/codegen/generate-classes.ts — *.classes.ts → C++/Zig bindings.
• src/codegen/bundle-modules.ts — src/js/{node,bun,thirdparty,internal}/ → C++ headers.
• src/codegen/bundle-functions.ts — src/js/builtins/ → JSC builtin headers.
• src/codegen/cppbind.ts — [[ZIG_EXPORT]] C++ → Zig declarations.
• src/codegen/internal-module-registry-scanner.ts — module ID assignment.

After a JS-only change in src/js/, bun run build re-bundles modules without needing a Zig recompile.

Bench

bun run bench
bun run bench:all

The bench harness is under bench/ (not in test/). Run bench/runner.ts for a quick smoke; individual benchmarks can be invoked directly.

Update dependencies

bun run update-deps          # bumps oven-sh tooling deps
bun run update-test-deps     # bumps test-only deps

Vendored C/C++ deps are copied in directly (they're not git submodules). To upgrade, run the relevant scripts/build/deps/<name>.ts after changing the version pin in that file.

Useful scripts

• scripts/build.ts — the build entry. Read the header.
• scripts/find-build.ts — picks the right BuildKite build for a branch / PR.
• scripts/all-dependencies.ts — what depends on what.
• scripts/update-root-certs.ts — refresh CA bundle.

VS Code

packages/bun-vscode/ is the official extension. It uses the same inspector protocol exposed by bun --inspect. Build it with bun run build inside the package and load it as a development extension.

Editor configs

.editorconfig is at the repo root. Zig files use 4-space indent; TS / C++ use 2-space. The auto-formatter enforces both.

Troubleshooting the toolchain

• "command not found: bd" — bd is a package.json script. Run from inside the repo.
• "no debug build" — Run bun bd once first; it produces the binary.
• "build is slow" — First build on a clean checkout takes minutes (CMake configure, vendored deps, Zig compile). Subsequent builds are incremental.
• "rebuilds for no reason" — Codegen invalidations. Check git status build/<profile>/codegen/.