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.

Macros and Functions

nodejs_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 Node.js that was available when the version of rules_nodejs you're using was released.

Forced version(s)

You can select the version of Node.js 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 Node.js repositories and URLs for node_repositories to use.

Custom Node.js versions

To specify custom Node.js versions, use the node_repositories attribute

nodejs_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

nodejs_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", "nodejs_repositories")

nodejs_repositories(
    # Unique name for the repository rule
    name = "",
)

name

Required.

Unique name for the repository rule

node_download_auth

Optional. Default: {}

Auth to use for all url requests.

Example: { "type": "basic", "login": "<UserName>", "password": "<Password>" }

node_repositories

Optional. Default: {}

Custom list of node repositories to use

A dictionary mapping Node.js 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 Node.js releases.

node_urls

Optional. Default: ["https://nodejs.org/dist/v{version}/{filename}"]

List of URLs to use to download Node.js.

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. Default: "18.20.4"

The specific version of Node.js to install

node_version_from_nvmrc

Optional. Default: None

The .nvmrc file containing the version of Node.js to use.

If set then the version found in the .nvmrc file is used instead of the one specified by node_version.

include_headers

Optional. Default: False

Set headers field in NodeInfo provided by this toolchain.

This setting creates a dependency on a c++ toolchain.

kwargs

Optional.

Additional parameters

nodejs_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 nodejs_toolchain definition:

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

nodejs_toolchain(
    name = "toolchain",
    node = "//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 = ":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.

Unique name for this target

node

Optional. Default: None

Node.js executable

node_path

Optional. Default: ""

Path to Node.js executable file

This is typically an absolute path to a non-hermetic Node.js executable.

Only one of node and node_path may be set.

npm

Optional. Default: None

Npm JavaScript entry point

npm_path

Optional. Default: ""

Path to npm JavaScript entry point.

This is typically an absolute path to a non-hermetic npm installation.

Only one of npm and npm_path may be set.

npm_srcs

Optional. Default: []

Additional source files required to run npm.

Not necessary if specifying npm_path to a non-hermetic npm installation.

headers

Optional. Default: None

cc_library that contains the Node/v8 header files

kwargs

Optional.

Additional parameters

Providers

UserBuildSettingInfo