Development Guide

This guide covers the essential workflows and commands for developing Deno.

Quick Development Commands

Building and Running

# Fast iteration (less optimization)
cargo build --bin deno

Code Quality

./tools/format.js

Testing

Running Tests

# Warning: This takes a while!
cargo test

Test Organization

Deno uses several types of tests:

Spec Tests

Location: tests/specs/Main integration tests that execute CLI commands and validate output.

Unit Tests

Location: Inline with source codeTest individual functions and modules.

Integration Tests

Location: cli/tests/Additional integration tests for CLI functionality.

Web Platform Tests

Location: tests/wpt/Tests for web standards compliance.

Spec Tests

The main form of integration test in Deno is the “spec” test. These tests execute CLI commands and assert against their output.

Creating a Spec Test

Create test directory

Create a directory in tests/specs/ with a descriptive name:

mkdir tests/specs/my_feature

Add test configuration

Create __test__.jsonc to describe your test steps:

tests/specs/my_feature/__test__.jsonc

{
  "tests": {
    "basic_case": {
      "args": "run main.ts",
      "output": "expected.out"
    },
    "with_permissions": {
      "args": "run --allow-net main.ts",
      "output": "[WILDCARD]success[WILDCARD]"
    }
  }
}

Add test files

Add input files and expected output:

tests/specs/my_feature/main.ts

console.log("Hello, Deno!");

tests/specs/my_feature/expected.out

Hello, Deno!

Run your test

cargo test spec::my_feature

Output Matching

Spec test output files support special matching syntax:

