Glossary

Terms that appear repeatedly in the Bun source tree.

Build & tooling

• bd — Short for "build & debug". The bun bd package.json script compiles a debug build (./build/debug/bun-debug) and forwards trailing args. Always preferred over invoking bun-debug by hand.
• build:release — Optimized build (./build/release/bun) without ASan. Roughly 2x faster builds and 2x faster runtime than debug.
• debug-local — A debug profile that builds against vendor/WebKit/ instead of a prebuilt JSC archive. Used when stepping through JSC.
• bun-pr <PR> — A bunx package that downloads a release build from a GitHub Actions artifact for the given PR and adds it to $PATH. See CONTRIBUTING.md.
• ZIG_EXPORT — Attribute on a C++ function that tells src/codegen/cppbind.ts to generate a Zig binding automatically.
• *.classes.ts — Declarative file that describes a JS-visible class (constructor, prototype, getters, methods, structure flags). Consumed by src/codegen/generate-classes.ts to produce both Zig and C++ glue. The actual implementation is in a sibling *.zig file.
• *.bind.ts — Bindgen v2 file for one-off cross-language function exports. See src/codegen/bindgen.ts.

Runtime concepts

• JSC — JavaScriptCore, WebKit's JS engine. Bun forks WebKit at vendor/WebKit/ and statically links JSC.
• ZigGlobalObject — The C++ JSC::JSGlobalObject subclass that backs every Bun JavaScript realm. Defined in src/bun.js/bindings/ZigGlobalObject.cpp. Caches Bun-specific structures and ties Zig and JSC together.
• VM — src/bun.js/VirtualMachine.zig. One per realm. Holds the event loop, module loader, transpiler caches, and lifecycle. The main process uses one; each Worker thread gets its own.
• Event loop — src/bun.js/event_loop.zig. Wraps either uSockets (POSIX) or libuv (Windows). Drains microtasks and dispatches Task variants.
• Microtask — Promise reaction queued by JSC. Drained by the event loop after every macrotask.
• Strong / Weak — Refs to JSC values that hold or do not hold the value alive across GC. src/bun.js/Strong.zig, src/bun.js/Weak.zig.
• Iso subspace — A JSC garbage-collection partition. Each Bun-defined JSC class registers an iso subspace in ZigGlobalObject so its instances live in the right GC bucket.
• Hardcoded module — A built-in module like node:fs or bun:sqlite. Declared in src/bun.js/HardcodedModule.zig and src/bun.js/modules/. Implementation may be in JS (src/js/) or native (Zig/C++).
• Internal module registry — Numeric IDs assigned to built-in modules at code-gen time. Used to dispatch import "bun:fs" to the right native loader.
• Microtask queue, deferred queue, "next tick" — Three execution levels: JSC's microtask queue, Bun's deferred task queue (cross-thread events), and Node's process.nextTick queue (drained between microtasks). All three are managed in event_loop.zig.

Parsing & bundling

• E.* and S.* — Expression and statement AST tags from src/ast/. Many parser methods take an E.Foo and return an E.Bar.
• Symbol / Ref — Identifier handles produced by the lexer. A Ref is a (source_index, inner_index) pair pointing into Symbol storage. The bundler renames symbols by editing this storage rather than rewriting the AST.
• Source index — Numeric ID for a parsed file in the bundler's graph. Used as an index into the chunk graph (LinkerGraph).
• Chunk — A bundle output unit. src/bundler/Chunk.zig describes shared chunks, entry-point chunks, and CSS chunks.
• Tree shaking — Symbol-level dead-code elimination. The bundler walks the symbol use graph and only emits symbols reachable from the entry points.
• Macro — A function called at bundle time. Marked with import { x } from "module" with { type: "macro" }. Implemented in src/bundler/macros/ and the parser.
• HMR — Hot module replacement. Bun's dev server (Bake) recompiles changed modules and patches the running module graph.

Package manager

