Data models

A shortlist of the in-memory and on-disk data shapes a contributor will run into.

Lockfile (bun.lock)

Text JSONC format, default since v1.2. Top level:

{
  "lockfileVersion": 1,
  "workspaces": {
    "": { "name": "...", "dependencies": { ... } },
    "packages/foo": { ... }
  },
  "packages": {
    "lodash@4.17.21": { ... },
    ...
  }
}

Each entry under packages includes a resolved URL, integrity hash, peer dependencies, and OS/CPU constraints. Schema in src/install/lockfile/.

The binary form (bun.lockb) is still read for compatibility but no longer the default.

Module ID registry

src/codegen/internal-module-registry-scanner.ts walks src/js/{node,bun,thirdparty,internal}/ alphabetically and assigns each file a numeric ID. The IDs are baked into the binary; HardcodedModule.zig and InternalModuleRegistry.cpp agree on them.

AST shapes

src/ast.zig defines:

• E.* — expression nodes (Identifier, Call, Function, Literal, ...).
• S.* — statement nodes (If, For, Switch, ...).
• B.* — bindings (destructuring patterns).
• Stmt, Expr, Binding — tagged-union wrappers with location info.

Each tag is a separate Zig struct; the union dispatches via a small enum. Nodes are heap-allocated from a per-source bump arena.

Ref is a (source_index, inner_index) tuple identifying a symbol. Symbol carries kind, name, use count, and link info.

Bundler graph

src/bundler/bundle_v2.zig represents the bundle as:

• ParseTask per input file.
• Graph mapping file path → JSAst, imports, exports.
• LinkerContext with chunks, code-splitting boundaries, tree-shaking marks.

The graph is mutated across multiple worker threads with synchronisation around chunk assembly.

VirtualMachine state

src/bun.js/VirtualMachine.zig holds per-realm state:

• module_loader — the module dispatcher.
• event_loop — the per-VM EventLoop.
• transpiler_store — cached parses.
• console, process, regular_event_loop — global accessors.
• source_mappings — saved sourcemaps for stack-trace remapping.

Each Bun.serve, each worker, each REPL gets its own VM.

Crash report payload

bun.report URLs encode (base64-ish):

• Build identifier (arch, OS, Bun version, build hash).
• Captured registers.
• Backtrace addresses.
• Panic message and short tag.

Decoded at bun.report and rendered with full debug symbols. Encoder in src/crash_handler.zig.

CSS AST

src/css/css_internals.zig holds the parser's representation:

• Stylesheet — top level.
• Rule — Style, Media, Import, Keyframes, FontFace, Page, Layer, Container, Scope, ...
• Declaration — property + value list.
• Selector — list of Component (element, class, id, pseudo-class, attribute, ...).
• Value — typed by property; common ones are Color, Length, Angle, Image, String, Number.

Patch files (Bun PM)

bun patch writes a unified-diff under patches/<name>+<version>.patch. Format compatible with pnpm patch. Schema documented in src/install/PatchInfo.zig.

Testfile / coverage data

Coverage output from bun test --coverage is V8-format JSON, compatible with c8/nyc. Schema in src/cli/coverage.zig.

Inspector protocol

JSC's inspector protocol is JSON-RPC over WebSocket. Bun does not extend the protocol; everything is upstream JSC. Implementation in src/bun.js/bindings/BunInspector.cpp and the JS shim in src/bun.js/Debugger.zig.