Deno Overview

Relevant source files

• .dprint.json
• .github/workflows/ci.generate.ts
• .github/workflows/ci.yml
• Cargo.lock
• Cargo.toml
• Releases.md
• cli/Cargo.toml
• ext/crypto/Cargo.toml
• ext/fetch/Cargo.toml
• ext/ffi/Cargo.toml
• ext/http/Cargo.toml
• ext/net/Cargo.toml
• ext/node/Cargo.toml
• ext/node/lib.rs
• ext/tls/Cargo.toml
• ext/web/Cargo.toml
• ext/websocket/Cargo.toml
• ext/webstorage/Cargo.toml
• runtime/Cargo.toml

Purpose and Scope

This document introduces Deno at the highest level: what it is, its architectural philosophy, and how the codebase is organized. For detailed information about specific subsystems:

• Project structure and workspace organization: see Project Structure and Workspace
• Build system and CI/CD details: see Build System, Dependencies, and CI/CD
• CLI implementation: see CLI Architecture
• Runtime internals: see Runtime Core

What is Deno

Deno is a secure runtime for JavaScript and TypeScript built on V8, Rust, and Tokio. The codebase delivers:

• A command-line interface (deno binary) for executing JavaScript/TypeScript
• A runtime library (deno_runtime) providing Web Platform APIs
• An extension framework (deno_core) enabling modular functionality
• Node.js compatibility layer (deno_node) with 300+ polyfilled modules
• Integrated developer tooling (LSP, testing, benchmarking, formatting, linting)

Sources: cli/Cargo.toml1-226 runtime/Cargo.toml1-116 Cargo.toml1-559

Architecture Philosophy

Layered Design

The codebase follows strict layering where each layer depends only on layers below:

Layer responsibilities:

• User Interface: CLI argument parsing, LSP protocol handling
• Runtime: Worker lifecycle, module loading, event loop
• Extensions: Web APIs, system APIs, Node.js compatibility
• Platform: JavaScript engine, async runtime, OS interfaces

Sources: Cargo.toml3-61 cli/Cargo.toml1-226 runtime/Cargo.toml1-116

Extension-Based Modularity

Functionality is provided through discrete extensions registered with deno_core. Each extension:

• Exposes operations (ops) callable from JavaScript via #[op2] macro
• Provides JavaScript/TypeScript source files embedded in binary
• Manages native resources via resource table
• Declares dependencies on other extensions

Extension Architecture:

Sources: Cargo.toml95-122 ext/node/lib.rs144-304 ext/http/Cargo.toml1-68

Codebase Organization

Cargo Workspace Structure

The repository is organized as a Cargo workspace with 63+ member crates:

Directory	Purpose	Key Members
cli/	Command-line interface	deno (binary), deno_lib, deno_snapshots
runtime/	Runtime library	deno_runtime, deno_permissions, deno_features
ext/	Extension crates	deno_* (20+ extensions)
libs/	Shared libraries	deno_config, deno_lockfile, node_resolver, eszip
tests/	Test infrastructure	test_util, bench_util, integration tests

Sources: Cargo.toml3-61

Repository Layout

Sources: Cargo.toml3-61 cli/Cargo.toml1-226

Core Components

CLI Binary (cli/)

The deno binary provides user-facing commands and subcommand dispatch.

Entry point: cli/main.rs16

Key structures:

• Flags: Parsed command-line arguments
• DenoSubcommand: Enum of all subcommands (run, test, compile, etc.)
• CliFactory: Dependency injection container for services
• CliMainWorkerFactory: Creates MainWorker instances

Major subsystems:

• cli/tools/test.rs: Test runner implementation
• cli/tools/bench.rs: Benchmark runner
• cli/lsp/: Language Server Protocol implementation
• cli/tsc/: TypeScript compiler integration

Sources: cli/Cargo.toml1-226 cli/main.rs16

Runtime Library (runtime/)

deno_runtime provides the JavaScript execution environment.

Key exports:

• MainWorker: Primary execution context for main thread
• WebWorker: Execution context for Web Workers
• BootstrapOptions: Configuration for runtime initialization

Bootstrap sequence: runtime/js/99_main.js

• Initializes global objects (Deno namespace, Web APIs)
• Sets up event loop integration
• Configures permissions system

Extension registration: Extensions are registered in dependency order during worker creation.

Sources: runtime/Cargo.toml1-116 runtime/lib.rs38

Extension System (ext/)

Extensions provide modular functionality via the deno_core::extension! macro.

Major extensions:

Extension	Primary Function	Rust Ops	JS Modules
deno_core	Extension framework, op system	Core infrastructure	-
deno_web	EventTarget, Streams, TextEncoder	50+	30+
deno_fetch	fetch() API, HTTP client	20+	10+
deno_http	Deno.serve(), HTTP server	30+	5+
deno_websocket	WebSocket client/server	15+	2+
deno_crypto	Web Crypto API, SubtleCrypto	40+	5+
deno_fs	FileSystem trait, file ops	25+	-
deno_io	stdio, Deno.File	10+	-
deno_net	TCP/UDP/Unix sockets, TLS	35+	5+
deno_ffi	dlopen, FFI	20+	3+
deno_kv	Deno.openKv(), AtomicOperation	15+	2+
deno_node	Node.js compatibility	100+	200+

