Verify Bun build with version command
To verify a Bun build worked, print its version with: build/debug/bun-debug --version, which outputs x.y.z_debug for debug builds
guides
347 notes in this subject, read out of this brain and free to use. This is page 6 of 6.
VSCode is recommended IDE for Bun development
VSCode is the recommended IDE for working on Bun. The repository includes configuration for it. After opening the repository, run 'Extensions: Show Recommended Extensions' to install recommended extensions for Rust and C++. rust-analyzer picks up the workspace Cargo.toml automatically and uses the pinned toolchain in rust-toolchain.toml for analysis.
Use 'bun bd' script to compile and run debug build
The 'bd' package.json script compiles and runs a debug build of Bun, only printing the output of the build process if it fails. Usage: 'bun bd <args>', 'bun bd test foo.test.ts', or 'bun bd ./foo.ts'
Use 'cargo check' and 'bun run watch' for faster iteration
To avoid long link times during development, use 'cargo check -p <crate>' (or 'bun run rust:check' for the whole workspace) to type-check Rust changes without linking. 'bun run watch' runs cargo check on every save.
Debug logging environment variables
Debug logging can be controlled with environment variables: 'BUN_DEBUG_<scope>=1' enables debug logging for the corresponding 'declare_scope!(<scope>, ...)' / 'scoped_log!(<scope>, ...)' logs. Set 'BUN_DEBUG_QUIET_LOGS=1' to disable all debug logging that isn't explicitly enabled. Set 'BUN_DEBUG=<path-to-file>.log' to dump debug logs into a file. Debug logs are removed in release builds.
Code generation scripts in Bun build process
Bun's build process runs several code generation scripts automatically when certain files change: (1) ./src/codegen/generate-jssink.ts generates build/debug/codegen/JSSink.cpp and JSSink.h which implement classes for interfacing with ReadableStream; (2) ./src/codegen/generate-classes.ts generates Rust & C++ bindings for JavaScriptCore classes implemented in Rust; (3) ./src/codegen/cppbind.ts scans C++ bindings and generates automatic Rust FFI wrappers (cpp.rs); (4) ./src/codegen/bundle-modules.ts bundles built-in modules like node:fs and bun:ffi; (5) ./src/codegen/bundle-functions.ts bundles globally-accessible functions like ReadableStream and WritableStream.
Certain ESM modules are implemented in JavaScript and pre-bundled
Certain modules like node:fs, node:stream, bun:sqlite, and ws are implemented in JavaScript. These live in src/js/{node,bun,thirdparty} files and are pre-bundled using Bun.
Build release version of Bun
To compile a release build of Bun, run: bun run build:release. The binaries are at ./build/release/bun and ./build/release/bun-profile.
Download and test release build from pull requests with bun-pr
The 'bun-pr' npm package allows running release builds from pull requests without building locally. Usage: 'bunx bun-pr <pr-number>', 'bunx bun-pr <branch-name>', 'bunx bun-pr https://github.com/oven-sh/bun/pull/1234566', or 'bunx bun-pr --asan <pr-number>' (Linux x64 only). The package downloads the release build from the pull request's GitHub Actions artifacts and adds it to $PATH as 'bun-${pr-number}' so you can run it directly as 'bun-1234566 --version'. You may need the 'gh' CLI installed to authenticate with GitHub.
View CI failures from terminal with BuildKite CLI
Bun's CI runs on BuildKite. Install the BuildKite CLI with 'brew install buildkite/buildkite/bk' and set 'BUILDKITE_API_TOKEN' to a read-scoped API token. The repo includes a '.bk.yaml' so 'bk' commands default to the bun pipeline. Available commands: 'bun run ci:status' (progress summary), 'bun run ci:errors' (rendered test-failure output), 'bun run ci:logs' (save full logs), 'bun run ci:watch' (watch until build finishes), 'bun run ci:find' (print build number). All accept a target: '#1234' (PR number), PR URL, branch name, or build number; without one they use the current git branch.
AddressSanitizer enabled by default in Bun debug builds on Linux and macOS
AddressSanitizer helps find memory issues and is enabled by default in debug builds of Bun on Linux and macOS. It covers Rust code, C++ bindings, and all dependencies. It makes the build take about 2x longer; if that stops productivity, disable it with 'bun run build:debug:noasan' or by passing '--asan=off' to scripts/build.ts. CI runs the test suite with at least one target built with AddressSanitizer.
Build release with AddressSanitizer
To build a release build with AddressSanitizer enabled, run: bun run build:asan
Development environment setup requires 10-30 minutes and 10GB disk space
Configuring a development environment for Bun takes 10-30 minutes depending on internet connection and computer speed. Approximately 10GB of free disk space is required for the repository and build artifacts.
Nix flake provides isolated reproducible development environment
The Bun repository includes a Nix flake as an alternative to installing dependencies manually. Running 'nix develop' provides all dependencies in an isolated, reproducible environment without requiring sudo. This can be followed by 'bun bd' to run a debug build.
macOS Homebrew dependencies for Bun development
On macOS with Homebrew, install: automake ccache cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rustup-init ruby
Ubuntu/Debian dependencies for Bun development
On Ubuntu/Debian, install via apt: curl wget lsb-release software-properties-common cmake git golang libtool ninja-build pkg-config ruby-full xz-utils
Arch Linux dependencies for Bun development
On Arch, install via pacman: base-devel cmake git go libiconv libtool make ninja pkg-config python rustup sed unzip ruby
Fedora dependencies for Bun development
On Fedora, install via dnf: clang21 llvm21 lld21 cmake git golang libtool ninja-build pkg-config ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'
openSUSE Tumbleweed dependencies for Bun development
On openSUSE Tumbleweed, install via zypper: go cmake ninja automake git icu rustup
Bun requires specific nightly Rust toolchain
Bun is written in Rust and requires a specific nightly toolchain pinned in rust-toolchain.toml. Install Rust with rustup rather than your distro's rust/cargo packages — the build scripts use rustup to automatically install and update the pinned nightly.
Release build of Bun required before development build
Before starting development, install a release build of Bun because the build uses Bun's bundler to transpile and minify code and to run code generation scripts.
ccache speeds up Bun rebuilds by caching compilation artifacts
Installing ccache caches compilation artifacts, which speeds up rebuilds. The build scripts detect and use ccache automatically if it is available. Check cache statistics with 'ccache --show-stats'.
LLVM 21.1.8 is required for Bun build
Bun requires LLVM 21.1.8 (clang is part of LLVM). The build system enforces this version as a mismatched version causes memory allocation failures at runtime.
macOS Homebrew LLVM 21 installation
On macOS with Homebrew, install LLVM 21 using: brew install llvm@21
Ubuntu/Debian LLVM 21 installation via automatic script
On Ubuntu/Debian, LLVM has an automatic installation script compatible with all versions: wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 21 all
Arch Linux LLVM 21 installation
On Arch, install LLVM 21 using: sudo pacman -S llvm clang lld
Fedora LLVM 21 installation
On Fedora, install LLVM 21 using: sudo dnf install llvm clang lld-devel
openSUSE Tumbleweed LLVM 21 installation
On openSUSE Tumbleweed, install LLVM 21 using: sudo zypper install clang21 lld21 llvm21
Verify clang-21 is in PATH with which command
After installing LLVM, verify Clang/LLVM 21 is in your path by running: which clang-21
Add LLVM to PATH on macOS Homebrew
On macOS with Homebrew, if clang-21 is not in PATH, add it manually with: export PATH="$(brew --prefix llvm@21)/bin:$PATH" (use fish_add_path if using fish shell, or path+="$(brew --prefix llvm@21)/bin" if using zsh)
macOS 'library not found for -lSystem' error
If you see 'library not found for -lSystem' error when compiling on macOS, run: xcode-select --install
Cannot find static libatomic on some distros
Bun defaults to linking libatomic statically, as not all systems have it. If building on a distro without static libatomic, enable dynamic linking with: bun run build --static-libatomic=off. The built version of Bun may not work on other systems if compiled this way.
Disable all debug logging in bun-debug
To disable all debug logging in bun-debug, use: BUN_DEBUG_QUIET_LOGS=1 bun-debug ...
Enable debug logging for specific scope in bun-debug
To enable debug logging for a specific scope in bun-debug, use: BUN_DEBUG_EventLoop=1 bun-debug ... (example shows enabling EventLoop scope output from scoped_log!(EventLoop, ...))
Find transpiled source files in bun-debug
Bun transpiles every file it runs. To see the actual executed source in a debug build, find it in /tmp/bun-debug-src/...path/to/file. For example, the transpiled version of /home/bun/index.ts is in /tmp/bun-debug-src/home/bun/index.ts
Clone and build WebKit locally for debug JSC
WebKit is not cloned by default to save time and disk space. To clone and build WebKit locally: (1) Clone WebKit: git clone https://github.com/oven-sh/WebKit vendor/WebKit; (2) Check out the pinned version: bun sync-webkit-source (reads WEBKIT_VERSION from scripts/build/deps/webkit.ts); (3) Build with local JSC: bun run build:local (handles configuring, building JSC, and building Bun). On subsequent runs, JSC rebuilds incrementally if WebKit sources changed.
WebKit local build output and configuration adjustments
When building WebKit locally, build output goes to ./build/debug-local instead of ./build/debug. Update: (1) First line in src/js/builtins.d.ts; (2) CompilationDatabase line in .clangd config to: CompilationDatabase: build/debug-local; (3) In .vscode/launch.json, many configurations use ./build/debug/, change as needed. After WebKit cloning, run 'C/C++: Select a Configuration' in VSCode so IntelliSense finds debug headers.
WebKit folder is 8GB+ in size
The WebKit folder, including build artifacts, is 8GB or larger in size.
Update WEBKIT_VERSION when making WebKit fork changes
If you make changes to Bun's WebKit fork (https://github.com/oven-sh/WebKit), you must change WEBKIT_VERSION in scripts/build/deps/webkit.ts to point to your commit hash or release tag.
Ubuntu C++ standard library issue with Clang and span
On Ubuntu versions 20.04 and earlier, Clang uses libstdc++, the C++ standard library from GCC. C++20 features like std::span are not available in GCC versions lower than 11. Running 'bun run build' may fail with 'fatal error: 'span' file not found'. Update GCC to version 11, then set it as default with: sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 and sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100
Clang cannot compile simple test program on Ubuntu
On Ubuntu, you may see error: 'The C++ compiler "/usr/bin/clang++-21" is not able to compile a simple test program.' This occurs when Clang is unable to link with a compatible C++ standard library. Update GCC to version 11 or higher to resolve.
Install libarchive on macOS when compile fails
If you see an error on macOS when compiling libarchive, run: brew install pkg-config
TypeScript 6.0 changed type discovery behavior
Starting in TypeScript 6.0, the types field in compilerOptions defaults to an empty array instead of including all @types/* packages. This means type definitions are no longer auto-discovered.
Add types field to tsconfig.json for Bun types
To fix 'Cannot find name Bun' errors after upgrading TypeScript 6.0 or later, add "types": ["bun"] to the compilerOptions section in tsconfig.json. This tells TypeScript to load type definitions from @types/bun.
Include multiple type packages in types array
The types array in compilerOptions can list multiple packages. For example, if using both Bun and React, configure: "types": ["bun", "react"]
TypeScript 7 requires explicit types configuration
TypeScript 7 carries forward the same default behavior as TypeScript 6. The types field defaults to an empty array, so the same fix applies: add "types": ["bun"] to compilerOptions. This applies even when upgrading directly from TypeScript 5 to 7.
Recommended tsconfig.json for Bun with TypeScript 6+
A full recommended tsconfig.json configuration for Bun with TypeScript 6.0 or later includes: compilerOptions with lib set to ["ESNext"], target set to "ESNext", module set to "Preserve", moduleDetection set to "force", jsx set to "react-jsx", allowJs set to true, types set to ["bun"], moduleResolution set to "bundler", allowImportingTsExtensions set to true, verbatimModuleSyntax set to true, noEmit set to true, strict set to true, skipLibCheck set to true, noFallthroughCasesInSwitch set to true, noUncheckedIndexedAccess set to true, noImplicitOverride set to true, noUnusedLocals set to false, noUnusedParameters set to false, and noPropertyAccessFromIndexSignature set to false.