• Lockfile — Binary-encoded resolution graph at the repo root: bun.lock (text v1) or bun.lockb (binary, legacy). Code in src/install/lockfile/.
• Hoisted install — npm-compatible flat node_modules/ layout. Default until 1.3+. src/install/hoisted_install.zig.
• Isolated install — pnpm-style symlinked node_modules/.bun/. src/install/isolated_install.zig.
• Trusted dependencies — Packages allowed to run lifecycle scripts without prompting. Defaults from src/install/default-trusted-dependencies.txt.
• Workspace — A package with "workspaces": [...] patterns in its package.json. Resolved via src/install/workspace_match.zig (in lockfile/).
• Patch — A user-supplied patch applied to an installed package, via bun patch. Stored under patches/. src/install/patch_install.zig.

Shell

• Interpreter — src/shell/interpreter.zig. Executes a parsed shell AST against the runtime's event loop.
• Builtin — A shell command implemented in Bun (cd, echo, mv, rm, ...). Not a forked process. src/shell/builtin/.
• States — Each shell construct (pipeline, if, command, ...) is a state machine with an init/run/done method. src/shell/states/.
• Yield — The cooperative async primitive used by shell states. src/shell/Yield.zig.

Bake (dev server / SSR)

• Bake — The internal name for Bun's full-stack dev server and SSR runtime. src/bake/.
• DevServer — src/bake/DevServer.zig, the long-running HTTP server that hot-reloads modules.
• Framework router — src/bake/FrameworkRouter.zig. Matches an incoming request to a server component or page.
• Server components — React 19+ server components. Implemented via src/bundler/ServerComponentParseTask.zig and the Bake runtime.

Test runner

• itBundled — Helper for bundler tests. Defines an inline source tree, runs Bun.build, and asserts on the output.
• tempDir — Helper from test/harness.ts that creates a using-scoped temp directory.
• bunEnv, bunExe — From test/harness.ts. Provide the env vars and binary path that tests should use to spawn child processes.
• USE_SYSTEM_BUN=1 — Env var that flips bunExe() from the debug build back to the system bun. Used to verify a regression test fails before a fix.
• normalizeBunSnapshot — test/harness.ts helper that strips ANSI codes, line numbers, and tempdir paths from output for stable snapshots.

Native infrastructure

• uSockets — uWebSockets's socket-event library. Vendored at packages/bun-usockets/. Drives the HTTP/TCP/UDP/TLS event loop on POSIX.
• libuv — Cross-platform async I/O. Vendored at vendor/libuv/. Used on Windows for the event loop and pervasively for filesystem watchers.
• mimalloc — Microsoft's allocator. Vendored at vendor/mimalloc/. Replaces the system allocator everywhere except where JSC owns the memory.
• lol-html — Cloudflare's streaming HTML rewriter. Vendored at vendor/lolhtml/. Powers Bun.HTMLRewriter.
• picohttpparser — Single-file HTTP/1.1 parser. Vendored at vendor/picohttpparser/.
• lshpack / lsqpack — HPACK (HTTP/2) and QPACK (HTTP/3) header coders.
• lsquic — LiteSpeed's QUIC stack. Powers fetch() over HTTP/3.
• TinyCC — Vendored at vendor/tinycc/. Provides bun:ffi cc JIT compilation.

Misc

• Output.zig — The repo's stdout/stderr abstraction. Use Output.prettyln, Output.errorln, etc., not std.io. Supports ANSI styling via <r><red>...</r> markup.
• Output.scoped — Generates a debug-log function gated on BUN_DEBUG_<scope> and visibility (.hidden / .visible).
• Bun__panic — The crash entry point. Routes to src/crash_handler.zig which captures a stack trace and uploads it to bun.report.
• Fast paths — Performance-critical functions often have a fastPath and a slowPath. Inspect both — frequently a regression hides in the slow path.
• Output.prettyln — Pretty-print with markup. The companion Output.prettyErrorln is the equivalent for stderr.
• bun.report — The crash-report receiver service. Stack traces from crash_handler.zig are POSTed there (opt-in).

Acronyms

Acronym	Meaning
HMR	Hot Module Replacement
FFI	Foreign Function Interface
JSC	JavaScriptCore
VM	Virtual Machine (JSC realm wrapper)
ESM	ECMAScript Modules
CJS	CommonJS
HPACK	Header compression for HTTP/2
QPACK	Header compression for HTTP/3
QUIC	Transport protocol underpinning HTTP/3
WPT	Web Platform Tests
ASan / LSan	Address / Leak Sanitizer
LTO	Link-time optimization