Skip to main content
Version: 6.0.x

rules_nodejs Bazel module

Features:

  • 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.

Rules

node_repositories​

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(
    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.zip", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"),
    },
)

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

node_repositories(
    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")

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

name​

Required name.

A unique name for this repository.

node_download_auth​

Optional dictionary: String → String. Default: {}

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

node_repositories​

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.

node_urls​

Optional list of strings. Default: ["https://nodejs.org/dist/v{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.

node_version​

Optional string. Default: "18.16.1"

the specific version of NodeJS to install

platform​

Optional string. Default: ""

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

repo_mapping​

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).

use_nvmrc​

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.

node_toolchain​

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")

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.

toolchain(
    name = "my_nodejs",
    exec_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":node_toolchain",
    toolchain_type = "@rules_nodejs//nodejs:toolchain_type",
)

See https://bazel.build/extending/toolchains#toolchain-resolution for more information on toolchain resolution.

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

For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains. You can use the --toolchain_resolution_debug flag to bazel to help diagnose which toolchain is selected.

name​

Required name.

A unique name for this target.

npm​

Optional label. Default: None

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

npm_files​

Optional list of labels. Default: []

Files required in runfiles to run npm.

npm_path​

Optional string. Default: ""

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

run_npm​

Optional label. Default: None

A template file that allows us to execute npm

target_tool​

Optional label. Default: None

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

target_tool_path​

Optional string. Default: ""

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

Providers

UserBuildSettingInfo​

Last updated on by Alex Eagle