Bun

Bun is an all-in-one JavaScript and TypeScript toolkit shipped as a single executable. It is a runtime, package manager, bundler, test runner, and shell — the goal is for bun to replace node, npm/yarn/pnpm, tsc, webpack/esbuild/vite, and jest in a typical workflow.

This wiki documents the source repository — the code that produces the bun binary — not the public API reference. For end-user docs, see bun.com/docs.

What ships in the binary

A single bun executable provides:

Surface	Entry point	Wiki page
JavaScript runtime (bun run, bun ./script.ts)	src/cli/run_command.zig	Runtime
Package manager (bun install, bun add, bun pm)	src/cli/install_command.zig	Package manager
Bundler (bun build, Bun.build)	src/cli/build_command.zig	Bundler
Test runner (bun test)	src/cli/test_command.zig	Test runner
Shell (Bun.$, bun -e)	src/shell/interpreter.zig	Shell
Dev server / SSR (Bake)	src/bake/DevServer.zig	Bake (dev server)
bunx (package executor)	src/cli/bunx_command.zig	bunx
REPL (bun repl)	src/cli/repl_command.zig	REPL & misc commands

All of these share one process, one event loop, one parser, one bundler pipeline, one HTTP stack, one allocator policy. Most of the code is in src/.

Languages and engine

Bun is written in three languages:

• Zig (src/**/*.zig, ~1,200 files) — runtime core, CLI, parser/printer, bundler, package manager, shell, HTTP stack, native bindings, OS abstractions.
• C++ (src/bun.js/bindings/**/*.cpp, ~570 .cpp / ~770 headers) — JavaScriptCore bindings, Web API host objects, Node vm module, debugger glue. Bun forks WebKit's JavaScriptCore engine; the fork lives at vendor/WebKit/.
• TypeScript / JavaScript (src/js/, ~6,500 .js+.ts+.mjs+.cjs files, including Node fallbacks) — built-in JS modules (node:fs, node:http, bun:sqlite, etc.), JSC builtins, the bunx runner, the bake hot-module-replacement runtime.

The engine is JavaScriptCore (JSC) from WebKit, not V8. JSC is built once per platform from vendor/WebKit/ and statically linked. Native code calls into JSC via two layers: the Zig wrappers in src/bun.js/bindings/ and the host-object C++ code in the same directory.

Repository map

bun/
├── src/                # all first-party Bun source code
│   ├── bun.zig           # main entry point (Zig)
│   ├── cli.zig           # CLI dispatcher
│   ├── cli/              # one file per subcommand (install, run, build, test, ...)
│   ├── bun.js/           # everything that runs JavaScript
│   │   ├── api/          # Bun.* APIs (server.zig, ffi.zig, html_rewriter.zig, ...)
│   │   ├── webcore/      # Web APIs (fetch, streams, Blob, Request, Response)
│   │   ├── node/         # Node.js compat layer in Zig
│   │   ├── modules/      # _NativeModule entries for built-ins
│   │   ├── bindings/     # C++ JSC bindings + generated classes
│   │   └── event_loop/   # event loop and task queue
│   ├── js/               # built-in JS/TS modules and JSC builtins
│   ├── bundler/          # bundle_v2.zig and friends
│   ├── install/          # package manager
│   ├── shell/            # cross-platform shell
│   ├── css/              # CSS parser/printer
│   ├── http/             # HTTP/1, HTTP/2, HTTP/3, WebSocket clients
│   ├── sql/              # Postgres / MySQL clients
│   ├── bake/             # dev server + SSR runtime ("Bake")
│   ├── codegen/          # build-time TS scripts that generate Zig/C++
│   └── ...               # parser, transpiler, resolver, allocators, sys, etc.
├── vendor/              # vendored C/C++ deps (WebKit, BoringSSL, libuv, ...)
├── packages/            # workspace packages (bun-types, bun-vscode, ...)
├── test/                # test suite (~thousands of files)
├── bench/               # micro/macro benchmarks
├── scripts/             # build.ts, runner.node.mjs, machine scripts, CI helpers
├── docs/                # public documentation (bun.com/docs source)
└── build.zig            # Zig build entry; CMake delegates to this for the Zig step

The build is orchestrated by scripts/build.ts (TypeScript) which drives CMake (CMakeLists.txt is referenced from there) which in turn invokes zig build on build.zig. See Getting started.

Reading order

If you are new to the repo:

1. Start here.
2. Read Architecture for the system diagram and how the pieces talk.
3. Skim Glossary to pick up the project-specific vocabulary.
4. Set up a build via Getting started.
5. Pick a subcommand from Apps that matches your work and follow the breadcrumbs.

If you are debugging a specific behavior, jump straight to the relevant page in Apps or Systems.

Statistics

See By the numbers for current LOC, churn, and contribution stats. As of generation, the repo has ~15,190 commits, 906 unique authors, and Bun version 1.3.13.