Main Deno repositories
The denoland organization on GitHub contains numerous repositories that are part of the Deno ecosystem. Key repositories include: deno (main CLI, Rust/JavaScript/TypeScript), deno_std (standard library, TypeScript/WebAssembly), fresh (next-gen web framework, TypeScript/TSX), deno_lint (linter powering deno lint, Rust), deno_doc (documentation generator powering deno doc, Rust), rusty_v8 (V8 JavaScript engine bindings, Rust), serde_v8 (bijection layer between V8 and Rust objects, Rust), and deno_docker (official Docker images).
Pull request requirements before submission
Before submitting a pull request: (1) give the PR a descriptive title that describes the change and affected component (e.g., 'fix(std/http): fix race condition in server' or 'feat(doc): handle nested re-exports'); (2) ensure there is a related issue referenced in the PR text; (3) ensure there are tests that cover the changes.
JSDoc requirements for JavaScript and TypeScript APIs
All publicly exposed APIs and types in JavaScript and TypeScript, both via the deno module and the global/window namespace, must have JSDoc documentation. JSDoc blocks come just prior to the statement they apply to and are denoted by a leading /** before terminating with */. Example: /** A simple JSDoc comment */ export const FOO = "foo";
Before starting work on issues or features
If you plan to work on an issue, mention so in the issue's comments before you start working. If you plan to work on a new feature, create an issue and discuss with other contributors before you start working on the feature, as not all proposed features will be accepted.
Profiling with Samply
Samply is a sampling profiler for macOS and Linux that works well with Deno and produces flamegraphs. Basic usage is: samply record -r 20000 deno run -A main.js. The generated flamegraph can be analyzed to identify hot spots where most CPU time is spent, unexpected function calls, and potential areas for optimization.
Code of conduct for Deno contributors
Contributors must be professional in forums and follow Rust's code of conduct. If there is a problem, email ry@tinyclouds.org.
Copyright header for Deno runtime and std
Most modules in the Deno repository should have the copyright header: `// Copyright 2018-2026 the Deno authors. All rights reserved. MIT license.` If code originates elsewhere, ensure the file has the proper copyright headers. Only MIT, BSD, and Apache licensed code is allowed.
Use underscores in filenames, not dashes
Filenames in the Deno codebase should use underscores instead of dashes. For example, use `file_server.ts` instead of `file-server.ts`.
Add tests for new features
Each module should contain or be accompanied by tests for its public functionality.
TODO comment format
TODO comments should include an issue number or the author's GitHub username in parentheses. Examples: `// TODO(ry): Add tests.`, `// TODO(#123): Support Windows.`, `// FIXME(#349): Sometimes panics.`
Avoid meta-programming and Proxy
Meta-programming, including the use of Proxy, is discouraged in Deno code. Be explicit, even when it means more code. There are few situations where such techniques make sense, but in the vast majority of cases they do not.
Follow inclusive code guidelines
Follow the guidelines for inclusive code outlined at https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/inclusive_code.md.
Use TypeScript instead of JavaScript in std
The TypeScript portion of the Deno codebase is the standard library `std`. Use TypeScript instead of JavaScript for standard library modules.
Do not use index.ts or index.js filenames
Deno does not treat 'index.js' or 'index.ts' in a special way. Using these filenames suggests they can be left out of the module specifier when they cannot, which is confusing. If a directory needs a default entry point, use `mod.ts` instead, which follows Rust's convention, is shorter than `index.ts`, and doesn't come with preconceived notions about how it might work.
Exported functions should have max 2 required arguments
Functions that are part of the public API should take 0-2 required arguments, plus an optional options object if necessary, for a maximum of 3 total arguments. Optional parameters should generally go into the options object. The 'options' argument is the only argument that should be a regular 'Object'. Other object arguments must be distinguishable from a plain Object at runtime by having either a distinguishing prototype (e.g., Array, Map, Date, class) or a well-known symbol property (e.g., Symbol.iterator for iterables). This allows the API to evolve in a backwards-compatible way even when the options object position changes.
Export all interfaces used in public API parameters
Whenever interfaces are used in the parameters or return type of an exported member, the interface should also be exported. For example, if exporting a function that returns a Person interface, export the Person interface as well.
Minimize dependencies and avoid circular imports
Although std has no external dependencies, internal dependencies must be kept simple and manageable. In particular, be careful not to introduce circular imports.
Files starting with underscore are internal and unstable
If a filename starts with an underscore (e.g., `_foo.ts`), do not link to it from outside. Such files are internal modules with unstable APIs. By convention, only files in its own directory should import it.
Use JSDoc for exported symbols
Every exported symbol should ideally have a documentation line. Single-line JSDoc should be written as `/** foo does bar. */` on one line rather than across multiple lines. JSDoc should generally follow markdown markup to enrich the text, but HTML tags are forbidden in JSDoc blocks. Code string literals should be wrapped with backticks (`) instead of quotes.
JSDoc @param tags for exported functions
Every exported function should have a `@param` tag for each parameter with a description. The `@param` tag should not include the type, as TypeScript is already strongly-typed. Example: `@param path The path to resolve.`
Code examples in JSDoc format
Code examples in JSDoc should utilize markdown format with triple backticks and a language specifier (e.g., ```ts). Code examples should not contain additional comments and must not be indented. If the example needs further comments, it is not a good example.
Resolve linting problems with deno-lint-ignore directive
Use the `deno-lint-ignore <code>` directive to suppress linting warnings when code must be non-conformant for valid reasons. For example: `// deno-lint-ignore no-explicit-any` before `let x: any;`. This directive should be used sparingly to ensure the CI process doesn't fail.
Test module naming and location
Every module with public functionality `foo.ts` should come with a test module `foo_test.ts`. For std modules, tests should go in `std/tests` due to different contexts. For other modules, the test module should be a sibling to the tested module.
Unit tests should be explicitly named
Test functions should be correctly named to clearly describe what they test. The test name is displayed in the test command output and should be descriptive. Example: `Deno.test("foo() returns bar object", function () { assertEquals(foo(), { bar: "bar" }); });`
Top-level functions should use function keyword, not arrow syntax
Top-level functions should use the `function` keyword rather than arrow function syntax. Arrow syntax should be limited to closures. Regular functions and arrow functions have different behavior regarding hoisting, binding, arguments, and constructability. The `function` keyword clearly indicates the intent to define a function, improving legibility and debuggability. Good: `export function foo(): string { return "bar"; }`. Bad: `export const foo = (): string => { return "bar"; };`
Error message formatting rules
User-facing error messages should follow these rules: (1) Start with uppercase, (2) Do not end with a period, (3) Use quotes for string values, (4) State the action that led to the error using active voice, (5) Do not use contractions, (6) Use a colon when providing additional information; periods should never be used, (7) Additional information should describe the current state and ideally also the desired state. Examples: Good: "Cannot parse input" or "Cannot parse input \"hello, world\"". Bad: "cannot parse input." or "Input x cannot be parsed".
std should not depend on external code
The https://jsr.io/@std standard library is intended to be baseline functionality that all Deno programs can rely on. It must not include potentially unreviewed third-party code.
Document and maintain browser compatibility in std
If a std module is browser-compatible, include the comment `// This module is browser-compatible.` at the top of the module JSDoc. Maintain browser compatibility by either not using the global `Deno` namespace or by feature-testing for it. Ensure any new dependencies are also browser-compatible.
Prefer private fields (#) over private keyword
In the standard library codebase, prefer the private fields syntax (`#`) over TypeScript's `private` keyword. Private fields make properties and methods private at runtime, while the `private` keyword only guarantees privacy at compile time and fields remain publicly accessible at runtime. Good: `class MyClass { #foo = 1; #bar() {} }`. Bad: `class MyClass { private foo = 1; private bar() {} }`
Naming convention: camelCase, PascalCase, UPPER_SNAKE_CASE
Use `camelCase` for functions, methods, fields, and local variables. Use `PascalCase` for classes, types, interfaces, and enums. Use `UPPER_SNAKE_CASE` for static top-level items such as static strings, numbers, bigints, booleans, RegExp, arrays of static items, and records of static keys and values. When names are in camelCase or PascalCase, always follow the rules even when parts are acronyms. For example, use `class HttpObject {}` not `class HTTPObject {}`, and `function convertUrl(url: URL)` not `function convertURL(url: URL)`.