Contributing and Development Setup

Relevant source files

This page provides technical details for setting up a local development environment, building Bun from source, and participating in the development workflow. Bun is primarily written in Rust (the core runtime, bundler, and package manager), with C++ for JavaScriptCore (JSC) integration, and TypeScript for built-in modules and type definitions CLAUDE.md1-2 CLAUDE.md110-115

System Requirements

Building Bun requires approximately 10GB of free disk space for the repository and build artifacts CONTRIBUTING.md1

Operating Systems: Bun supports macOS, Linux (Debian, Ubuntu, Arch, Fedora, openSUSE), and Windows CONTRIBUTING.md23-45
LLVM: LLVM 21.1.8 is strictly required. This version is enforced by the build system; mismatching versions cause memory allocation failures at runtime CONTRIBUTING.md97-102
Rust: Bun requires a specific nightly toolchain pinned in rust-toolchain.toml. The build scripts use rustup to manage this CONTRIBUTING.md47-51
Bun: A release build of Bun must be pre-installed, as it is used for code generation, transpilation, and minification during the build process CONTRIBUTING.md53-54
Alternative (Nix): A Nix flake is provided to set up an isolated, reproducible environment containing all dependencies CONTRIBUTING.md7-17

Sources: CONTRIBUTING.md1-125 CLAUDE.md1-2 rust-toolchain.toml1-10

Build System Architecture

Bun utilizes a custom TypeScript-based build orchestration system that generates build.ninja files. The scripts in scripts/build/ describe the build, while Ninja performs the actual compilation and linking scripts/build/CLAUDE.md1-4

Build Configuration and Flags

The build is controlled by a flat Config struct resolved at configure-time scripts/build/config.ts73-176 Compiler and linker flags are managed in scripts/build/flags.ts, which uses a flat table with predicates to determine when a flag is applied scripts/build/flags.ts4-40

Build Toolchain and Commands

The primary entry point for developers is the bd (Build Debug) package script CLAUDE.md7-16

Command	Action	Output Path
`bun bd`	Incremental debug build	`./build/debug/bun-debug` CLAUDE.md8
`bun run build`	Full debug build (clones submodules)	`./build/debug/bun-debug` CONTRIBUTING.md156-159
`bun run build:release`	Optimized release build	`./build/release/bun` CLAUDE.md23
`bun run build:local`	Debug build using local WebKit source	`./build/debug/bun-debug` CLAUDE.md24

Development Workflow Diagram

The following diagram illustrates the relationship between source entities and the build process.

"Development Workflow and Code Entities"

Sources: CLAUDE.md110-115 CONTRIBUTING.md156-163 scripts/build/bun.ts1-40 scripts/build/rust.ts1-25

Development Workflow

AI Assistant Integration (CLAUDE.md)

The CLAUDE.md file contains instructions for AI assistants. A critical rule is build-then-exec: any bun run build* command accepts trailing arguments passed to the built executable, ensuring you always test the newly built binary CLAUDE.md18-25

IDE Setup (VSCode)

VSCode is the recommended IDE. Configuration is provided in .vscode/settings.json and .vscode/launch.json.

Extensions: Recommended extensions include rust-analyzer, clangd, and CodeLLDB .vscode/extensions.json4-13
Rust Analyzer: Automatically picks up the workspace Cargo.toml and pinned nightly toolchain CONTRIBUTING.md168-170
Debugging: Use CodeLLDB with the provided launch configurations .vscode/launch.json14-107
Pathing: Add ./build/debug to your $PATH to use bun-debug globally CONTRIBUTING.md172-176

Debugging and Logging

Scoped Logs: Enable specific debug logs using BUN_DEBUG_<scope>=1. Use BUN_DEBUG_QUIET_LOGS=1 to suppress non-explicit logs CONTRIBUTING.md194
JSC Validation: To verify C++/JSC exception state consistency, use BUN_JSC_validateExceptionChecks=1 and BUN_JSC_dumpSimulatedThrows=1 CLAUDE.md13-14
GC Stress: BUN_GARBAGE_COLLECTOR_LEVEL=2 forces GC to run after every expect() in tests .vscode/launch.json3

Sources: CONTRIBUTING.md166-202 CLAUDE.md13-25 .vscode/launch.json1-107

Testing Suite

Bun's test suite is extensive and organized by module. Tests are written in TypeScript using bun:test CLAUDE.md69

Test Categories

Path	Description
`test/js/bun/`	Bun-specific API tests (HTTP, SQL, Shell, FFI) CLAUDE.md53
`test/js/node/`	Node.js compatibility suite CLAUDE.md54
`test/js/web/`	Web API standards (Fetch, WebSocket, Streams) CLAUDE.md55
`test/cli/`	CLI command behavior (Install, Run, Build) CLAUDE.md56
`test/bundler/`	Transpiler and Linker logic CLAUDE.md57
`test/regression/`	Reproductions for specific GitHub issues CLAUDE.md62

Test Implementation Standards

Tests rely on the harness module for reproducible environments and utility functions like bunExe(), bunEnv, and tempDir() test/CLAUDE.md28-33 test/CLAUDE.md186-196

"Testing Entity Mapping"

Sources: CLAUDE.md53-66 test/CLAUDE.md28-143

Critical Testing Rules

Never use bun test directly: Use bun bd test <file> to ensure your local changes are included in the binary being tested CLAUDE.md11 test/CLAUDE.md15
No Hardcoded Ports: Always use port: 0 to prevent collisions CLAUDE.md100 test/CLAUDE.md21
No setTimeout: Tests should await conditions, not time passing CLAUDE.md105 test/CLAUDE.md21
Leak Detection: LeakSanitizer (ASAN) is enabled in CI, except for specific tests listed in test/no-validate-leaksan.txt test/no-validate-leaksan.txt1-150
Verification: Verify tests fail with USE_SYSTEM_BUN=1 and pass with the debug build to ensure the test is valid CLAUDE.md106

Sources: