Core JavaScript Runtime

Relevant source files

• src/jsc/JSType.rs
• src/jsc/VirtualMachine.rs
• src/jsc/bindings/IsolatedModuleCache.cpp
• src/jsc/bindings/IsolatedModuleCache.h
• src/jsc/bindings/JSCTaskScheduler.cpp
• src/jsc/bindings/JSCTaskScheduler.h
• src/jsc/bindings/JSMockFunction.cpp
• src/jsc/bindings/NodeVM.cpp
• src/jsc/bindings/NodeVM.h
• src/jsc/bindings/NodeVMModule.cpp
• src/jsc/bindings/NodeVMModule.h
• src/jsc/bindings/NodeVMScript.cpp
• src/jsc/bindings/NodeVMScript.h
• src/jsc/bindings/ZigException.cpp
• src/jsc/bindings/ZigGlobalObject.cpp
• src/jsc/bindings/ZigGlobalObject.h
• src/jsc/bindings/webcore/DOMClientIsoSubspaces.h
• src/jsc/bindings/webcore/DOMIsoSubspaces.h
• src/jsc/bindings/webcore/Worker.cpp
• src/jsc/web_worker.rs
• src/runtime/bake/BakeGlobalObject.cpp
• src/runtime/cli/test/parallel/runner.rs
• src/runtime/dispatch.rs
• src/runtime/hw_exports.rs
• src/runtime/jsc_hooks.rs
• src/runtime/node/node_fs_stat_watcher.rs
• src/runtime/test_runner/timers/FakeTimers.rs
• src/runtime/timer/Timer.rs
• src/runtime/timer/WTFTimer.rs
• src/runtime/timer/mod.rs
• src/runtime/timer/timer_object_internals.rs
• test/js/bun/test/test-timers-gc-spin-fixture.ts
• test/js/bun/test/test-timers.test.ts
• test/js/node/watch/fs.watchFile.test.ts
• test/js/web/timers/timer-heap-atomics-fixture.ts
• test/js/web/timers/timer-heap-atomics-teardown-fixture.ts
• test/js/web/timers/timer-heap-gc-fixture.ts
• test/js/web/timers/timer-heap-race.test.ts

The Core JavaScript Runtime is the foundation of Bun's JavaScript execution environment. It encompasses the integration with WebKit's JavaScriptCore (JSC) engine, the implementation of the global object, the event loop for asynchronous operations, module loading and resolution, and memory management across the Rust, C++, and Zig boundaries.

Architecture Overview

Bun's runtime is built across three primary languages:

• Rust (src/**/*.rs): Core runtime logic, JS-visible APIs, the bundler, and the module resolution subsystem.
• C++ (src/jsc/bindings/*.cpp): JavaScriptCore bindings, Web API implementations (e.g., Headers, Fetch), and memory-critical glue code.
• Zig (src/*.zig): Historical implementation layer. While much logic has migrated to Rust, Zig remains involved in the process bootstrapping and the high-level VirtualMachine lifecycle.

The runtime uses a tiered dispatch system to bridge these layers. Low-tier crates like bun_jsc define opaque vtables, while the high-tier bun_runtime implements the actual logic (e.g., timers, I/O) and provides them as link-time-resolved symbols src/runtime/jsc_hooks.rs1-21

Runtime Component Hierarchy

Diagram: System names and their corresponding code entities

Sources: src/jsc/VirtualMachine.rs137-152 src/runtime/jsc_hooks.rs68-100 src/jsc/bindings/ZigGlobalObject.cpp1-209 src/runtime/node/node_fs_watcher.rs1-100

Global Object and JSC Integration

ZigGlobalObject is the central C++ class that extends WebKit's JSC::JSGlobalObject. It serves as the globalThis in Bun and provides the execution context for all JavaScript code.

• Host Integration: Bun uses RuntimeHooks to provide high-tier implementations for operations like transpilation and fetching builtin modules src/runtime/jsc_hooks.rs16-19
• Namespace Assembly: The globalThis.Bun object and various Web APIs (like URL, Headers, AbortController) are registered on the ZigGlobalObject during initialization src/jsc/bindings/ZigGlobalObject.cpp61-148
• FFI and Bindings: Bun provides deep integration for native code, including JSFFIFunction for fast foreign function calls and NapiEnv for Node-API compatibility src/jsc/bindings/ZigGlobalObject.cpp112-156

For details, see Global Object and JSC Integration.

Sources: src/runtime/jsc_hooks.rs1-40 src/jsc/bindings/ZigGlobalObject.cpp61-148 src/jsc/bindings/ZigGlobalObject.cpp112-156

Event Loop and Async Operations

Bun's event loop manages the scheduling of microtasks, timers, and asynchronous I/O.

• Timer Management: Each VirtualMachine owns a timer::All instance src/runtime/jsc_hooks.rs68-70 This manages setTimeout and setInterval using an optimized heap-based scheduler src/runtime/timer/mod.rs1-20
• Fake Timers: For testing, Bun implements a FakeTimers system that can override Date.now and manually advance the clock src/runtime/test_runner/timers/FakeTimers.rs20-42
• Stat Watchers: Bun implements an efficient StatWatcherScheduler that uses a dedicated thread pool and linked-list queue to monitor file changes without blocking the main event loop src/runtime/node/node_fs_stat_watcher.rs48-73

For details, see Event Loop and Async Operations.

Sources: src/runtime/jsc_hooks.rs68-70 src/runtime/timer/mod.rs1-20 src/runtime/test_runner/timers/FakeTimers.rs20-42 src/runtime/node/node_fs_stat_watcher.rs48-73

Module System and Resolution

Bun features a highly optimized module resolver and loader capable of handling ESM, CommonJS, and TypeScript.

• Resolution Subsystem: The bun_resolver crate implements the logic for traversing node_modules, handling package.json fields, and resolving tsconfig.json paths.
• Module Loading: JSModuleLoader handles the fetching and transpilation of source code. The LoaderHooks bridge this to the Rust-based transpiler src/runtime/jsc_hooks.rs18-19
• Worker Support: Bun supports WebWorker and Node.js worker_threads, with a dedicated threading model where the WebWorker struct is owned by the C++ WebCore::Worker src/jsc/web_worker.rs1-21

For details, see Module System and Resolution.

Sources: src/runtime/jsc_hooks.rs18-19 src/jsc/web_worker.rs1-21 src/jsc/bindings/ZigGlobalObject.cpp38-43

Memory Management and Garbage Collection

Bun employs a multi-layered memory management strategy to balance performance and safety.

• Allocation: Bun utilizes mimalloc for high-performance allocations. Per-VM state is often boxed and leaked in init_runtime_state to ensure it remains valid for the lifetime of the VirtualMachine src/runtime/jsc_hooks.rs59-67
• GC Integration: The VirtualMachine tracks RareData and other structures that the JavaScriptCore Garbage Collector needs to visit. The runtime uses ThreadSafeRefCounted for objects shared across threads, such as StatWatcherScheduler src/runtime/node/node_fs_stat_watcher.rs49-51
• Arena Allocators: For short-lived operations like transpilation, Bun uses a transpiler_arena (a bun_alloc::Arena) to minimize overhead src/runtime/jsc_hooks.rs92

For details, see Memory Management and Garbage Collection.

Sources: src/runtime/jsc_hooks.rs59-99 src/jsc/VirtualMachine.rs137-152 src/runtime/node/node_fs_stat_watcher.rs49-51

Code Entity Mapping

The following diagram maps high-level runtime concepts to the specific code entities that implement them.

Sources: src/jsc/VirtualMachine.rs137-152 src/runtime/jsc_hooks.rs68-99 src/jsc/web_worker.rs78-142 src/jsc/bindings/JSMockFunction.cpp117-140