[WILDCARD] - Matches 0 or more of any character (like .* in regex), can cross newlines
[WILDLINE] - Matches 0 or more characters until end of line
[WILDCHAR] - Match the next character
[WILDCHARS(5)] - Match any of the next 5 characters
[UNORDERED_START] … [UNORDERED_END] - Match lines in any order (useful for non-deterministic output)
[# comment] - Line comments

Example:

expected.out

Check file://[WILDCARD]/main.ts
[WILDCARD]
Successfully compiled [WILDLINE]

Development Workflows

Adding a New CLI Subcommand

Define command flags

Add your command structure in cli/args/flags.rs

Create command handler

Add the command handler in cli/tools/<command_name>.rs or cli/tools/<command_name>/mod.rsReference examples:

Simple command: cli/tools/fmt.rs
Complex command: cli/tools/test/

Wire up the command

Connect your command in cli/main.rs (actually cli/lib.rs)

Add tests

Create spec tests in tests/specs/<command_name>/

Modifying or Adding an Extension

Extensions provide native functionality to JavaScript (filesystem, networking, etc.).

Navigate to extension

Extensions are in ext/<extension_name>/ (e.g., ext/fs/, ext/net/)

Implement ops

Rust code provides the “ops” (operations) exposed to JavaScript

Add JavaScript APIs

JavaScript code in the extension provides higher-level APIs

For new extensions, update runtime/worker.rs to register it

Add tests

Add tests in the extension’s directory

Updating Dependencies

cargo update

Debugging

Debugging Rust Code

Using an IDE Debugger

Set breakpoints in Rust code
Run tests in debug mode through your IDE (VS Code with rust-analyzer, IntelliJ IDEA, etc.)

Using LLDB

lldb ./target/debug/deno
(lldb) run eval 'console.log("test")'

Debugging JavaScript Runtime

Enable the V8 inspector and connect Chrome DevTools:

./target/debug/deno run --inspect-brk script.ts
# Then open chrome://inspect in Chrome

Verbose Logging

DENO_LOG=debug ./target/debug/deno run script.ts

Debug Prints

In Rust code:

eprintln!("Debug: {:?}", some_variable);
dbg!(some_variable);

In JavaScript runtime:

console.log("Debug:", value);

Backtraces

For crashes or panics:

RUST_BACKTRACE=1 ./target/debug/deno run script.ts

Troubleshooting

Build Failures

Error: linking with `cc` failed

Make sure you have the required system dependencies:

macOS: xcode-select --install
Linux: Install build-essential or equivalent

Error: failed to download dependencies

Check your internet connection
Try cargo clean then rebuild
If behind a proxy, configure cargo accordingly

Slow compile times

Use cargo check instead of cargo build when possible
Use --bin deno to build only the main binary
Consider using sccache or mold linker for faster builds
Use cargo-watch for incremental builds

Test Failures

Spec test failures

Check the test output carefully for differences
Update .out files if output format changed intentionally
Use [WILDCARD] for non-deterministic parts of output

Flaky tests

Add [UNORDERED_START]/[UNORDERED_END] for order-independent output
Check for race conditions in test code
May need to increase timeouts or add retries

Permission errors in tests

Ensure test files have correct permissions
Check that test setup properly grants necessary permissions

Key Files to Understand

cli/main.rs

Entry point and command routing

cli/args/flags.rs

CLI flag parsing and structure

runtime/worker.rs

Worker/runtime initialization

runtime/permissions.rs

Permission system implementation

cli/module_loader.rs

Module loading and resolution

Common Patterns

Ops - Rust functions exposed to JavaScript (in ext/ directories)
Extensions - Collections of ops and JS code providing functionality
Workers - JavaScript execution contexts (main worker, web workers)
Resources - Managed objects passed between Rust and JS (files, sockets, etc.)

Finding Examples

Adding a CLI flag?

Look at similar commands in cli/args/flags.rs

Adding an op?

Look at ops in relevant ext/ directory (e.g., ext/fs/lib.rs)

Adding a tool?

Reference existing tools in cli/tools/

Performance Tips

Fast Iteration

Use cargo build --bin deno for faster builds during development

Type Checking

Use cargo check instead of cargo build when you only need to verify compilation

Incremental Builds

Install cargo-watch for automatic rebuilds on file changes

Faster Linking

Use sccache or the mold linker to speed up linking

Getting Help

When you’re stuck:

Check existing issues on GitHub
Look at recent PRs for similar changes
Search the Discord community for discussions
Ask the maintainers - they’re helpful and responsive!

Need Help?

Join the Deno Discord community for real-time help and discussions

Get Involved

Development

Guidelines

​Quick Development Commands

​Building and Running

​Code Quality

​Testing

​Running Tests

​Test Organization

Spec Tests

Unit Tests

Integration Tests

Web Platform Tests

​Spec Tests

​Creating a Spec Test

​Output Matching

​Development Workflows

​Adding a New CLI Subcommand

​Modifying or Adding an Extension

​Updating Dependencies

​Debugging

​Debugging Rust Code

​Using an IDE Debugger

​Using LLDB

​Debugging JavaScript Runtime

​Verbose Logging

​Debug Prints

​Backtraces

​Troubleshooting

​Build Failures

​Test Failures

​Codebase Navigation

​Key Files to Understand

cli/main.rs

cli/args/flags.rs

runtime/worker.rs

runtime/permissions.rs

cli/module_loader.rs

​Common Patterns

​Finding Examples

​Performance Tips

Fast Iteration

Type Checking

Incremental Builds

Faster Linking

​Getting Help

Need Help?

Build docs developers (and LLMs) love

Quick Development Commands

Building and Running

Code Quality

Testing

Running Tests

Test Organization

Spec Tests

Creating a Spec Test

Output Matching

Development Workflows

Adding a New CLI Subcommand

Modifying or Adding an Extension

Updating Dependencies

Debugging

Debugging Rust Code

Using an IDE Debugger

Using LLDB

Debugging JavaScript Runtime

Verbose Logging

Debug Prints

Backtraces

Troubleshooting

Build Failures

Test Failures

Codebase Navigation

Key Files to Understand

Common Patterns

Finding Examples

Performance Tips

Getting Help