Deno Administrator & Developer Guide

This guide is the operator-and-developer reference for the Deno runtime: how it is built, how the source is organized, how to deploy and operate it, what its security model guarantees, and how to extend or contribute to it. Every fact is taken from the source tree at commit 7529c84 (Deno CLI version 2.7.12).

1. Executive Summary

Deno is a JavaScript / TypeScript / WebAssembly runtime distributed as a single self-contained binary. The codebase is a 70+ crate Rust workspace combining V8 (the JavaScript engine), Tokio (the async runtime), and a substantial set of in-house Rust crates that implement Web APIs, Node compatibility, the package management system, the language tooling, and the editor language server. The whole binary statically links V8.

Top-level facts:

The Deno CLI binary (cli/main.rs) is just deno::main() — a thin wrapper that calls into the deno library crate (cli/lib.rs). Everything else is layered crates.

Note

This guide focuses on the project as it is checked in. Deno Deploy (the hosted runtime) is a separate product and is treated here only as a destination for deno deploy.

2. Architecture

2.1 Layered Architecture

+----------------------------------------------------------------------+
|                            cli/ (binary)                             |
|  CLI parsing (clap), tools/* (run, fmt, lint, test, compile, ...),   |
|  factory wiring, LSP, type-checker driver                            |
+----------------------------------------------------------------------+
|                    runtime/ (deno_runtime crate)                     |
|  MainWorker, WebWorker, Deno.* namespace, permissions enforcement,   |
|  bootstrap JS, integrates ext/* into a JsRuntime                     |
+----------------------------------------------------------------------+
|     ext/ (32 crates: web/fetch/net/http/fs/crypto/node/webgpu/...)   |
|  Each crate contributes ops + JS/TS bindings for one Web API or      |
|  Node compatibility surface; loaded as deno_core::Extension          |
+----------------------------------------------------------------------+
|                    libs/core/ (deno_core crate)                      |
|  JsRuntime, ExtensionBuilder, op2 macro, ModuleLoader, snapshotting, |
|  the ops bridge between JS and Rust                                  |
+----------------------------------------------------------------------+
|                              v8 crate                                |
|  Rust bindings to the V8 JavaScript engine (statically linked)       |
+----------------------------------------------------------------------+

Below the engine, Tokio drives all async I/O. Above the CLI, no other layers exist — the binary IS the user interface.

2.2 Component Inventory

cli/ — the user-facing binary

runtime/ — the embeddable runtime (deno_runtime crate)

The runtime/README.md notes that this crate is deliberately a slimmed-down version of the CLI: it omits TypeScript type-checking, the doc/lint/fmt tools, and CLI argument parsing — it provides only "JavaScript execution with Deno's operating system bindings (ops)." Third parties embed this crate to get a Deno-compatible MainWorker without dragging in the whole cli/.

ext/ — Web platform and Node compatibility extensions (32 crates)

Each ext/<name> crate contributes ops + JS bindings for one Web API surface (or Node-compatibility surface). They are loaded as deno_core::Extension instances when the JsRuntime is built.

The naming convention is consistent: ext/<name>/lib.rs defines an Extension via deno_core::Extension::builder(); ext/<name>/<name>.js (or .ts) is the JS portion; ops are written in Rust with the #[op2] macro from libs/ops.

libs/ — shared library crates (24 crates)

These are the crates that the CLI and the runtime depend on. Several are also published independently to crates.io (deno_core, deno_ast, deno_lockfile, etc.).

tests/ — integration test infrastructure

2.3 Request Lifecycle: deno run main.ts

$ deno run --allow-net main.ts
        |
        v
cli/main.rs::main()  --> deno::main() (cli/lib.rs)
        |
        v
flags_from_vec_with_initial_cwd(args)   parses clap, returns Flags struct
        |
        v
CliFactory::from_flags(flags)           lazy DI container
        |
        v
factory.create_main_worker_factory()    builds LibMainWorkerFactory
        |   - Resolves deno.json (if present)
        |   - Builds module loader (handles file://, https://, jsr:, npm:, node:)
        |   - Builds permission set from flags + deno.json
        |   - Builds NPM installer if needed
        |
        v
worker.create_main_worker(...)          MainWorker (deno_runtime)
        |   - Constructs JsRuntime (deno_core)
        |   - Loads all ext/* extensions (web, fetch, net, http, fs, crypto, node, ...)
        |   - Snapshot is loaded if available, otherwise extensions are bootstrapped fresh
        |   - Runs runtime/js/99_main.js to set up the Deno namespace
        |   - Applies bootstrap options (args, location, runtime version)
        |
        v
main_worker.execute_main_module(specifier)
        |   - Module loader fetches main.ts (from disk)
        |   - If TS/TSX, deno_ast transpiles to JS (cached in $DENO_DIR/gen)
        |   - JsRuntime instantiates and evaluates the module graph
        |   - Top-level await is awaited
        |
        v
main_worker.run_event_loop(false)       drives Tokio + V8 microtasks until idle
        |
        v
Process exits with main_worker.exit_code()

The same orchestration drives every executed-script subcommand (run, serve, test, bench, eval, repl, task). Each builds slightly different WorkerOptions and may register additional setup (test runner installs Deno.test, REPL installs the REPL state, etc.).

2.4 Subcommand Architecture

Every subcommand has:

1. A clap Command::new(...) builder in cli/args/flags.rs (lines 2219+, one fn <cmd>_subcommand() per subcommand).
2. A <cmd>_parse(...) function (also in flags.rs) that consumes the parsed ArgMatches and writes into Flags.
3. A handler in cli/tools/<cmd>.rs (or cli/tools/<cmd>/mod.rs for multi-file subcommands).

The 38 subcommands defined in the root command (flags.rs:2140-2179):

Aliases: When the CLI is invoked as dx, denox, or dnx, flags_from_vec_with_initial_cwd rewrites the args to insert x as the first argument (flags.rs:1697-1711). This makes dx eslint . equivalent to deno x eslint . (which itself is deno run npm:eslint .).

2.5 The op2 Bridge: How JS Calls Rust

Every Deno API that does I/O goes through an op — an asynchronous or synchronous function defined in Rust and exposed to JS through V8 fast-call bindings.

// ext/fs/lib.rs (illustrative)
#[op2(async)]
async fn op_read_file_async(
  #[state] state: &PermissionsContainer,
  #[string] path: String,
) -> Result<Vec<u8>, AnyError> {
  state.check_read(Path::new(&path), "Deno.readFile()")?;
  tokio::fs::read(path).await.map_err(Into::into)
}

The #[op2] macro generates V8 fast-call entry points and serde_v8 bindings. The op is registered with an Extension:

deno_core::extension!(
  deno_fs,
  deps = [deno_web, deno_io],
  ops = [op_read_file_async, op_write_file_async, ...],
  esm_entry_point = "ext:deno_fs/30_fs.js",
  esm = ["30_fs.js"],
  options = { fs: Arc<dyn FileSystem> },
);

When the CLI builds a JsRuntime, it passes a list of these extensions. At snapshot time, the JS portions are evaluated and snapshotted. At runtime, only the Rust ops + any non-snapshotted extensions remain to load.

2.6 Snapshotting

Building the binary involves a build-time JavaScript snapshot: all bootstrap JS for deno_core + every ext/* is parsed and serialized into a binary blob that ships inside the executable. At startup, V8 deserializes the snapshot, skipping the cost of parsing and evaluating ~2 MB of JS. The cli Cargo.toml enables include_js_files_for_snapshotting only on its build-dependencies, so the snapshot is generated by build.rs and the embedded blob is the only JS that ships.

Disable with the hmr Cargo feature for development: this drops the snapshot and reloads JS from disk, which is slower but allows live editing.

3. System Requirements

3.1 Runtime requirements (running deno)

The pre-built binary is statically linked against V8 and the bundled C++ runtime; it does not depend on any system JS engine.

3.2 Build requirements (building from source)

V8 itself may compile for 30+ minutes on first build. Subsequent incremental builds are minutes.

3.3 Platform targets supported by deno compile

Cross-compile by passing --target to deno compile. The denort runtime for the target is downloaded and cached automatically on first use.

4. Configuration Mastery

4.1 Configuration Discovery Order

Deno resolves configuration in this order (highest to lowest precedence):

1. Command-line flags (--config, --lock, --import-map, --allow-*).
2. Environment variables (DENO_DIR, DENO_NO_PACKAGE_JSON, etc.).
3. Per-task --env-file if specified.
4. deno.json / deno.jsonc discovered by walking from --initial-cwd (or the current working directory) upward.
5. package.json discovered the same way (when not disabled by DENO_NO_PACKAGE_JSON).
6. Built-in defaults.

Use --no-config to disable deno.json discovery entirely; --config=path to pin a specific file.

Important

In workspace setups, each member's deno.json inherits the root imports map but can override individual specifiers. Task definitions do not inherit — each member must declare its own tasks.

4.2 The deno.json Schema

The full JSON schema is cli/schemas/config-file.v1.json (~600 lines). The top-level keys, exhaustively:

permissionSet schema (excerpt)

"permissionSet": {
  "all": boolean,
  "read":   true | false | string[] | { allow: ..., deny: ..., ignore: ... },
  "write":  true | false | string[] | { allow: ..., deny: ... },
  "import": true | false | string[] | { allow: ..., deny: ... },
  "env":    true | false | string[] | { allow: ..., deny: ..., ignore: ... },
  "net":    true | false | string[] | { allow: ..., deny: ... },
  "run":    true | false | string[] | { allow: ..., deny: ... },
  "ffi":    true | false | string[] | { allow: ..., deny: ... },
  "sys":    true | false | string[] | { allow: ..., deny: ... }
}

The asymmetry — only read, env, sys accept the ignore key — reflects which categories support being silently no-op'd vs. denied.

4.3 Workspace (Monorepo) Configuration

A root deno.json declares workspace:

{ "workspace": ["./packages/core", "./packages/cli", "./packages/web"] }

Each member has its own deno.json with name / version / exports. Commands operate over the full workspace:

libs/config/workspace implements discovery and member resolution.

4.4 Lockfile (deno.lock)

libs/lockfile defines the format. Top-level keys:

Pass --frozen to fail when the lockfile would change (CI default for reproducible builds). --no-lock disables lockfile use entirely.

4.5 compilerOptions — TypeScript Settings

A subset of tsconfig.json. Notable supported keys:

strict, strictNullChecks, noImplicitAny, noFallthroughCasesInSwitch, noImplicitOverride, noImplicitThis, noUnusedLocals, noUnusedParameters, useDefineForClassFields, experimentalDecorators, emitDecoratorMetadata, lib, jsx, jsxFactory, jsxFragmentFactory, jsxImportSource, jsxImportSourceTypes, target, types, checkJs, allowJs.

Notably not supported: outDir, rootDir, module, moduleResolution, paths, baseUrl — Deno controls module resolution itself via imports / scopes.

compilerOptions.lib defaults are derived from the unstable flags. With no flags, ["deno.window"] is used. Adding "dom" enables browser globals; "deno.unstable" adds typings for unstable APIs.

4.6 Environment Variable Precedence

Some env vars have CLI flag equivalents. Where both are set:

Full list of supported env vars: see User Guide Section 7 (sourced from cli/args/flags.rs:1452-1591).

5. Security

5.1 Threat Model

Deno's primary security posture is to make a script safe for the user to run, not to make the host machine safe for the user. Untrusted code runs inside the V8 sandbox and can only escape via Deno-controlled ops, all of which are gated by the permission system. Secondary properties:

• The V8 process is the security boundary; there is no in-process privilege separation.
• Permissions are checked at op-call time, not at module-load time. A malicious module loaded with --allow-net can still attempt FS reads — the check fires when it tries.
• Permissions cannot be widened at runtime. They can only be narrowed via --deny-* or via Deno.permissions.revoke().
• The permission prompt is interactive and bypassable in CI by --no-prompt.

5.2 Permission Model Internals

runtime/permissions/lib.rs defines PermissionsContainer, the central state for a worker. Each permission category is a struct (e.g. UnaryPermission<NetDescriptor>) holding allow-list, deny-list, ignore-list, and prompted state.

Op call flow:

1. The op extracts &PermissionsContainer from the OpState.
2. It calls a typed check method, e.g. state.check_net(&host, port, "Deno.connect").
3. The check evaluates: deny list → prompted-deny → granted-allow → allow-list → prompted-allow → prompt user (or deny if --no-prompt).
4. On allow, the op proceeds; on deny, it returns PermissionDenied to JS.

is_allow_all() short-circuits to true when --allow-all was used. Without -A, every op call goes through the full check.

Warning

Permissions are checked at op-call time, not at module-load time. A module imported with --allow-net can still attempt file system reads — the denial fires only when the syscall-level op is invoked. Always apply the principle of least privilege.

5.3 Known Security Considerations

5.4 Hardening Recommendations

• Use --no-prompt in CI and in production binaries to convert silent denials into errors.
• Use --allow-net= with explicit hosts; never bare --allow-net.
• Use --allow-read= and --allow-write= with explicit paths.
• Set unstable only to the features actually needed; do not blanket-enable.
• Pin Deno versions in CI (actions/setup-deno@vN with deno-version: vX.Y.Z).
• Commit deno.lock and run deno install --frozen (or rely on the --frozen default in CI mode).
• Use DENO_NO_UPDATE_CHECK=1 in air-gapped environments.
• For network apps, run behind a reverse proxy and set DENO_TRUST_PROXY_HEADERS=1 only when the proxy is trusted to set the client address.
• Approve npm lifecycle scripts package-by-package, never globally.

Caution

--allow-ffi loads arbitrary native dynamic libraries, effectively granting the same capabilities as --allow-all. Treat any FFI usage as a full trust boundary escape.

6. Operations and Maintenance

6.1 Cache Layout ($DENO_DIR)

Default path: $HOME/.cache/deno (Linux), $HOME/Library/Caches/deno (macOS), %LOCALAPPDATA%\deno (Windows). Override with DENO_DIR.

$DENO_DIR/
  deps/                 HTTPS module cache (URL → file)
  npm/                  npm package cache (registry → tarball)
  registries/           jsr:/npm: metadata cache
  gen/                  Transpiled JS for TS modules (keyed by source hash)
  check/                Type-check artefacts and diagnostics cache
  emit/                 Emit cache (build outputs)
  binary/               Downloaded denort runtimes for `deno compile --target`
  binary_versions.json  Tracker for downloaded denort versions
  kv/                   Default storage for Deno.openKv() (SQLite files)
  webcache/             Web Cache API storage
  webstorage/           localStorage / sessionStorage SQLite files
  repl.log              REPL history (override with DENO_REPL_HISTORY)
  upgrade_check/        Last-update-check timestamp

deno clean removes the entire $DENO_DIR. To selectively reload, use --reload[=URL].

Tip

Set DENO_DIR to a shared network path for team-wide cache sharing. The cache is content-addressed and safe for concurrent access from multiple Deno processes.

6.2 Logging

Deno respects RUST_LOG (Rust env_logger syntax):

RUST_LOG=info deno run main.ts
RUST_LOG=deno=debug,deno_runtime=trace deno run main.ts
RUST_LOG=deno_core::module_loader=trace deno run main.ts

Useful target prefixes: deno, deno_runtime, deno_core, deno_npm, deno_resolver, deno_lsp, tokio. Combine with DENO_TRACE_PERMISSIONS=1 to debug permission issues.

6.3 Monitoring (OpenTelemetry)

ext/telemetry exposes the runtime via OpenTelemetry. Configure with standard OTel env vars:

The runtime exports HTTP request spans, op spans, and JS-emitted spans (when user code uses @opentelemetry/api).

Note

OpenTelemetry support requires --unstable-otel or adding "otel" to the unstable array in deno.json. Without this flag, the OTEL_* environment variables are ignored.

6.4 Inspector and Debugging

deno run --inspect main.ts                # listen on 127.0.0.1:9229
deno run --inspect-brk main.ts            # break before user code
deno run --inspect-wait main.ts           # wait for debugger to attach
deno run --inspect=0.0.0.0:9229 main.ts   # listen on all interfaces (BE CAREFUL)

Open chrome://inspect in Chrome to attach. The inspector speaks the standard V8 Debugger Protocol.

The standalone inspector server (libs/inspector_server) is also used by deno lsp for IDE debugging integration.

Warning

Never expose the inspector on 0.0.0.0 in production. The V8 inspector protocol allows arbitrary code execution — an attacker with network access to the inspector port gains full control of the process.

6.5 Upgrade and Rollback

deno upgrade                # latest stable
deno upgrade canary         # canary
deno upgrade <version>      # specific version
deno upgrade --output PATH  # specify output binary path
deno upgrade --dry-run      # show what would happen, don't change anything
deno upgrade --force        # overwrite when target version equals current

The upgrade subcommand downloads from https://github.com/denoland/deno/releases, verifies the SHA256, and atomically replaces the binary. To roll back to a known version: deno upgrade <previous-version>. There is no built-in version manager; for multi-version coexistence use a tool like dvm or install side-by-side via different DENO_INSTALL_ROOT directories.

6.6 Cron and Long-Running Servers

For production HTTP servers using Deno.serve:

• Run with --parallel to spawn one worker per CPU.
• Use a process supervisor (systemd, supervisord, Docker restart policies) — Deno does not daemonize.
• For Linux, set DENO_USR2_MEMORY_TRIM=1 to allow SIGUSR2 to free memory.
• Use DENO_USE_CGROUPS=1 so V8's heap limit reflects container memory limits, not host RAM.

For scheduled work: Deno.cron("name", "* * * * *", handler) (requires --unstable-cron). State for cron is stored in Deno KV.

6.7 Backup

The dependency cache (deps/, npm/) is reproducible from deno.lock + network and does not need backup.

6.8 Deployment Topologies

Single-process: a deno serve instance behind nginx/Caddy. Set --port, --host=127.0.0.1, and proxy.

Multi-process: spawn N instances bound to different ports, load-balance with the proxy. Deno does not provide cluster-mode; use OS-level process management.

Single-binary deployment: deno compile -A --output app main.ts produces a self-contained executable. Ship it directly. The binary embeds the runtime, so the target machine needs no Deno installation.

Container: denoland/deno:latest is the official image. For minimal images, use gcr.io/distroless/cc and copy a deno compiled binary in.

7. Build and Distribution

7.1 Cargo Workspace

Root Cargo.toml declares the workspace with resolver = "2" and lists all 70+ members. Workspace-level package metadata (authors, edition, license, repository) is inherited by all crates. Workspace-level dependencies pin every external dependency version once and inject path = "./..." for internal crates so they are always built from source.

Build the binary:

cargo build --release -p deno
./target/release/deno --version

Build with debug symbols and dhat heap profiling:

cargo build --profile=release-with-debug --features=dhat-heap -p deno

Build the slim runtime crate alone (for embedding):

cargo build -p deno_runtime

7.2 Cargo Features (cli crate)

7.3 Build-Time Snapshot

cli/build.rs builds a V8 startup snapshot. The snapshot embeds:

• deno_core infrastructure JS
• All ext/* JS bootstrap code (each Extension contributes its esm files at snapshot time)
• runtime/js/99_main.js — the Deno namespace setup

Without snapshotting, startup parses ~2 MB of JS on every invocation. With it, V8 mmap-loads a binary blob and starts in milliseconds.

cli/snapshot/ holds the persisted snapshot artifacts pulled into the binary by include_bytes!.

7.4 Release Process

1. Tag a commit with vX.Y.Z on main.
2. CI (GitHub Actions) builds binaries for all 5 target triples.
3. Each binary is signed and uploaded to a GitHub Release.
4. The install scripts (install.sh, install.ps1) detect the latest release and download the appropriate binary.
5. deno upgrade queries the same GitHub Releases API.

Releases.md in the repo root is the canonical changelog.

7.5 Dependency Management for the Workspace

External dependencies are pinned in the root [workspace.dependencies] block. Internal deno crates use path references so workspace builds always use local source. Deno-specific helper crates (deno_ast, deno_lockfile, deno_doc, deno_lint, etc.) are pinned to exact versions via =X.Y.Z.

To upgrade an internal crate: bump the =X.Y.Z line in [workspace.dependencies], run cargo update -p <crate>, and verify with cargo check --workspace.

7.6 Cross-Compile

Cargo cross-compile setup is in .cargo/config.toml. CI uses cross and platform-specific runners (Apple Silicon and ARM Linux are native; Windows is MSVC).

Cross-compile a deno compile binary (different from cross-compiling deno itself):

deno compile --target aarch64-unknown-linux-gnu --output myapp-arm64 main.ts

The denort runtime for the target architecture is downloaded to $DENO_DIR/binary/ on first cross-compile.

8. Module Reference

8.1 The deno_core Trinity

deno_core is the foundation. The three central types:

JsRuntime

libs/core/runtime/jsruntime.rs. Owns a V8 Isolate and Context. Provides:

• new(options) — construct a runtime with extensions, snapshot, module loader, op state seed.
• execute_script(name, source) — synchronously execute JS, returns the V8 value.
• load_main_module(specifier, code) — load a module graph rooted at specifier.
• mod_evaluate(module_id) — evaluate a loaded module; returns a future for the result.
• run_event_loop(opts) — drive Tokio + microtasks until idle.

Extension

libs/core/extensions.rs. Bundles ops, ESM modules, and state seed for a feature. Built via the extension! macro:

extension!(deno_my,
  deps = [deno_web, deno_url],
  ops = [op_foo, op_bar],
  esm_entry_point = "ext:deno_my/01_main.js",
  esm = ["01_main.js", "02_helpers.js"],
  options = { foo: Arc<dyn FooSrv> },
);

deps enforces extension-load ordering. options are passed at runtime via MyExtensionOptions { ... }.

ModuleLoader

Trait in libs/core/modules/. Implementors handle resolve() (specifier → URL) and load() (URL → source). The CLI's loader at cli/module_loader.rs handles HTTPS, JSR, npm, file, data, and node schemes.

8.2 The op2 Macro

libs/ops/op2/. The #[op2] proc-macro generates V8 fast-call entry points. Variants:

Parameter attributes:

8.3 Module Graph and Resolution

The graph is built by deno_graph (an external crate, but wholly authored by the Deno team). It traverses imports starting from the entry point, applies the import map, resolves npm/jsr specifiers via the local resolver, and produces a module graph used for type-checking, bundling, vendoring, publishing, and execution.

Key types:

8.4 The Type-Checking Pipeline

cli/type_checker.rs and cli/tsc/. As of v2, Deno uses TypeScript-Go (a Go port of tsc) for type-checking. The Rust client (libs/typescript_go_client/) talks to the Go process over IPC.

Flow:

1. deno check main.ts builds the module graph.
2. The graph is serialized and sent to the TS-Go subprocess.
3. TS-Go runs the type checker and returns diagnostics.
4. Diagnostics are formatted and printed by deno_runtime::fmt_errors.
5. Successful type-check results are cached in $DENO_DIR/check/.

The legacy tsc integration (in cli/tsc/) remains for cases where TS-Go cannot handle the graph (some experimental syntax, compilerOptions.experimentalDecorators interactions). Both paths produce the same diagnostic format.

8.5 The Language Server (deno lsp)

cli/lsp/. A Tower-LSP server that implements the standard LSP plus Deno-specific extensions:

The LSP shares the resolver, type-checker, and module loader with the rest of the CLI; opening a workspace in an editor exercises the same resolution path as deno run.

8.6 The Standalone Runtime (denort)

cli/rt/. A reduced binary that ships inside deno compile outputs. It contains the runtime + ext extensions but omits the type checker, formatter, linter, doc generator, REPL, and LSP. The eszip appended to the executable contains the user's bundled module graph; on startup, denort loads the eszip into memory and executes the entry point.

ext/rt_helper provides shared helpers between cli/ and cli/rt/.

8.7 The Bundler

ext/bundle + cli/tools/bundle/. The bundler is built on esbuild (via WASM). It produces ESM bundles for browser/Deno targets and is the engine behind:

8.8 The Package Manager (cli/tools/pm)

cli/tools/pm/. Implements deno add, deno remove, deno install, deno uninstall, deno outdated, deno update, and deno approve-scripts. Backed by:

• libs/npm — npm package resolution
• libs/npm_cache — disk cache
• libs/npm_installer — node_modules layout
• libs/npmrc — registry/auth config
• libs/resolver/npm — runtime npm resolution

9. Code Patterns

9.1 Cargo Conventions

• Workspace-pinned everything. Every external dep is in [workspace.dependencies]. Crates use workspace = true.
• Per-crate features for slim builds. deno_runtime has transpile, snapshot, hmr features so embedders can opt in/out of features that pull in heavy deps.
• Internal crates ship to crates.io. deno_core, deno_ast, deno_lockfile, deno_doc, deno_lint, etc. are independently versioned and published.

9.2 Async Patterns

• The runtime is single-threaded Tokio (current_thread flavor) — V8 isolates are not Send.
• WebWorker spawns a fresh OS thread with its own Tokio runtime.
• Long-running ops yield via tokio::spawn_blocking for FS-heavy work; otherwise they run on the main thread.
• Cancellation is cooperative via CancelHandle (a deno_core type).

9.3 Error Handling

deno_error::JsErrorBox and AnyError are the universal error types crossing the JS/Rust boundary. Errors implement JsError for proper translation to JS exception classes (TypeError, RangeError, Deno.errors.PermissionDenied, etc.). Most ops return Result<T, AnyError>.

9.4 Snapshot-Friendly Code

Anything in an ext/ JS file that runs at extension load runs at snapshot time (during the build), not at runtime. This means:

• No I/O, no Tokio.
• No date/time captures (would freeze build time into the snapshot).
• No network access — URLs constructed at snapshot time embed the build host's machine state.

Code that must run per-process (e.g. reading env vars, getting Date.now()) goes in the 99_main.js bootstrap or in lazily-evaluated code paths.

9.5 State Management

OpState is a per-JsRuntime typemap (keyed by Rust type) that ops draw from. Idiomatic pattern: store an Arc<MyService> in OpState, pull it via #[state] in op signatures.

PermissionsContainer lives in OpState and is mutated only by the runtime (not by ops).

10. Testing Strategy

10.1 Test Categories

The spec format: each test directory has a __test__.jsonc describing args, env, expected exit code, expected stdout pattern, expected stderr pattern. The integration test runner discovers them recursively.

10.2 Local Mock Registries

tests/registry/ ships a self-contained JSR-shaped and npm-shaped registry served by the tests/util/server HTTP server during tests. This allows tests to reference deterministic packages like npm:@denotest/cjs-multiple-exports without hitting npm.org.

10.3 Adding a Spec Test

1. Create tests/specs/<group>/<test_name>/.

2. Add __test__.jsonc:

   { "args": "run -A main.ts", "output": "main.out" }
   

3. Add main.ts and main.out (the expected stdout/stderr).

4. Run cargo test --test integration -- specs::<group>::<test_name>.

11. Operating in Production

11.1 Container Image

FROM denoland/deno:2.7.12 AS build
WORKDIR /app
COPY deno.json deno.lock ./
RUN deno install --frozen
COPY . .
RUN deno cache --frozen main.ts
CMD ["deno", "run", "--no-prompt", "--allow-net", "--allow-read=./data", "main.ts"]

For minimal image size, use deno compile and a distroless base:

FROM denoland/deno:2.7.12 AS build
WORKDIR /app
COPY . .
RUN deno compile --output myapp -A main.ts

FROM gcr.io/distroless/cc
COPY --from=build /app/myapp /usr/local/bin/myapp
ENTRYPOINT ["/usr/local/bin/myapp"]

11.2 systemd Unit

[Unit]
Description=My Deno Service
After=network.target

[Service]
ExecStart=/usr/local/bin/deno run --no-prompt --allow-net --allow-read=/var/lib/myapp /var/lib/myapp/main.ts
Restart=on-failure
RestartSec=5
User=myapp
Environment=DENO_DIR=/var/cache/deno
Environment=DENO_NO_UPDATE_CHECK=1
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

11.3 Kubernetes

Run deno serve --parallel --host 0.0.0.0 --port 8080 main.ts in the container. Expose port 8080. The pod's CPU limit governs the parallel worker count when DENO_USE_CGROUPS=1 is set.

For graceful shutdown: Deno.serve already handles SIGTERM. Kubernetes' default terminationGracePeriodSeconds: 30 is sufficient for most workloads.

11.4 Resource Limits

12. Troubleshooting (Operator-Focused)

For developer-side troubleshooting, see the User Guide. This section covers operational issues.

Warning

Production Deno processes should always run with --no-prompt to convert interactive permission prompts into hard denials. An unattended process that blocks on a prompt will stall indefinitely.

Issue: Deno binary updates itself unexpectedly in a Linux distro package

Cause: deno upgrade overwrites the binary. The distro tracks a different version. Solution: Build with cargo build --release --no-default-features --features __vendored_zlib_ng -p deno to disable the upgrade feature.

Issue: Type-check is slow in CI

Cause: Cold cache; TypeScript-Go starting up; remote modules being fetched. Solution: Cache $DENO_DIR/check/ and $DENO_DIR/deps/ between CI runs. Use deno cache main.ts as a separate step before deno test.

Issue: V8 process exceeds container memory

Cause: Default heap limit ignores cgroups. Solution: Set DENO_USE_CGROUPS=1 so V8 sees the container limit. Alternatively, pass --v8-flags=--max-old-space-size=<MB>.

Issue: deno compile binary fails on target with "GLIBC_X.YZ not found"

Cause: The pre-built denort for Linux is built against newer glibc than the target. Solution: Build denort from source on a matching glibc base, or target a musl variant via cross-compilation.

Issue: Module fetch fails behind corporate proxy

Cause: Proxy credentials or CA cert. Solution: Set HTTPS_PROXY and HTTP_PROXY. For private CA: DENO_CERT=/path/to/ca-bundle.pem and possibly DENO_TLS_CA_STORE=system,mozilla.

Issue: deno serve --parallel only spawns one worker

Cause: --parallel without an integer defaults to detected CPU count from cgroups; a misconfigured cgroup may report 1. Solution: Pass an explicit count: --parallel=8. Verify cgroup with nproc inside the container.

Issue: Inspector is reachable from outside the container

Cause: --inspect=0.0.0.0:9229 was used. Deno's inspector has no auth. Solution: Always use --inspect=127.0.0.1:9229 and tunnel via SSH or kubectl port-forward. Never expose the inspector publicly.

Tip

When debugging CI cache misses, run deno info --json main.ts to dump the full module graph with resolved URLs and cache paths. Compare against the previous run to identify what changed.

Issue: KV database corruption after kill -9

Cause: SQLite WAL not checkpointed. Solution: Use kill -TERM and let Deno's signal handler close KV cleanly. For recovery, open the SQLite file with sqlite3 and run PRAGMA wal_checkpoint(TRUNCATE);.

Issue: Lockfile drift across team members

Cause: Different platforms resolve packages slightly differently (npm optional deps). Solution: Commit the lockfile as-is and use --frozen in CI. For platform-specific optional deps, use npmrc settings.

Issue: deno upgrade fails with "could not download release"

Cause: GitHub rate-limited the unauthenticated request, or the network blocks github.com. Solution: Set GH_TOKEN (or GITHUB_TOKEN) for an authenticated request. For air-gapped environments, mirror releases internally and use --canary-url=... or deno upgrade --output PATH after manual download.

13. Contributing

13.1 Where to Start

• Code of conduct: .github/CODE_OF_CONDUCT.md
• Contributing guide: .github/CONTRIBUTING.md
• Good first issues: https://github.com/denoland/deno/labels/good first issue

13.2 Local Development

git clone https://github.com/denoland/deno.git
cd deno
cargo build -p deno              # debug build (~5 min after V8 caches)
./target/debug/deno --version
cargo test -p deno_runtime       # unit tests for runtime crate
cargo test --test integration -- specs::run::  # integration specs for `run`

For tight iteration on JS bootstrap code, use the hmr Cargo feature: cargo build --features hmr -p deno. With HMR, edits to runtime/js/* and ext/*/*.js take effect on the next deno run without rebuilding the snapshot.

13.3 Style and Lint

• Rust: cargo fmt --check and cargo clippy -- -D warnings. CI fails on either.
• JS/TS: deno fmt and deno lint. CI runs both.
• Spec tests: copyright header is mandatory (// Copyright 2018-2026 the Deno authors. MIT license.).

13.4 PR Process

1. Branch from main.
2. Open a PR with a clear description and (where relevant) a spec test.
3. CI runs the full matrix: build on all 5 targets + spec tests + WPT subset + lint + format.
4. Maintainers review. Most PRs require one approval; substantial changes require two.
5. Squash-merge into main with a Conventional Commits-style message.

13.5 Architecture for New Contributors

14. Quick Reference

14.1 Rebuild After Pulling

cargo build -p deno --release

14.2 Run Specific Spec Test

cargo test --test integration -- specs::run::specific_test_name

14.3 Re-Generate the JSON Schema for deno.json

The schema lives at cli/schemas/config-file.v1.json and is hand-maintained. Update it whenever a new top-level key is added.

14.4 Useful Files

14.5 GitHub Issues Referenced in Troubleshooting