Contributing Guidelines

This is the main repository that provides the deno CLI.

If you want to fix a bug or add a new feature to deno this is the repository to contribute to.

Some systems, including a large part of the Node.js compatibility layer are implemented in JavaScript and TypeScript modules. These are a good place to start if you are looking to make your first contribution.

Here is a list of Node.js test cases, including both successful and failing ones. Reviewing these can provide valuable insight into how the compatibility layer works in practice, and where improvements might be needed. They can also serve as a useful guide for identifying areas where contributions are most impactful.

While iterating on such modules it is recommended to include --features hmr in your cargo flags. This is a special development mode where the JS/TS sources are not included in the binary but read at runtime, meaning the binary will not have to be rebuilt if they are changed.

To use the commands below, you need to first install the necessary tools on your system as described here.

# cargo build
cargo build --features hmr

# cargo run -- run hello.ts
cargo run --features hmr -- run hello.ts

# cargo test integration::node_unit_tests::os_test
cargo test --features hmr integration::node_unit_tests::os_test

Also remember to reference this feature flag in your editor settings. For VSCode users, combine the following into your workspace file:

{
  "settings": {
    "rust-analyzer.cargo.features": ["hmr"],
    // Adds support for resolving internal `ext:*` modules
    "deno.importMap": "tools/core_import_map.json"
  }
}

To use a development version of the LSP in VSCode:

Install and enable the Deno VSCode extension
Update your VSCode settings and point deno.path to your development binary:

// .vscode/settings.json
{
  "deno.path": "/path/to/your/deno/target/debug/deno"
}

Submitting a PR

In addition to the above make sure that:

To use the commands below, you need to first install the necessary tools on your system as described here.

cargo test passes - this will run full test suite for deno including unit tests, integration tests and Web Platform Tests
Run ./tools/format.js - this will format all of the code to adhere to the consistent style in the repository
Run ./tools/lint.js - this will check Rust and JavaScript code for common mistakes and errors using clippy (for Rust) and dlint (for JavaScript)

Building from source

Below are instructions on how to build Deno from source. If you just want to use Deno you can download a prebuilt executable (more information in the Getting Started chapter).

Cloning the Repository

Deno uses submodules, so you must remember to clone using --recurse-submodules.

Linux(Debian)/Mac/WSL:

git clone --recurse-submodules https://github.com/denoland/deno.git

Windows:

Enable "Developer Mode" (otherwise symlinks would require administrator privileges).
Make sure you are using git version 2.19.2.windows.1 or newer.

Set core.symlinks=true before the checkout:

git config --global core.symlinks true
git clone --recurse-submodules https://github.com/denoland/deno.git

Prerequisites

Rust

Deno requires a specific release of Rust. Deno may not support building on other versions, or on the Rust Nightly Releases. The version of Rust required for a particular release is specified in the rust-toolchain.toml file.

Update or Install Rust. Check that Rust installed/updated correctly:

rustc -V
cargo -V

Native Compilers and Linkers

Many components of Deno require a native compiler to build optimized native functions.

Linux(Debian)/WSL

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
./llvm.sh 17
apt install --install-recommends -y cmake libglib2.0-dev

Mac

Mac users must have the XCode Command Line Tools installed. (XCode already includes the XCode Command Line Tools. Run xcode-select --install to install it without XCode.)

CMake is also required, but does not ship with the Command Line Tools.

brew install cmake

Mac M1/M2

For Apple aarch64 users lld must be installed.

brew install llvm lld
# Add /opt/homebrew/opt/llvm/bin/ to $PATH

Windows

Get VS Community 2019 with the "Desktop development with C++" toolkit and make sure to select the following required tools listed below along with all C++ tools.
- Visual C++ tools for CMake
- Windows 10 SDK (10.0.17763.0)
- Testing tools core features - Build Tools
- Visual C++ ATL for x86 and x64
- Visual C++ MFC for x86 and x64
- C++/CLI support
- VC++ 2015.3 v14.00 (v140) toolset for desktop
Enable "Debugging Tools for Windows".
- Go to "Control Panel" → "Programs" → "Programs and Features"
- Select "Windows Software Development Kit - Windows 10"
- → "Change" → "Change" → Check "Debugging Tools For Windows" → "Change" →"Finish".
- Or use: Debugging Tools for Windows (Notice: it will download the files, you should install X64 Debuggers And Tools-x64_en-us.msi file manually.)

Protobuf Compiler

Building Deno requires the Protocol Buffers compiler.

Linux(Debian)/WSL

apt install -y protobuf-compiler
protoc --version  # Ensure compiler version is 3+

Mac

brew install protobuf
protoc --version  # Ensure compiler version is 3+

Windows

Windows users can download the latest binary release from GitHub.

Python 3

Deno requires Python 3 for running WPT tests. Ensure that a suffix-less python/python.exe exists in your PATH and it refers to Python 3.

Building Deno

The easiest way to build Deno is by using a precompiled version of V8.

For WSL make sure you have sufficient memory allocated in .wslconfig. It is recommended that you allocate at least 16GB.

cargo build -vv

However, you may also want to build Deno and V8 from source code if you are doing lower-level V8 development, or using a platform that does not have precompiled versions of V8:

V8_FROM_SOURCE=1 cargo build -vv

When building V8 from source, there may be more dependencies. See rusty_v8's README for more details about the V8 build.

Building

Build with Cargo:

# Build:
cargo build -vv

# Build errors?  Ensure you have latest main and try building again, or if that doesn't work try:
cargo clean && cargo build -vv

# Run:
./target/debug/deno run tests/testdata/run/002_hello.ts

Running the Tests

Deno has a comprehensive test suite written in both Rust and TypeScript. The Rust tests can be run during the build process using:

cargo test -vv

The TypeScript tests can be run using:

# Run all unit/tests:
target/debug/deno test -A --unstable --lock=tools/deno.lock.json --config tests/config/deno.json tests/unit

# Run a specific test:
target/debug/deno test -A --unstable --lock=tools/deno.lock.json --config tests/config/deno.json tests/unit/os_test.ts

Working with Multiple Crates

If a change-set spans multiple Deno crates, you may want to build multiple crates together. It's suggested that you checkout all the required crates next to one another. For example:

- denoland/
  - deno/
  - deno_core/
  - deno_ast/
  - ...

Then you can use Cargo's patch feature to override the default dependency paths:

cargo build --config 'patch.crates-io.deno_ast.path="../deno_ast"'

If you are working on a change-set for few days, you may prefer to add the patch to your Cargo.toml file (just make sure you remove this before staging your changes):

[patch.crates-io]
deno_ast = { path = "../deno_ast" }

This will build the deno_ast crate from the local path and link against that version instead of fetching it from crates.io.

Note: It's important that the version of the dependencies in the Cargo.toml match the version of the dependencies you have on disk.

Use cargo search <dependency_name> to inspect the versions.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!