Extension dependencies (simplified):

• deno_fetch depends on deno_web, deno_net, deno_tls
• deno_http depends on deno_web, deno_net
• deno_node depends on nearly all other extensions

Sources: Cargo.toml95-122 ext/node/lib.rs144-304 ext/http/Cargo.toml1-68 ext/fetch/Cargo.toml1-55 ext/crypto/Cargo.toml1-51

Shared Libraries (libs/)

Reusable libraries used across CLI and runtime:

Library	Responsibility
deno_config	Parse deno.json, workspace configuration
deno_lockfile	Lock file read/write, integrity checking
deno_npm	NPM package resolution, semver handling
node_resolver	Node module resolution algorithm
deno_resolver	Unified module resolution (Deno + Node + NPM + JSR)
eszip	ES module archive format (ESZIP v2)
deno_inspector_server	Chrome DevTools Protocol server

Sources: Cargo.toml124-148

Build System

Workspace Dependency Management

Centralized dependency versions in workspace root:

Workspace dependencies section: Cargo.toml72-148

• 100+ dependencies with pinned versions
• Shared across all workspace members
• Individual crates use workspace = true syntax

Sources: Cargo.toml1-559

Build Profiles

Release profile configuration: Cargo.toml421-428

opt-level = 'z'           # Optimize for size
lto = true                # Link-time optimization
codegen-units = 1         # Single codegen unit for better optimization
incremental = true        # Incremental compilation
split-debuginfo = "packed" # Packed debug info

Per-package optimization overrides: Cargo.toml455-558

• Hot paths (deno_core, tokio, hyper, crypto libs) set to opt-level = 3
• Ensures performance-critical code is fully optimized even in debug builds

Sources: Cargo.toml421-558

CI/CD Pipeline

Multi-platform automated builds via GitHub Actions:

Build matrix dimensions: .github/workflows/ci.generate.ts431-496

• 3 operating systems (Linux, macOS, Windows)
• 2 architectures (x86_64, aarch64)
• 2 profiles (debug, release)
• Conditional execution based on PR labels (ci-full, ci-bench)

Test phases:

1. Library tests: cargo test --lib
2. Integration tests: cargo test --tests
3. Web Platform Tests (WPT) on Linux release builds
4. Node.js compatibility test suite

Release artifacts:

• deno-<platform>.zip: Main binary
• denort-<platform>.zip: Runtime-only binary (for deno compile)
• deno-<platform>.symcache: Debug symbols for crash reporting

Distribution:

• Canary: Every commit to main → dl.deno.land/canary/<sha>/
• Stable: Tagged releases → dl.deno.land/release/<version>/ + GitHub Releases

Sources: .github/workflows/ci.yml1-3523 .github/workflows/ci.generate.ts1-1192

Extension System Details

Extension Macro Usage

Extensions use the deno_core::extension! macro to declare their interface:

Example - deno_node extension: ext/node/lib.rs144-304

• Declares 100+ ops (e.g., op_require_*, op_node_fs_*, op_node_http_*)
• Provides 200+ ESM modules (public Node.js APIs + internal implementations)
• Depends on deno_io and deno_fs

Sources: ext/node/lib.rs144-304 ext/http/Cargo.toml1-68

Op Types and Patterns

Operations are defined using #[op2] macro with modifiers:

Modifier	Use Case	Example
#[op2(fast)]	Simple synchronous ops, minimal V8 overhead	op_now() returns current timestamp
#[op2(async)]	I/O operations, returns Future	op_read_file() reads file asynchronously
#[op2]	Complex data structures, full V8 integration	op_create_worker() with configuration object

Common op naming conventions:

• op_fs_*: File system operations in deno_fs
• op_net_*: Network operations in deno_net
• op_http_*: HTTP server operations in deno_http
• op_fetch_*: HTTP client operations in deno_fetch
• op_node_*: Node.js compatibility operations in deno_node

Sources: ext/node/lib.rs147-303

Node.js Compatibility Architecture

The deno_node extension provides comprehensive Node.js API compatibility through a three-layer architecture:

Public APIs: ext/node/lib.rs316-527

• 50+ Node.js modules (fs, http, crypto, buffer, stream, etc.)
• Located in polyfills/ directory
• Export-compatible with Node.js

Internal implementation:

• _fs/, _http*/, internal/ modules
• Contain actual polyfill logic
• Use internal bindings for native operations

Node-specific ops:

• Located in ops/ subdirectory
• Bridge to Deno infrastructure (e.g., ops/http.rs uses deno_http)
• Wrap native libraries (zlib, brotli, zstd)

Coverage: 300+ polyfilled modules providing ~80% Node.js API compatibility

Sources: ext/node/lib.rs1-528 ext/node/Cargo.toml1-76

Module Loading System

Supported Module Types

Deno's module loader handles multiple formats:

