This page introduces Bun's architecture, its four primary features, the languages used to implement them, and the layout of the source tree. For details on installing Bun and using its CLI, see Getting Started. For setting up a development environment, see Contributing and Development Setup.
Bun is an all-in-one JavaScript and TypeScript toolkit that ships as a single executable. It provides four integrated tools:
| Tool | CLI command | Purpose |
|---|---|---|
| Runtime | bun run <file> | Execute JS/TS files directly, drop-in Node.js replacement |
| Bundler | bun build | Bundle, tree-shake, and compile JS/TS/CSS for production |
| Package Manager | bun install | npm-compatible package installation |
| Test Runner | bun test | Jest-compatible test execution |
Bun is designed as a Node.js-compatible runtime. It loads and executes TypeScript and JSX natively without a separate compilation step. The runtime is built on WebKit's JavaScriptCore (JSC) engine rather than V8.
Sources: README.md26-35 CLAUDE.md132-185
The codebase uses four languages, each with a distinct role:
| Language | Location | Role |
|---|---|---|
| Rust | src/**/*.rs | Core runtime, JS API bindings, bundler, package manager |
| C++ | src/jsc/bindings/*.cpp | JavaScriptCore bindings, Web API implementations |
| TypeScript | src/js/ | Built-in JavaScript modules (node:fs, bun:ffi, etc.) |
| Zig | src/**/*.zig | Legacy: kept as porting reference only, not compiled |
The
.zigfiles alongside many.rsfiles are the original implementation kept as a behavioral reference during an ongoing Zig→Rust port. They are not compiled and new code should not be added to them.
Sources: CLAUDE.md136-141 src/CLAUDE.md1-18
The Rust side is a Cargo workspace of approximately 200 crates rooted at Cargo.toml. The final binary is produced by linking libbun_rust.a from the bun_bin crate.
Architecture of the Rust codebase (major crates):
Sources: CLAUDE.md145-185 src/CLAUDE.md1-13
Sources: CLAUDE.md144-208 src/CLAUDE.md1-18
The Bun runtime executes JavaScript and TypeScript files. TypeScript and JSX are supported natively — no tsc or Babel required. The runtime is a Node.js-compatible drop-in replacement.
Key implementation locations:
| Component | Location |
|---|---|
| Event loop | src/event_loop/ |
JSC global object (ZigGlobalObject) | src/jsc/bindings/ |
Bun.* API namespace | src/runtime/api/BunObject.rs |
| Node.js compatibility layer | src/runtime/node/ |
| Web API implementations | src/runtime/webcore/ |
HTTP server (Bun.serve) | src/runtime/server/ |
For deep dives, see Core JavaScript Runtime, Bun Global APIs, and Node.js Compatibility Layer.
The bundler is implemented in src/bundler/. It handles JavaScript, TypeScript, JSX, CSS, and HTML. The main entry point for bundling is the BundleV2 struct. Linking is performed by LinkerContext.
Key implementation locations:
| Component | Location |
|---|---|
| Bundler orchestration | src/bundler/ |
| JS/TS parser | src/js_parser/ |
| Code printer | src/js_printer/ |
| Module resolution | src/resolver/ |
| CSS parser | src/css/ |
| Dev server / HMR | src/bake/ |
For details, see JavaScript Toolchain.
The package manager is implemented in src/install/. It produces a binary lockfile (bun.lockb) and a text lockfile (bun.lock).
Key implementation locations:
| Component | Location |
|---|---|
| Installation pipeline, lockfile | src/install/lockfile/ |
| NPM registry client | src/install/npm.rs |
| Lifecycle script runner | src/install/lifecycle_script_runner.rs |
For details, see Package Manager.
The test runner implements a Jest-compatible API via bun:test. Tests are discovered and executed by the bun test command.
Key implementation locations:
| Component | Location |
|---|---|
bun:test module (TypeScript built-in) | src/js/bun/ |
| Test runner CLI | src/runtime/cli/ |
| Expect matchers | src/runtime/ |
For details, see Testing Framework.
Sources: README.md27-43 CLAUDE.md155-185 package.json30-93
Key third-party C/C++ libraries are vendored in vendor/:
| Library | Path | Purpose |
|---|---|---|
| WebKit/JavaScriptCore | vendor/WebKit/ | JavaScript engine |
| mimalloc | vendor/mimalloc/ | Memory allocator (#[global_allocator]) |
| BoringSSL | vendor/boringssl/ | TLS and cryptography |
| libuv | vendor/libuv/ | Windows event loop, async I/O |
| zlib-ng | vendor/zlib/ | Compression (zlib-compatible) |
| lol-html | vendor/lolhtml/ | HTML rewriting (HTMLRewriter) |
| c-ares | vendor/cares/ | Async DNS |
| TinyCC | vendor/tinycc/ | FFI JIT compiler |
| libdeflate | vendor/libdeflate/ | Fast DEFLATE compression |
| Google Highway | vendor/highway/ | SIMD operations |
| libarchive | vendor/libarchive/ | tar/zip archive support |
Sources: CLAUDE.md186-210
Several C++, Rust, and Zig source files are auto-generated as part of the build and should not be edited by hand. The generators live in src/codegen/:
| Script | Output | Purpose |
|---|---|---|
src/codegen/generate-classes.ts | *.cpp, *.rs bindings | JS class bindings from *.classes.ts definitions |
src/codegen/generate-jssink.ts | Stream-related C++ classes | Writable/readable stream bindings |
src/codegen/bundle-modules.ts | Embedded module bytecode | Bundles src/js/node/, src/js/bun/, etc. |
src/codegen/bundle-functions.ts | Global function builtins | ReadableStream, Console, etc. |
For the full picture, see Code Generation Pipeline.
Sources: CLAUDE.md226-235 src/js/CLAUDE.md88-98
The src/js/ directory holds TypeScript source for built-in modules. These are bundled at build time and embedded in the binary. They are organized as:
| Directory | Contents |
|---|---|
src/js/node/ | Node.js compatibility modules (node:fs, node:path, node:events, …) |
src/js/bun/ | Bun-specific modules (bun:ffi, bun:sqlite, bun:test, …) |
src/js/thirdparty/ | NPM packages replaced by built-ins (ws, node-fetch) |
src/js/internal/ | Internal modules, not user-accessible |
src/js/builtins/ | Core JS builtins (ReadableStream, Console, Web Streams) |
These modules use special syntax:
require()with string literals only,$-prefixed JSC intrinsics, and.$call/.$applyinstead of.call/.applyto prevent prototype tampering.
Sources: CLAUDE.md237-245 src/js/CLAUDE.md1-106
The following diagram maps a bun run index.ts invocation to the code entities that handle it.
Sources: CLAUDE.md144-185 src/CLAUDE.md1-18
| Platform | Architectures |
|---|---|
| Linux | x64, arm64 (kernel ≥ 5.6 recommended, ≥ 5.1 minimum) |
| macOS | x64, Apple Silicon (arm64) |
| Windows | x64, arm64 |
The build system supports baseline CPU builds for older x64 hardware. For platform-specific bootstrapping, see Platform Support and Bootstrap.
Sources: README.md44-50
LATEST (e.g., 1.3.14).package.json version field reflects the development version (e.g., 1.4.0).packages/bun-types/ and packages/@types/bun/. See Bun API Types.scripts/ and are driven by scripts/build.ts. See CMake Build Configuration.Sources: package.json1-8 LATEST1
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.