guides

347 notes in this subject, read out of this brain and free to use. This is page 5 of 6.

Testing Library usage example in Bun tests

With Happy DOM and Testing Library preloaded, you can render components and query the DOM: `import { test, expect } from "bun:test"; import { screen, render } from "@testing-library/react"; import { MyComponent } from "./myComponent"; test("Can use Testing Library", () => { render(MyComponent); const myComponent = screen.getByTestId("my-component"); expect(myComponent).toBeInTheDocument(); });`

Optional cleanup after each test with Testing Library

In the Testing Library preload script, you can optionally call cleanup after each test to match Jest's behavior and ensure proper cleanup of rendered components between tests.

Detect Bun runtime with process.versions.bun

Check if `process.versions.bun` is truthy to detect whether code is running in Bun. This works in both JavaScript and TypeScript without requiring any additional type definitions. The check is: `if (process.versions.bun) { /* code runs only in Bun */ }`

Detect Bun runtime with Bun global

Check if the `Bun` global is defined using `typeof Bun !== "undefined"` to detect whether code is running in Bun. In TypeScript, this check is a type error unless `@types/bun` is installed. Install it with `bun add -d @types/bun`.

Bun processes start 4x faster than Node.js

Bun processes start 4x faster than Node.js according to its design goals.

Bun is an all-in-one toolkit for JavaScript/TypeScript

Bun is an all-in-one toolkit for developing modern JavaScript and TypeScript applications. It ships as a single executable called `bun` and includes a runtime, package manager, test runner, bundler, and script runner.

Bun runtime is a drop-in replacement for Node.js

The Bun runtime is a fast JavaScript runtime designed as a drop-in replacement for Node.js. It is written in Rust and powered by JavaScriptCore, which reduces startup time and memory usage.

Bun supports TypeScript and JSX by default

Bun can directly execute `.jsx`, `.ts`, and `.tsx` files. Its transpiler converts these to vanilla JavaScript before execution, so no build step is required.

Bun supports both ESM and CommonJS

Bun recommends ES modules (ESM) but supports CommonJS. It aims for full compatibility with both module systems.

Bun implements web-standard APIs

Bun implements standard Web APIs like `fetch`, `WebSocket`, and `ReadableStream`. Some APIs like `Headers` and `URL` directly use Safari's implementation, as Bun is powered by the JavaScriptCore engine developed by Apple for Safari.

Bun aims for Node.js compatibility

Bun aims for full compatibility with built-in Node.js globals like `process` and `Buffer`, and with Node.js modules like `path`, `fs`, and `http`. This is an ongoing effort.

Bundler supports TypeScript, JSX, React, and CSS

The Bun bundler can bundle TypeScript, JSX, React, and CSS for both browsers and servers. It supports splitting, plugins, and HTML imports.

Bun command examples

Common Bun commands: `bun run index.tsx` executes TypeScript/JSX files, `bun run start` runs the start script, `bun install <pkg>` installs a package, `bun build ./index.tsx` bundles a project, `bun test` runs tests, and `bunx cowsay 'Hello, world!'` executes a package.

CPU requirements for x64-baseline Bun binaries

x64-baseline binaries target the Nehalem architecture for older CPUs. Intel requirement: Nehalem (1st gen Core) or newer. AMD requirement: Bulldozer or newer. Baseline builds are slower than regular builds and should only be used if an 'Illegal Instruction' error is encountered.

Uninstall Bun on macOS and Linux

To remove Bun from macOS and Linux, run: `rm -rf ~/.bun`.

Bun minimum CPU requirement

Bun does not support CPUs older than the baseline target, which requires the SSE4.2 extension. Bun requires macOS 13.0 or later.

Upgrade Bun to canary build

To upgrade to the latest canary build, run: `bun upgrade --canary`. To switch back to stable, run: `bun upgrade --stable`. Canary builds are untested builds released on every commit to main and automatically upload crash reports.

Install specific version of Bun on Linux and macOS

To install a specific version of Bun on Linux and macOS, pass the git tag to the install script: `curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"`.

Install specific version of Bun on Windows

To install a specific version of Bun on Windows, pass the version number to the PowerShell install script: `iex "& {$(irm https://bun.com/install.ps1)} -Version 1.3.3"`.