Format	File Extensions	Features
ES modules	.js, .ts, .mjs, .mts	Native V8 loader, dynamic import, top-level await
CommonJS	.cjs, .cts, Node packages	require(), module.exports, interop with ESM
TypeScript	.ts, .tsx, .mts, .cts	Transpiled to JavaScript via SWC or TSC
JSON	.json	Import assertions/attributes
WASM	.wasm	WebAssembly modules

Module resolution strategies:

1. Deno-style: URL-based specifiers (https://, file://)
2. Node-style: Bare specifiers with node_modules/ resolution
3. NPM: npm: specifier protocol
4. JSR: jsr: specifier protocol for JSR packages

Sources: ext/node/lib.rs55-74 cli/Cargo.toml68-199

NPM Integration Modes

Two modes for NPM package handling:

Managed Mode (default):

• Global cache at DENO_DIR/npm/
• Automatic package installation
• Resolver: ManagedCliNpmResolver

BYONM (Bring Your Own node_modules) Mode:

• Uses local node_modules/ directory
• Requires manual npm install or deno install
• Resolver: ByonmCliNpmResolver

Sources: cli/Cargo.toml68-199

Developer Tools

The CLI provides integrated development tools sharing common infrastructure:

Tool	Command	Implementation	Description
Type checker	deno check	cli/tsc/	TypeScript type checking (TSC or TSGO)
Test runner	deno test	cli/tools/test.rs	Test execution with reporters
Benchmark	deno bench	cli/tools/bench.rs	Performance benchmarking
Linter	deno lint	deno_lint crate	JavaScript/TypeScript linting
Formatter	deno fmt	dprint-* plugins	Code formatting
LSP	deno lsp	cli/lsp/	Language Server Protocol
Documentation	deno doc	deno_doc crate	API documentation generator
Bundle	deno bundle	esbuild_client	Module bundling
Compile	deno compile	cli/tools/compile.rs	Standalone executable creation

Shared services (via CliFactory):

• ModuleGraphBuilder: Builds dependency graphs
• TypeChecker: Runs type checking
• CliNpmResolver: Resolves NPM packages
• Emitter: Transpiles TypeScript to JavaScript

Sources: cli/Cargo.toml68-199 Cargo.toml124-148

Configuration System

deno.json / deno.jsonc

Project configuration file supporting:

Section	Purpose
compilerOptions	TypeScript compiler settings
imports	Import map for specifier resolution
scopes	Scoped import maps
tasks	Task definitions (like npm scripts)
lint	Linter configuration
fmt	Formatter configuration
test	Test configuration
workspace	Workspace members for monorepos
nodeModulesDir	Enable/disable node_modules/ directory

Parsed by deno_config library: Cargo.toml126

deno.lock

Lock file for deterministic dependency resolution:

• Records exact versions of all dependencies
• Includes integrity checksums
• Auto-generated on first run (when not present)
• Can be committed to version control

Managed by deno_lockfile library: Cargo.toml131

Sources: Cargo.toml124-148

Release Channels and Versioning

Version Scheme

Semantic versioning: MAJOR.MINOR.PATCH

Recent stable releases: Releases.md9-200

• 2.6.9 (2026-02-10): Latest patch with Node.js compat improvements
• 2.6.8 (2026-02-02): Windows ARM builds, SQLite features
• 2.6.7 (2026-01-29): V8 14.5, cron socket implementation

Distribution Channels

Canary builds:

• Published on every commit to main branch
• URL: dl.deno.land/canary/<commit-sha>/
• For testing unreleased features
• Updated via: .github/workflows/ci.yml348-356

Stable builds:

• Published on tagged releases
• URL: dl.deno.land/release/<version>/
• Also on GitHub Releases page
• Install via deno upgrade or install scripts

Install methods:

• Shell script: curl -fsSL https://deno.land/install.sh | sh
• PowerShell: irm https://deno.land/install.ps1 | iex
• Package managers: Homebrew, Cargo, Chocolatey, Scoop

Sources: Releases.md1-600 .github/workflows/ci.yml348-356

Summary

Deno's codebase is organized as a modular, layered system:

Architecture layers:

1. CLI & LSP (cli/): User interface, tools, command dispatch
2. Runtime (runtime/): Worker management, event loop, bootstrap
3. Extensions (ext/): 20+ modular extensions for APIs
4. Platform: V8 JavaScript engine, Tokio async runtime, Rust stdlib

Key design principles:

• Modularity: Extension-based architecture with explicit dependencies
• Standards compliance: Web Platform API compatibility
• Node.js compatibility: 300+ polyfilled modules via deno_node
• Integrated tooling: Unified CLI for development tasks
• Multi-platform: Linux, macOS, Windows on x86_64 and aarch64

Workspace composition:

• 63+ Cargo crates in monorepo
• Centralized dependency management
• Optimized build profiles for release binaries
• Comprehensive CI/CD with 6+ platform targets

For deeper exploration of specific components, refer to the related pages listed at the beginning of this document.

Sources: Cargo.toml1-559 cli/Cargo.toml1-226 runtime/Cargo.toml1-116 ext/node/lib.rs1-528 .github/workflows/ci.yml1-3523