Skip to main content
Version: 6.0.x

rules_nodejs Bazel module


  • A Toolchain that fetches a hermetic copy of node and npm - independent of what's on the developer's machine.
  • Core Providers to allow interop between JS rules.



To be run in user's WORKSPACE to install rules_nodejs dependencies.

This rule sets up node, npm, and npx. The versions of these tools can be specified in one of three ways

Simplest Usage

Specify no explicit versions. This will download and use the latest NodeJS that was available when the version of rules_nodejs you're using was released.

Forced version(s)

You can select the version of NodeJS to download & use by specifying it when you call node_repositories, using a value that matches a known version (see the default values)

Using a custom version

You can pass in a custom list of NodeJS repositories and URLs for node_repositories to use.

Custom NodeJS versions

To specify custom NodeJS versions, use the node_repositories attribute

node_repositories = {
"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"),
"10.10.0-linux_amd64": ("node-v10.10.0-linux-x64.tar.xz", "node-v10.10.0-linux-x64", "686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"),
"10.10.0-windows_amd64": ("", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"),

These can be mapped to a custom download URL, using node_urls

node_version = "10.10.0",
node_repositories = {"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e")},
node_urls = ["https://mycorpproxy/mirror/node/v{version}/{filename}"],

A Mac client will try to download node from https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz and expect that file to have sha256sum 00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e

See the the repositories documentation for how to use the resulting repositories.

Using a custom node.js.

To avoid downloads, you can check in a vendored node.js binary or can build one from source. See toolchains.

Example usage (generated):

load("@rules_nodejs//nodejs:index.for_docs.bzl", "node_repositories")

# A unique name for this repository.
name = "",
# A dictionary from local repository name to global repository name
repo_mapping = {},


Required name.

A unique name for this repository.


Optional dictionary: String → String. Default: {}

auth to use for all url requests Example: {"type": "basic", "login": "<UserName>", "password": "<Password>" }


Optional dictionary: String → List of strings. Default: {}

Custom list of node repositories to use

A dictionary mapping NodeJS versions to sets of hosts and their corresponding (filename, strip_prefix, sha256) tuples. You should list a node binary for every platform users have, likely Mac, Windows, and Linux.

By default, if this attribute has no items, we'll use a list of all public NodeJS releases.


Optional list of strings. Default: ["{version}/{filename}"]

custom list of URLs to use to download NodeJS

Each entry is a template for downloading a node distribution.

The {version} parameter is substituted with the node_version attribute, and {filename} with the matching entry from the node_repositories attribute.


Optional string. Default: "18.18.0"

the specific version of NodeJS to install


Optional string. Default: ""

Internal use only. Which platform to install as a toolchain. If unset, we assume the repository is named nodejs_[platform]


Required dictionary: String → String.

A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).


Optional label. Default: None

the local path of the .nvmrc file containing the version of node

If set then also set node_version to the version found in the .nvmrc file.


Defines a node toolchain for a platform.

You can use this to refer to a vendored nodejs binary in your repository, or even to compile nodejs from sources using rules_foreign_cc or other rules.

First, in a BUILD.bazel file, create a node_toolchain definition:

load("@rules_nodejs//nodejs:toolchain.bzl", "node_toolchain")

name = "node_toolchain",
target_tool = "//some/path/bin/node",

Next, declare which execution platforms or target platforms the toolchain should be selected for based on constraints.

name = "my_nodejs",
exec_compatible_with = [
toolchain = ":node_toolchain",
toolchain_type = "@rules_nodejs//nodejs:toolchain_type",

See for more information on toolchain resolution.

Finally in your WORKSPACE, register it with register_toolchains("//:my_nodejs")

For usage see You can use the --toolchain_resolution_debug flag to bazel to help diagnose which toolchain is selected.


Required name.

A unique name for this target.


Optional label. Default: None

A cc_library that contains the Node/v8 header files for this target platform.


Optional label. Default: None

A hermetically downloaded npm executable target for this target's platform.


Optional list of labels. Default: []

Files required in runfiles to run npm.


Optional string. Default: ""

Path to an existing npm executable for this target's platform.


Optional label. Default: None

A template file that allows us to execute npm


Optional label. Default: None

A hermetically downloaded nodejs executable target for this target's platform.


Optional string. Default: ""

Path to an existing nodejs executable for this target's platform.