CPU requirements for x64 standard Bun binaries

x64 standard binaries target the Haswell CPU architecture and require AVX and AVX2 instructions. Intel requirement: Haswell (4th gen Core) or newer. AMD requirement: Excavator or newer.

Install Bun on macOS and Linux with curl

To install Bun on macOS and Linux, run: `curl -fsSL https://bun.com/install | bash`. Linux users must have the `unzip` package installed (`sudo apt install unzip`). Kernel version 5.6 or higher is recommended; Bun runs on kernels as old as 3.10 (RHEL 7) with graceful degradation of newer syscalls.

Install Bun on Windows with PowerShell

To install Bun on Windows, run: `powershell -c "irm bun.sh/install.ps1|iex"`. Bun requires Windows 10 version 1809 or later.

Install Bun with Docker

To run Bun with Docker, pull the image and run it: `docker pull oven/bun` and `docker run --rm --init --ulimit memlock=-1:-1 oven/bun`. Image variants are available: `oven/bun:debian`, `oven/bun:slim`, `oven/bun:distroless`, and `oven/bun:alpine`. Bun provides a Docker image that supports both Linux x64 and arm64.

Verify Bun installation

To verify Bun was installed successfully, run `bun --version` to see the version number (output format: 1.x.y) and run `bun --revision` to see the precise commit hash (output format: 1.x.y+hash).

Add Bun to PATH on macOS and Linux

If Bun is not recognized as a command, add it to PATH by determining your shell (run `echo $SHELL`), opening the configuration file (~/.bashrc for bash, ~/.zshrc for zsh, ~/.config/fish/config.fish for fish), adding these lines: `export BUN_INSTALL="$HOME/.bun"` and `export PATH="$BUN_INSTALL/bin:$PATH"`, then reloading the shell configuration with `source ~/.bashrc` or `source ~/.zshrc`.

Add Bun to PATH on Windows

If Bun is not recognized on Windows, verify it is installed by running `& "$env:USERPROFILE\.bun\bin\bun" --version`. If this works but `bun --version` is not recognized, add Bun to PATH by running this PowerShell command: `[System.Environment]::SetEnvironmentVariable("Path", [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin", [System.EnvironmentVariableTarget]::User)`. Restart the terminal afterward.

Upgrade Bun

To upgrade Bun, run: `bun upgrade`. For Homebrew users, use `brew upgrade bun` instead to avoid conflicts. For Scoop users, use `scoop update bun` instead to avoid conflicts.

Bun glibc version requirement

Bun's glibc binaries require glibc 2.17 or newer. If an error like `bun: /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_... not found` is encountered, try using the musl binary instead. Bun's install script automatically chooses the correct binary for the system.

Uninstall Bun on Windows

To remove Bun from Windows, run: `powershell -c ~\.bun\uninstall.ps1`.

Recommended HTTP load testing tools

