Toolchains

API docs for Toolchain support.

When you call nodejs_register_toolchains() in your WORKSPACE file it will setup a node toolchain for executing tools on all currently supported platforms. In bzlmod default toolchains are registered automatically when you depend on rules_nodejs.

There are two toolchain types:

1. The transpilation toolchain, which provides the Node runtime used to execute the transpiler (and type checker), as well as various helper tools and settings. (@rules_nodejs//nodejs:toolchain_type)
2. The Node runtime that executable Node outputs (e.g., js_binary) will run on. (@rules_nodejs//nodejs:runtime_toolchain_type)

See //nodjes/BUILD.bazel for details.

If you have an advanced use-case and want to use a version of node not supported by this repository, you can also register your own toolchains.

Registering a custom toolchain

To run a custom toolchain (i.e., to run a node binary not supported by the built-in toolchains), you'll need four things:

1. A rule which can build or load a node binary from your repository (a checked-in binary or a build using a relevant rules_foreign_cc build rule will do nicely).
2. A nodejs_toolchain rule which depends on your binary defined in step 1 as its node.
3. Two toolchain rules each depends on your nodejs_toolchain rule defined in step 2 as its toolchain and one on @rules_nodejs//nodejs:toolchain_type as its toolchain_type and the other one @rules_nodejs//nodejs:runtime_toolchain_type. Make sure to define appropriate platform restrictions as described in the documentation for the toolchain rule.
4. A call to the register_toolchains function in your WORKSPACE that refers to the toolchain rule defined in step 3.

Examples of steps 2-4 can be found in the documentation for nodejs_toolchain.

If necessary, you can substitute building the node binary as part of the build with using a locally installed version by skipping step 1 and replacing step 2 with:

2. A nodejs_toolchain rule which has the path of the system binary as its node_path