Contributing and Development Setup

Relevant source files

• .buildkite/Dockerfile
• .clangd
• .prettierrc
• .vscode/c_cpp_properties.json
• .vscode/extensions.json
• .vscode/launch.json
• .vscode/settings.json
• .vscode/tasks.json
• CONTRIBUTING.md
• LATEST
• docs/project/building-windows.mdx
• docs/project/contributing.mdx
• flake.nix
• package.json
• scripts/github-metrics.ts
• shell.nix
• src/linker.lds
• test/bundler/bundler_bun.test.ts
• test/js/bun/test/__snapshots__/expect.test.js.snap
• test/js/bun/test/ci-restrictions.test.ts
• test/js/bun/test/snapshot-tests/new-snapshot.test.ts
• test/js/bun/test/test-only.test.ts
• test/js/node/test/parallel/test-runner-typechecking.js
• test/regression/issue/08964/08964.test.ts

This page provides technical details for setting up a local development environment, building Bun from source, and participating in the development workflow. Bun is a multi-language project primarily written in Rust (core runtime, bundler, and package manager), C++ (JavaScriptCore integration and bindings), and TypeScript (built-in modules, type definitions, and build scripts) package.json30-92 CONTRIBUTING.md47-53

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 (Ubuntu, Debian, 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 automatically 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 in flake.nix to set up an isolated, reproducible environment containing all dependencies including LLVM 21, Clang, and the required Rust toolchain flake.nix1-177 CONTRIBUTING.md7-17

Sources: CONTRIBUTING.md1-125 flake.nix1-177 package.json1-30

Build System Architecture

Bun utilizes a custom TypeScript-based build orchestration system. The scripts in scripts/build.ts and related files manage the build graph, while Ninja performs the actual compilation and linking package.json41-55 CONTRIBUTING.md151-165

Build Toolchain and Commands

The primary entry point for developers is the bd (Build Debug) package script, which enables quiet logs and incremental compilation package.json42

Command	Action	Output Path
bun bd	Incremental debug build with quiet logs package.json42	./build/debug/bun-debug
bun run build	Standard debug build package.json31	./build/debug/bun-debug
bun run build:release	Optimized release build package.json46	./build/release/bun
bun run build:asan	Release build with AddressSanitizer package.json51	./build/release-asan/bun
bun run jsc:build	Build local WebKit/JSC source package.json60	build/release-local/

Code Generation Pipeline

Bun uses several TypeScript scripts to generate high-performance bindings between Rust, C++, and JavaScript. These are often triggered automatically or can be run manually:

• generate-jssink.ts: Generates C++ code for ReadableStream interfaces CONTRIBUTING.md205
• generate-classes.ts: Produces Rust and C++ bindings for classes implemented in Rust CONTRIBUTING.md206
• generate-string-map.ts: Generates efficient Rust string maps from TypeScript definitions package.json76

"Development Workflow and Code Entities"

Sources: package.json30-92 CONTRIBUTING.md151-206 flake.nix130-152

Development Workflow

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
• C++ IntelliSense: Handled via clangd using compile_commands.json generated during the build .vscode/c_cpp_properties.json6
• Debugging: Pre-configured launch targets exist for bun test, bun run, and bun install .vscode/launch.json12-171

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 .vscode/launch.json22
• JSC Validation: To verify C++/JSC exception state consistency, use BUN_JSC_validateExceptionChecks=1 .vscode/launch.json25
• AddressSanitizer (ASAN): Used for memory safety. Options are configured via ASAN_OPTIONS in launch configs .vscode/launch.json29

Local WebKit Development

Bun pins a specific WebKit version. To work on the integration:

1. Run bun sync-webkit-source to ensure the vendor/WebKit folder is at the correct commit package.json91 .vscode/launch.json9
2. Use bun run jsc:build:debug to compile a local version of JavaScriptCore package.json61
3. Source maps in VSCode are configured to map WebKit's build paths back to the local vendor/WebKit directory .vscode/launch.json33-40

Sources: CONTRIBUTING.md166-202 .vscode/launch.json1-171 .vscode/settings.json1-150 package.json60-62

Testing Suite

Bun's test suite is extensive and is executed using the newly built binary to ensure changes are verified.

Execution Commands

• Run all tests: bun run test (uses build/debug/bun-debug by default) package.json69
• Run with ASAN: bun run testleak enables leak detection .vscode/launch.json70
• Run specific file: bun bd test path/to/file.test.ts CONTRIBUTING.md183-185

"Testing Entity Mapping"

Sources: package.json69-71 .vscode/launch.json24-30 CONTRIBUTING.md180-190

Windows Development

On Windows, developers should use PowerShell 7 and source .\scripts\vs-shell.ps1 to set up the MSVC environment docs/project/building-windows.mdx6-81

• Prerequisites: Visual Studio 2022 with C++ workload, LLVM 21.1.8, and NASM docs/project/building-windows.mdx26-39
• Cross-Compilation: Windows binaries can be cross-compiled from Linux using xwin to provide the Windows SDK and CRT docs/project/building-windows.mdx140-162

Sources: docs/project/building-windows.mdx1-180 CONTRIBUTING.md3-4