For load testing Bun.serve(), recommended tools are: bombardier (https://github.com/codesenberg/bombardier), oha (https://github.com/hatoo/oha), or http_load_test (https://github.com/uNetworking/uSockets/blob/master/examples/http_load_test.c).

mitata recommended for microbenchmarks

For microbenchmarks, mitata is the recommended tool. The project is located at https://github.com/evanwashere/mitata.

HTTP benchmarking tools must be fast enough for Bun.serve()

For load testing, you must use an HTTP benchmarking tool that is at least as fast as Bun.serve(), or results will be skewed. Node.js-based tools like autocannon are not fast enough.

hyperfine recommended for benchmarking scripts and CLI commands

For benchmarking scripts or CLI commands, hyperfine is recommended. The project is located at https://github.com/sharkdp/hyperfine.

CPU profiling with --cpu-prof flag

Use the --cpu-prof flag when running Bun to generate a .cpuprofile file that can be opened in Chrome DevTools (Performance tab → Load profile) or VS Code's CPU profiler to identify performance bottlenecks in JavaScript execution.

CPU profiling options table

CPU profiling flags: --cpu-prof (generate .cpuprofile JSON file in Chrome DevTools format), --cpu-prof-md (generate markdown CPU profile for grep/LLM analysis), --cpu-prof-name <filename> (set output filename), --cpu-prof-dir <dir> (set output directory). Combine --cpu-prof and --cpu-prof-md to generate both formats.

BUN_OPTIONS environment variable for CPU profiling

CPU profiling flags can be passed through the BUN_OPTIONS environment variable, e.g., BUN_OPTIONS="--cpu-prof-md" bun script.js

Heap profiling with --heap-prof flag

Use the --heap-prof flag to write a full V8-format heap snapshot on exit using Node.js's diagnostic filename format (Heap.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.heapprofile). Load it in Chrome DevTools via Memory tab → Load.

Heap profiling options table

Heap profiling flags: --heap-prof (write .heapprofile file on exit), --heap-prof-md (generate markdown heap profile on exit for CLI analysis), --heap-prof-name <filename> (set output filename), --heap-prof-dir <dir> (set output directory), --heap-prof-interval <bytes> (accepted for Node.js compatibility; snapshot taken once at exit). If both --heap-prof and --heap-prof-md are specified, markdown format is used.

Windows sysroot location for cross-compilation

The cross-build looks for the Windows sysroot at /opt/winsysroot or /opt/xwin automatically. To use a different location, set WINDOWS_SYSROOT=<path> environment variable or pass --winsysroot=<path> to the build command. A user-writable path lets configure manage the aliases automatically.

Cross-compiled Windows binaries testing limitation

Cross-compiled Windows executables are not run on the host (the --revision smoke test is skipped), so test them on a Windows machine or under Wine.

Windows x64 release cross-build ThinLTO support

Windows x64 release cross-builds support ThinLTO with cross-language (Rust↔C++) LTO as an opt-in feature. Enable with: bun run build --profile=windows-x64-release --lto=on. This compiles Bun's C/C++ with -flto=thin, makes rustc emit LLVM bitcode (-Clinker-plugin-lto), pulls the bun-webkit-windows-amd64-lto ThinLTO prebuilt, and links everything with rustc's bundled lld-link. There is no LTO for arm64 (no -lto WebKit prebuilt due to LLVM CodeView emitter issues with ARM64 NEON tuple registers) or for --baseline.

Cross-compile Windows binaries from Linux

To cross-compile Windows binaries from Linux, use: bun run build --profile=windows-x64 for x64 debug builds, bun run build --profile=windows-arm64 for ARM64 debug builds, bun run build --profile=windows-x64-release for x64 release builds, bun run build --profile=windows-arm64-release for ARM64 release builds. Output lands in build/debug-windows-x64/bun-debug.exe, build/release-windows-aarch64/bun-profile.exe + bun.exe, and so on. Equivalent raw flags: bun run build --os=windows --arch=aarch64

Enable script execution for Windows builds

By default, running unverified scripts is blocked on Windows. To enable script execution, run: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

Windows build system dependencies

Building Bun on Windows requires: Bun v1.1 or later (the build uses Bun to run code generators), Visual Studio Community 2022 with 'Desktop Development with C++' workload and Git, LLVM 21.1.8, Go, Rust (via rustup), NASM, Perl, Ruby, and Node.js. Install Bun with: irm bun.sh/install.ps1 | iex. Install Visual Studio with: winget install "Visual Studio Community 2022" --override "--add Microsoft.VisualStudio.Workload.NativeDesktop Microsoft.VisualStudio.Component.Git" -s msstore. Install remaining tools with Scoop: scoop install nodejs-lts go rustup nasm ruby perl ccache, then separately: scoop install llvm@21.1.8

Windows ARM64 build requires manual LLVM installation

For Windows ARM64 builds, download LLVM 21.1.8 directly from GitHub releases (the first version with ARM64 Windows builds) using: Invoke-WebRequest -Uri "https://github.com/llvm/llvm-project/releases/download/llvmorg-21.1.8/LLVM-21.1.8-woa64.exe" -OutFile "$env:TEMP\LLVM-21.1.8-woa64.exe" then Start-Process -FilePath "$env:TEMP\LLVM-21.1.8-woa64.exe" -ArgumentList "/S" -Wait

Do not use Strawberry Perl for Windows builds

Do not install Perl with WinGet or another package manager as you will likely get Strawberry Perl instead of a minimal installation. Strawberry Perl adds many utilities to $Env:PATH that conflict with MSVC and break the build. Use Scoop instead.

WebKit build dependencies on Windows

To build WebKit locally on Windows x64 (optional), install: scoop install make cygwin python. ARM64 builds do not need Cygwin because WebKit is provided as a pre-built binary.

Use vs-shell.ps1 for Windows builds

From setup onward, use a PowerShell terminal with .\scripts\vs-shell.ps1 sourced. Load the script by running: .\scripts\vs-shell.ps1. Verify it worked by checking for an MSVC-only command such as mt.exe with: Get-Command mt. Avoid installing ninja or cmake into your global path as you may end up building Bun without vs-shell.ps1 sourced.

Build Bun on Windows

Build Bun on Windows with: bun run build. After the initial build, you can use: ninja -Cbuild/debug. A successful build writes bun-debug.exe to the build/debug folder. Verify with: .\build\debug\bun-debug.exe --revision

Add Bun build to Windows PATH

After building, add the build folder to $Env:PATH to use bun-debug.exe globally. Open the Start menu, type 'Path', and use the environment variables menu to add C:\...\bun\build\debug to the user environment variable PATH. Then restart your editor (if it still does not pick up the change, log out and log back in).

WebKit extraction location on Windows builds

WebKit is extracted to build/debug/cache/webkit/ on Windows builds.

RC file build failure on Windows

If llvm-rc.exe fails to build .rc files, use rc.exe instead. Make sure you are in a Visual Studio dev terminal and check rc /? to confirm it is Microsoft Resource Compiler.

Permission denied when building bun-debug.exe on Windows

If the build fails with 'permission denied' when writing bun-debug.exe, the file is currently open. You likely have a running instance, possibly in the VS Code debugger. Close it and rebuild.

Cross-compile Windows binaries from Linux prerequisites

To cross-compile Windows binaries (x64 and arm64) from a Linux host, you need: the same LLVM version as a native build (check scripts/bootstrap.sh llvm_version_exact) with clang-cl, lld-link, llvm-lib and llvm-rc available (apt.llvm.org provides these on Debian/Ubuntu), nasm (only for Windows x64, needed for BoringSSL's x64 assembly), Rust std for Windows targets (rustup target add x86_64-pc-windows-msvc aarch64-pc-windows-msvc), and a Windows sysroot via xwin.

Windows build requires PowerShell 7, not default PowerShell

Building Bun on Windows requires PowerShell 7 (pwsh.exe), not the default powershell.exe. If problems occur, ask in the #contributing channel on the Bun Discord.

Create Windows sysroot for cross-compilation from Linux

To create a Windows sysroot for cross-compilation from Linux, install xwin with: cargo install xwin (or download a release binary). Then run: xwin --accept-license --arch x86_64,aarch64 --sdk-version 10.0.26100 --crt-version 14.44.17.14 --include-atl splat --use-winsysroot-style --preserve-ms-arch-notation --include-debug-libs --output /opt/winsysroot. Then create aliases: ln -s include "/opt/winsysroot/Windows Kits/10/Include" and ln -s lib "/opt/winsysroot/Windows Kits/10/Lib"

TypeScript configuration for Bun projects

For TypeScript support in Bun, configure `tsconfig.json` with these `compilerOptions`: `"lib": ["ESNext"]`, `"target": "ESNext"`, `"module": "Preserve"`, `"moduleDetection": "force"`, `"moduleResolution": "bundler"`, `"allowImportingTsExtensions": true`, `"verbatimModuleSyntax": true`, `"noEmit": true`.

Add LLVM to PATH on Arch Linux

On Arch Linux, if clang-21 is not in PATH, add it manually with: export PATH="$PATH:/usr/lib/llvm21/bin" (use fish_add_path if using fish shell)

Build Bun with 'bun run build' command

After cloning the repository, run 'bun run build' to build Bun. This can take a while as it downloads and builds dependencies.

Debug binary location after build

After building Bun, the binary is at ./build/debug/bun-debug. It is recommended to add this to your $PATH.

Give your agent this brain