rules_nodejs Bazel module
This is the "core" module, and is used internally by build_bazel_rules_nodejs
.
Most users should continue to use only the latter, and ignore this "core" module.
The dependency graph is:
build_bazel_rules_nodejs -> rules_nodejs -> bazel_skylib
Features:
- A Toolchain that fetches a hermetic copy of node, npm, and yarn - independent of what's on the developer's machine.
- Core Providers to allow interop between JS rules.
Most features, such as npm_install
and nodejs_binary
are still in the build_bazel_rules_nodejs
module.
We plan to clean these up and port into rules_nodejs
in a future major release.
Rules
directory_file_path
Provide DirectoryFilePathInfo to reference some file within a directory.
Otherwise there is no way to give a Bazel label for it.
Example usage (generated)
load("@build_bazel_rules_nodejs//nodejs:index.bzl", "directory_file_path")
directory_file_path(
# A unique name for this target.
name = "",
# a directory
directory = "",
# a path within that directory
path = "",
)
name
A unique name for this target.
directory
a directory
path
a path within that directory
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.
Note that you can skip calling node_repositories
in your WORKSPACE file - if you later try to yarn_install
or npm_install
,
we'll automatically select this simple usage for you.
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 and examples/vendored_node_and_yarn
.
Example usage (generated)
load("@build_bazel_rules_nodejs//nodejs:index.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
A unique name for this repository.
node_download_auth
auth to use for all url requests
Example: {"type": "basic", "login": "
node_repositories
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
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
the specific version of NodeJS to install
platform
Internal use only. Which platform to install as a toolchain. If unset, we assume the repository is named nodejs_[platform]
repo_mapping
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
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.
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:
toolchain(
name = "my_nodejs",
exec_compatible_with = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
],
toolchain = ":node_toolchain",
toolchain_type = "@rules_nodejs//nodejs:toolchain_type",
)
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
A unique name for this target.
run_npm
A template file that allows us to execute npm
target_tool
A hermetically downloaded nodejs executable target for the target platform.
target_tool_path
Path to an existing nodejs executable for the target platform.
yarn_repositories
Repository rule to fetch the yarnpkg.com package manager.
Note, the recommended name is "yarn". If you choose a different name, you'll have to override the
yarn
attribute in your yarn_install
rule to point to your yarn.js
file.
Custom Yarn versions
To specify custom Yarn versions, use the yarn_releases
attribute
yarn_repositories(
yarn_releases = {
"1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
},
)
Like node_urls
, the yarn_urls
attribute can be used to provide a list of custom URLs to use to download yarn
yarn_repositories(
yarn_releases = {
"1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
},
yarn_version = "1.12.1",
yarn_urls = [
"https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}",
],
)
Will download yarn from https://github.com/yarnpkg/yarn/releases/download/v1.2.1/yarn-v1.12.1.tar.gz
and expect the file to have sha256sum 09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d
.
If you don't use Yarn at all, you can skip downloading it by setting yarn_urls = []
.
Vendored yarn
You can vendor the yarn.js
file into your repo. In this case, don't call yarn_repositories
at all.
Just pass the label of your vendored file to the yarn
attribute of yarn_install
.
Example usage (generated)
load("@build_bazel_rules_nodejs//nodejs:index.bzl", "yarn_repositories")
yarn_repositories(
# A unique name for this repository.
name = "",
# A dictionary from local repository name to global repository name
repo_mapping = {},
)
name
A unique name for this repository.
node_repository
The basename for a nodejs toolchain to use for running yarn.
Usually this is the value of the name
attribute given to a nodejs_register_toolchains call in WORKSPACE
repo_mapping
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
).
yarn_download_auth
auth to use for all url requests
Example: {"type": "basic", "login": "
yarn_releases
Custom list of yarn releases to use.
Dictionary mapping Yarn versions to their corresponding (filename, strip_prefix, sha256) tuples.
By default, if this attribute has no items, we'll use a list of all public releases which is periodically mirrored to rules_nodejs.
yarn_urls
custom list of URLs to use to download Yarn
Each entry is a template using yarn_version
and yarn_releases
in the substitutions.
If this list is empty, we won't download yarn at all.
yarn_version
the specific version of Yarn to install
Macros and Functions
declaration_info
Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps.
Example usage (generated)
load("@build_bazel_rules_nodejs//nodejs:index.bzl", "declaration_info")
declaration_info(
# list of typings files
declarations = None,
)
declarations
list of typings files
deps
list of labels of dependencies where we should collect their DeclarationInfo to pass transitively
js_module_info
Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps.
Example usage (generated)
load("@build_bazel_rules_nodejs//nodejs:index.bzl", "js_module_info")
js_module_info(
# direct JS files
sources = None,
)
sources
direct JS files
deps
other targets that provide JSModuleInfo, typically from the deps attribute
Providers
DeclarationInfo
The DeclarationInfo provider allows JS rules to communicate typing information. TypeScript's .d.ts files are used as the interop format for describing types. package.json files are included as well, as TypeScript needs to read the "typings" property.
Do not create DeclarationInfo instances directly, instead use the declaration_info factory function.
Note: historically this was a subset of the string-typed "typescript" provider.
DirectoryFilePathInfo
Joins a label pointing to a TreeArtifact with a path nested within that directory.
JSModuleInfo
JavaScript files and sourcemaps.
LinkablePackageInfo
The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages