This page documents the bootstrap and initialization process of the Deno runtime, covering how the JavaScript execution environment is set up when a Deno process starts or when workers are created. This includes configuration of the global object, the Deno namespace, error handlers, and extension initialization.
For information about the extension system architecture itself, see Extension System Architecture. For details about worker creation and lifecycle, see Worker Creation and Lifecycle.
Bootstrap is the process of transforming a raw JavaScript isolate into a fully functional Deno runtime environment. This happens in two phases:
99_main.js module executes bootstrap functions that configure globals, set up the Deno namespace, and prepare the execution environmentThe bootstrap process differs between main workers (the initial script execution) and web workers (background threads), but shares common infrastructure.
Sources: runtime/js/99_main.js1-994
Bootstrap configuration is passed from Rust to JavaScript via the BootstrapOptions struct, which is serialized to V8 values using serde_v8. The options control runtime behavior, feature flags, and execution mode.
| Field | Type | Purpose |
|---|---|---|
deno_version | String | Version string for Deno.version.deno |
args | Vec<String> | Command-line arguments for Deno.args |
cpu_count | usize | Number of CPUs available |
log_level | WorkerLogLevel | Logging level (Error/Warn/Info/Debug) |
location | Option<ModuleSpecifier> | Sets globalThis.location |
unstable_features | Vec<i32> | Enabled unstable feature IDs |
has_node_modules_dir | bool | Whether using local node_modules |
mode | WorkerExecutionMode | Execution mode (Run/Test/Bench/Serve/etc) |
is_standalone | bool | Whether running as compiled binary |
otel_config | OtelConfig | OpenTelemetry configuration |
Sources: runtime/worker_bootstrap.rs92-246 runtime/js/99_main.js618-641
The WorkerExecutionMode enum determines runtime behavior and which APIs are available:
Sources: runtime/worker_bootstrap.rs13-59 runtime/js/99_main.js606-616
The bootstrapMainRuntime() function initializes the main worker environment. This is called for the initial script execution and has additional responsibilities compared to worker bootstrap.
1. Remove Imported Ops - Ops already imported via ext:core/ops are deleted from the global ops object to avoid duplication:
2. Set Global Properties - Different properties are set based on whether it's a main worker or web worker:
3. Configure Location - If --location flag is provided, set globalThis.location, otherwise make it writable:
4. Event Handler Registration - Standard event handlers for window lifecycle:
5. Deno Serve Handler - For deno serve mode, register automatic server detection:
Sources: runtime/js/99_main.js618-823
The bootstrapWorkerRuntime() function initializes web worker environments. It's simpler than main runtime bootstrap but shares common infrastructure.
Workers need to poll for messages from their parent. The polling infrastructure is set up during bootstrap:
runtime/js/99_main.js207-259 - pollForMessages() async function
runtime/js/99_main.js907-908 - Exposed on globalThis
| Aspect | Main Runtime | Worker Runtime |
|---|---|---|
| Prototype | Window.prototype | DedicatedWorkerGlobalScope.prototype |
Deno.mainModule | Available | Deleted after bootstrap |
close() | windowClose() - exits process | workerClose() - terminates worker |
| Message handling | Not applicable | pollForMessages() loop |
importScripts() | Not available | Available for classic workers |
Sources: runtime/js/99_main.js825-954
Both main and worker bootstrap call runtimeStart() which performs initialization common to all runtime types:
The formatException() function customizes how uncaught exceptions are displayed:
Unhandled promise rejections are processed through registered handlers:
runtime/js/99_main.js411-459 - Handler registration and processing
Sources: runtime/js/99_main.js394-459
The global object (globalThis) is configured differently for main workers and web workers through property descriptors.
Properties common to both window and worker contexts are defined in windowOrWorkerGlobalScope:
runtime/js/99_main.js477 - Application of shared properties
These include Web APIs like console, fetch, setTimeout, crypto, etc.
runtime/js/99_main.js867-882 - Worker-specific property definitions
Sources: runtime/js/99_main.js477-496 runtime/js/99_main.js742-750 runtime/js/99_main.js867-882
The Deno namespace is built by aggregating APIs from multiple sources and applying feature flags.
The following properties are defined with getters on the Deno namespace:
| Property | Source | Memoized |
|---|---|---|
pid | op_bootstrap_pid() | Yes |
ppid | op_ppid() | No |
noColor | op_bootstrap_no_color() | No |
args | op_bootstrap_args() | Yes |
mainModule | op_main_module() | No |
exitCode | os.getExitCode() / os.setExitCode() | N/A (getter/setter) |
Unstable APIs are added based on the unstableFeatures array from bootstrap options:
runtime/js/99_main.js791-794 - Main runtime unstable features
runtime/js/99_main.js910-913 - Worker runtime unstable features
The Deno.internal symbol provides access to internal APIs not intended for public use:
Sources: runtime/js/99_main.js562-598 runtime/js/99_main.js791-794 runtime/js/99_main.js810
Error handling is established early in the bootstrap process through multiple mechanisms.
Standard Deno error classes are registered with deno_core:
runtime/js/99_main.js323-363 - Error class registration
Custom builders for DOMException errors with specific names:
runtime/js/99_main.js345-392 - DOMException error builders
runtime/js/99_main.js411-412 - Handler registration
runtime/js/99_main.js416-459 - Handler implementation
Sources: runtime/js/99_main.js323-459
Extensions provide ops and ESM modules to the runtime. They are initialized before bootstrap functions run.
Extensions are registered in dependency order (defined in deno_runtime/lib.rs). Key extensions include:
The deno_fs extension is initialized with a FileSystemRc implementation:
ext/fs/lib.rs26-105 - Extension definition
ext/fs/30_fs.js1-955 - JavaScript implementation
The deno_io extension sets up standard I/O resources:
ext/io/lib.rs228-295 - Extension initialization with stdio setup
Sources: ext/fs/lib.rs26-105 ext/io/lib.rs228-295 runtime/js/99_main.js6-93
When Node.js compatibility is enabled, an additional nodeBootstrap() function is called after main bootstrap.
The nodeBootstrap() function receives:
| Option | Value (Main) | Value (Worker) |
|---|---|---|
usesLocalNodeModulesDir | hasNodeModulesDir | hasNodeModulesDir |
runningOnMainThread | true | false |
argv0 | From options | From options |
workerId | N/A | Worker ID |
maybeWorkerMetadata | N/A | Deserialized metadata |
nodeDebug | From options | From options |
runtime/js/99_main.js812-819 - Main runtime Node bootstrap
runtime/js/99_main.js939-949 - Worker runtime Node bootstrap
Node.js global variables are added to the Deno.internal object:
runtime/js/99_main.js561 - Node globals assignment
Sources: runtime/js/99_main.js561 runtime/js/99_main.js812-819 runtime/js/99_main.js939-949 runtime/js/99_main.js956-957
The runtime performs a "warmup" pass during snapshot creation to pre-initialize code paths and improve startup performance.
At the end of 99_main.js, bootstrap functions are called with warmup = true:
This executes the bootstrap code during snapshot creation without actually configuring the runtime, ensuring:
Sources: runtime/js/99_main.js983-993
Sources: runtime/js/99_main.js1-994 runtime/worker_bootstrap.rs1-247
Refresh this wiki