CLAUDE.md

1# Deno Development Guide
2 
3## Table of Contents
4 
5- [Git workflow](#git-workflow)
6- [High Level Overview](#high-level-overview)
7- [Quick Start](#quick-start)
8- [Commands](#commands)
9- [Testing](#testing)
10- [Development Workflows](#development-workflows)
11- [Debugging](#debugging)
12- [Codebase Navigation](#codebase-navigation)
13- [Troubleshooting](#troubleshooting)
14 
15## Git workflow
16 
17Deno uses a GH based standard git workflow. The main branch is `main`. All
18development happens in feature branches, which are then merged into `main` via
19pull requests.
20 
21When the feature is finished and ready to for review, follow these steps:
22 
23- Create a new git branch, if you haven't already, with a descriptive name
24  (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).
25- Commit your changes with clear and descriptive commit messages.
26- Push your branch to the remote repository.
27- Open a pull request (PR) against the `main` branch on GitHub.
28- Before committing, make sure `tools/format.js` is run to format your code
29- Before committing, if only non-Rust was changed, make sure to run
30  `tools/lint.js --js` and fix any lint errors before committing
31- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint
32  errors before committing
33- In the PR description, provide a clear summary of the changes you made, why
34  they were necessary, and any relevant context or links to related issues.
35- When pushing updates to the PR, make sure to never force push. Create as many
36  commits as you need, all of them get squashed when the PR is merged, so there
37  is no need to rewrite history. This also allows reviewers to see the
38  incremental changes you made in response to feedback.
39- Keep your changes minimal, don't do drive-by changes in a PR. If you need to
40  make a change that is not directly related to the PR, create a separate PR for
41  it. This keeps the review process focused and efficient.
42 
43## High Level Overview
44 
45The user visible interface and high level integration is in the `deno` crate
46(located in `./cli`).
47 
48This includes flag parsing, subcommands, package management tooling, etc. Flag
49parsing is in `cli/args/flags.rs`. Tools are in `cli/tools/<tool>`.
50 
51The `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,
52including all "extensions" (native functionality exposed to JavaScript). The
53extensions themselves are in the `ext/` directory, and provide system access to
54JavaScript – for instance filesystem operations and networking.
55 
56### Key Directories
57 
58- `cli/` - User-facing CLI implementation, subcommands, and tools
59- `runtime/` - JavaScript runtime assembly and integration
60- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)
61- `tests/specs/` - Integration tests (spec tests)
62- `tests/unit/` - Unit tests
63- `tests/testdata/` - Test fixtures and data files
64 
65## Quick Start
66 
67Before building, install the required prerequisites (Rust, native compilers,
68cmake, protobuf, etc.) and clone with `--recurse-submodules` as described in
69[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).
70 
71### Building Deno
72 
73To compile after making changes:
74 
75```bash
76cargo build
77```
78 
79For faster iteration during development (less optimization):
80 
81```bash
82cargo build --bin deno
83```
84 
85Execute your development build:
86 
87```bash
88./target/debug/deno eval 'console.log("Hello from dev build")'
89```
90 
91### Running with your changes
92 
93```bash
94# Run a local file
95./target/debug/deno run path/to/file.ts
96 
97# Run with permissions
98./target/debug/deno run --allow-net --allow-read script.ts
99 
100# Run the REPL
101./target/debug/deno
102```
103 
104## Commands
105 
106### Compilation and Checks
107 
108```bash
109# Check for compilation errors (fast, no binary output)
110cargo check
111 
112# Check specific package
113cargo check -p deno_runtime
114 
115# Build release version (slow, optimized)
116cargo build --release
117```
118 
119### Code Quality
120 
121```bash
122# Lint the code
123./tools/lint.js
124 
125# Format the code
126./tools/format.js
127 
128# Both lint and format
129./tools/format.js && ./tools/lint.js
130```
131 
132## Testing
133 
134### Running Tests
135 
136```bash
137# Run all tests (this takes a while)
138cargo test
139 
140# Filter tests by name
141cargo test &lt;nameOfTest&gt;
142 
143# Run tests in a specific package
144cargo test -p deno_core
145 
146# Run just the CLI integration tests
147cargo test --bin deno
148 
149# Run spec tests only
150cargo test specs
151 
152# Run a specific spec test
153cargo test spec::test_name
154```
155 
156### Unit Tests (`tests/unit/`)
157 
158JavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run
159them via `cargo test`:
160 
161```bash
162# Run all unit tests in a specific file
163cargo test unit::webcrypto_test
164 
165# Run all unit tests
166cargo test unit::
167 
168# Run Node.js compatibility unit tests (tests/unit_node/)
169cargo test unit_node::crypto_test
170 
171# Run all Node.js compat unit tests
172cargo test unit_node::
173```
174 
175Do NOT run these directly with `./target/debug/deno test` — they depend on the
176cargo test harness for correct setup.
177 
178### Test Organization
179 
180- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command
181  execution and output validation
182- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime
183  APIs
184- **Integration tests** (`tests/integration/`) - Additional integration tests
185- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance
186 
187## "spec" tests
188 
189The main form of integration test in deno is the "spec" test. These tests can be
190found in `tests/specs`. The idea is that you have a `__test__.jsonc` file that
191lays out one or more tests, where a test is a CLI command to execute and the
192output is captured and asserted against.
193 
194The name of the test comes from the directory the `__test__.jsonc` appears in.
195 
196### Creating a New Spec Test
197 
1981. Create a directory in `tests/specs/` with a descriptive name
1992. Add a `__test__.jsonc` file describing your test steps
2003. Add any input files needed for the test
2014. Add `.out` files for expected output (or inline in `__test__.jsonc`)
202 
203Example:
204 
205```
206tests/specs/my_feature/
207  __test__.jsonc
208  main.ts
209  expected.out
210```
211 
212### `__test__.jsonc` schema
213 
214The schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.
215 
216Example test structure:
217 
218```jsonc
219{
220  "tests": {
221    "basic_case": {
222      "args": "run main.ts",
223      "output": "expected.out"
224    },
225    "with_flag": {
226      "steps": [
227        {
228          "args": "run --allow-net main.ts",
229          "output": "[WILDCARD]success[WILDCARD]"
230        }
231      ]
232    }
233  }
234}
235```
236 
237### Output assertions
238 
239The expected output can be inline in a `__test__.jsonc` file or in a file ending
240with `.out`. For a given test step, the `output` field tells you either the
241inline expectation or the name of the file containing the **expectation**. The
242expectation uses a small matching language to support wildcards and things like
243that. A literal character means you expect that exact character, so `Foo bar`
244would expect the output to be "Foo bar". Then there are things with special
245meanings:
246 
247- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this
248  can cross newlines
249- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line
250- `[WILDCHAR]` - match the next character
251- `[WILDCHARS(5)]` - match any of the next 5 characters
252- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match
253  the lines in any order (useful for non-deterministic output)
254- `[# example]` - line comments start with `[#` and end with `]`
255 
256Example `.out` file:
257 
258```
259Check file://[WILDCARD]/main.ts
260[WILDCARD]
261Successfully compiled [WILDLINE]
262```
263 
264## Development Workflows
265 
266### Adding a New CLI Subcommand
267 
2681. Define the command structure in `cli/args/flags.rs`
2692. Add the command handler in `cli/tools/<command_name>.rs` or
270   `cli/tools/<command_name>/mod.rs`
2713. Wire it up in `cli/main.rs`
2724. Add spec tests in `tests/specs/<command_name>/`
273 
274Example files to reference:
275 
276- Simple command: `cli/tools/fmt.rs`
277- Complex command: `cli/tools/test/`
278 
279### Modifying or Adding an Extension
280 
2811. Navigate to `ext/<extension_name>/` (e.g., `ext/fs/`, `ext/net/`)
2822. Rust code provides the ops (operations) exposed to JavaScript
2833. JavaScript code in the extension provides the higher-level APIs
2844. Update `runtime/worker.rs` to register the extension if new
2855. Add tests in the extension's directory
286 
287### Updating Dependencies
288 
289```bash
290# Update Cargo dependencies
291cargo update
292 
293# Update to latest compatible versions
294cargo upgrade  # Requires cargo-edit: cargo install cargo-edit
295 
296# Check for outdated dependencies
297cargo outdated  # Requires cargo-outdated
298```
299 
300## Debugging
301 
302### Debugging Rust Code
303 
304Use `lldb` directly:
305 
306```bash
307lldb ./target/debug/deno
308(lldb) run eval 'console.log("test")'
309```
310 
311### Debugging JavaScript Runtime Issues
312 
313Use println debugging.
314 
315### Verbose Logging
316 
317```bash
318# Set Rust log level
319DENO_LOG=debug ./target/debug/deno run script.ts
320 
321# Specific module logging
322DENO_LOG=deno_core=debug ./target/debug/deno run script.ts
323```
324 
325### Debug Prints
326 
327In Rust code:
328 
329```rust
330eprintln!("Debug: {:?}", some_variable);
331dbg!(some_variable);
332```
333 
334In JavaScript/TypeScript code:
335 
336```javascript
337console.log("Debug:", value);
338```
339 
340## Codebase Navigation
341 
342### Key Files to Understand First
343 
3441. `cli/main.rs` - Entry point, command routing
3452. `cli/args/flags.rs` - CLI flag parsing and structure
3463. `runtime/worker.rs` - Worker/runtime initialization
3474. `runtime/permissions.rs` - Permission system
3485. `cli/module_loader.rs` - Module loading and resolution
349 
350### Common Patterns
351 
352- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)
353- **Extensions** - Collections of ops and JS code providing functionality
354- **Workers** - JavaScript execution contexts (main worker, web workers)
355- **Resources** - Managed objects passed between Rust and JS (files, sockets,
356  etc.)
357 
358### Finding Examples
359 
360- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`
361- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,
362  `ext/fs/lib.rs`)
363- Need to add a tool? Reference existing tools in `cli/tools/`
364 
365## Troubleshooting
366 
367### Build Failures
368 
369**Error: linking with `cc` failed**
370 
371- Make sure you have the required system dependencies
372- On macOS: `xcode-select --install`
373- On Linux: Install `build-essential` or equivalent
374 
375**Error: failed to download dependencies**
376 
377- Check internet connection
378- Try `cargo clean` then rebuild
379- Check if behind a proxy, configure cargo accordingly
380 
381For other build failures (missing `cmake`, `stdarg.h`, etc.), see the full
382prerequisites in
383[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).
384 
385### Test Failures
386 
387**Spec test failures**
388 
389- Check the test output carefully for differences
390- Update `.out` files if output format changed intentionally
391- Use `[WILDCARD]` for non-deterministic parts of output
392 
393**Flaky tests**
394 
395- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output
396- Check for race conditions in test code
397- May need to increase timeouts or add retries
398 
399### Permission Issues
400 
401**Tests failing with permission errors**
402 
403- Ensure test files have correct permissions
404- Check that test setup properly grants necessary permissions
405 
406### Performance Issues
407 
408**Slow compile times**
409 
410- Use `cargo check` instead of `cargo build` when possible
411- Use `--bin deno` to build only the main binary
412- Use `sccache` or `mold` linker for faster builds
413- Consider using `cargo-watch` for incremental builds
414 
415### Runtime Debugging
416 
417**Crashes or panics**
418 
419- Run with `RUST_BACKTRACE=1` for full backtrace
420- Use `RUST_BACKTRACE=full` for even more detail
421- Check for unwrap() calls that might panic
422 
423**Unexpected behavior**
424 
425- Add debug prints liberally
426- Check permission grants - many features require explicit permissions
427 
428### Getting Help
429 
430- Check existing issues on GitHub
431- Look at recent PRs for similar changes
432- Review the Discord community for discussions
433- When in doubt, ask! The maintainers are helpful
434