Built-in rules
+ +These rules are available without any npm installation, via the WORKSPACE install of the build_bazel_rules_nodejs workspace. This is necessary to bootstrap Bazel to run the package manager to download other rules from NPM.
node_repositories
+ +USAGE
+ ++node_repositories(name, node_download_auth, node_repositories, node_urls, node_version, + package_json, preserve_symlinks, repo_mapping, vendored_node, vendored_yarn, + yarn_download_auth, yarn_repositories, yarn_urls, yarn_version) ++ +
To be run in user’s WORKSPACE to install rules_nodejs dependencies.
+ +This rule sets up node, npm, and yarn. 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 & Yarn that were 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 and/or Yarn 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 and/or Yarn repositories and URLs for node_resositories 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
Custom Yarn versions
+ +To specify custom Yarn versions, use the yarn_repositories attribute
node_repositories(
+ yarn_repositories = {
+ "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
node_repositories(
+ yarn_repositories = {
+ "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.
Using a local version
+ +To avoid downloads, you can check in vendored copies of NodeJS and/or Yarn and set vendored_node and or vendored_yarn +to point to those before calling node_repositories. You can also point to a location where node is installed on your computer, +but we don’t recommend this because it leads to version skew between you, your coworkers, and your Continuous Integration environment. +It also ties your build to a single platform, preventing you from cross-compiling into a Linux docker image on Mac for example.
+ +See the the repositories documentation for how to use the resulting repositories.
+ +Manual install
+ +You can optionally pass a package_json array to node_repositories. This lets you use Bazel’s version of yarn or npm, yet always run the package manager yourself.
+This is an advanced scenario you can use in place of the npm_install or yarn_install rules, but we don’t recommend it, and might remove it in the future.
load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")
+node_repositories(package_json = ["//:package.json", "//subpkg:package.json"])
+Running bazel run @nodejs//:yarn_node_repositories in this repo would create /node_modules and /subpkg/node_modules.
Note that the dependency installation scripts will run in each subpackage indicated by the package_json attribute.
ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this repository.
+ +node_download_auth
+ +(Dictionary: String -> String): auth to use for all url requests
+Example: {“type”: “basic”, “login”: “
Defaults to {}
node_repositories
+ +(Dictionary: String -> List of strings): 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.
+ +Defaults to {}
node_urls
+ +(List of strings): 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.
Defaults to ["https://nodejs.org/dist/v{version}/{filename}"]
node_version
+ +(String): the specific version of NodeJS to install or, if vendored_node is specified, the vendored version of node
+ +Defaults to "12.13.0"
package_json
+ +(List of labels): (ADVANCED, not recommended)
+ a list of labels, which indicate the package.json files that will be installed
+ when you manually run the package manager, e.g. with
+ bazel run @nodejs//:yarn_node_repositories or bazel run @nodejs//:npm_node_repositories install.
+ If you use bazel-managed dependencies, you should omit this attribute.
Defaults to []
preserve_symlinks
+ +(Boolean): Turn on –node_options=–preserve-symlinks for nodejs_binary and nodejs_test rules.
+ +When this option is turned on, node will preserve the symlinked path for resolves instead of the default +behavior of resolving to the real path. This means that all required files must be in be included in your +runfiles as it prevents the default behavior of potentially resolving outside of the runfiles. For example, +all required files need to be included in your node_modules filegroup. This option is desirable as it gives +a stronger guarantee of hermeticity which is required for remote execution.
+ +Defaults to True
repo_mapping
+ +(Dictionary: String -> String, mandatory): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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).
vendored_node
+ +(Label): the local path to a pre-installed NodeJS runtime.
+ +If set then also set node_version to the version that of node that is vendored.
+ +Defaults to None
vendored_yarn
+ +(Label): the local path to a pre-installed yarn tool
+ +Defaults to None
yarn_download_auth
+ +(Dictionary: String -> String): auth to use for all url requests
+Example: {“type”: “basic”, “login”: “
Defaults to {}
yarn_repositories
+ +(Dictionary: String -> List of strings): Custom list of yarn repositories 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 NodeJS releases.
+ +Defaults to {}
yarn_urls
+ +(List of strings): custom list of URLs to use to download Yarn
+ +Each entry is a template, similar to the node_urls attribute, using yarn_version and yarn_repositories in the substitutions.
Defaults to ["https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]
yarn_version
+ +(String): the specific version of Yarn to install
+ +Defaults to "1.19.1"
nodejs_binary
+ +USAGE
+ ++nodejs_binary(name, chdir, configuration_env_vars, data, default_env_vars, entry_point, env, + link_workspace_root, templated_args) ++ +
Runs some JavaScript code in NodeJS.
+ +ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this target.
+ +chdir
+ +(String): Working directory to run the binary or test in, relative to the workspace. +By default, Bazel always runs in the workspace root. +Due to implementation details, this argument must be underneath this package directory.
+ +To run in the directory containing the nodejs_binary / nodejs_test, use
chdir = package_name()
+(or if you’re in a macro, use native.package_name())
WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+which are workspace-relative.
+You may need ../../ segments to re-relativize such paths to the new working directory.
Defaults to ""
configuration_env_vars
+ +(List of strings): Pass these configuration environment variables to the resulting binary.
+Chooses a subset of the configuration environment variables (taken from ctx.var), which also
+includes anything specified via the –define flag.
+Note, this can lead to different outputs produced by this rule.
Defaults to []
data
+ +(List of labels): Runtime dependencies which may be loaded during execution.
+ +Defaults to []
default_env_vars
+ +(List of strings): Default environment variables that are added to configuration_env_vars.
This is separate from the default of configuration_env_vars so that a user can set configuration_env_vars
+without losing the defaults that should be set in most cases.
The set of default environment variables is:
+ +-
+
VERBOSE_LOGS: use by some rules & tools to turn on debug output in their logs
+ NODE_DEBUG: used by node.js itself to print more logs
+ RUNFILES_LIB_DEBUG: print diagnostic message from Bazel runfiles.bash helper
+
Defaults to ["VERBOSE_LOGS", "NODE_DEBUG", "RUNFILES_LIB_DEBUG"]
entry_point
+ +(Label, mandatory): The script which should be executed first, usually containing a main function.
+ +If the entry JavaScript file belongs to the same package (as the BUILD file), +you can simply reference it by its relative name to the package directory:
+ +nodejs_binary(
+ name = "my_binary",
+ ...
+ entry_point = ":file.js",
+)
+You can specify the entry point as a typescript file so long as you also include +the ts_library target in data:
+ +ts_library(
+ name = "main",
+ srcs = ["main.ts"],
+)
+
+nodejs_binary(
+ name = "bin",
+ data = [":main"]
+ entry_point = ":main.ts",
+)
+The rule will use the corresponding .js output of the ts_library rule as the entry point.
If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule. +For example:
+ +filegroup(
+ name = "entry_file",
+ srcs = ["main.js"],
+)
+
+nodejs_binary(
+ name = "my_binary",
+ entry_point = ":entry_file",
+)
+The entry_point can also be a label in another workspace:
+ +nodejs_binary(
+ name = "history-server",
+ entry_point = "@npm//:node_modules/history-server/modules/cli.js",
+ data = ["@npm//history-server"],
+)
+env
+ +(Dictionary: String -> String): Specifies additional environment variables to set when the target is executed, subject to location +expansion.
+ +Defaults to {}
link_workspace_root
+ +(Boolean): Link the workspace root to the bin_dir to support absolute requires like ‘my_wksp/path/to/file’. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin.
+ +Defaults to False
templated_args
+ +(List of strings): Arguments which are passed to every execution of the program.
+ To pass a node startup option, prepend it with --node_options=, e.g.
+ --node_options=--preserve-symlinks.
Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.
+ +-
+
- Subject to predefined source/output path variables substitutions. +
The predefined variables execpath, execpaths, rootpath, rootpaths, location, and locations take
+label parameters (e.g. $(execpath //foo:bar)) and substitute the file paths denoted by that label.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables for more info.
+ +NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test
+args and genrule bazel substitions. This will be fixed in a future major release.
+See docs string of expand_location_into_runfiles macro in internal/common/expand_into_runfiles.bzl
+for more info.
The recommended approach is to now use $(rootpath) where you previously used $(location).
To get from a $(rootpath) to the absolute path that $$(rlocation $(location)) returned you can either use
+$$(rlocation $(rootpath)) if you are in the templated_args of a nodejs_binary or nodejs_test:
BUILD.bazel:
+nodejs_test(
+ name = "my_test",
+ data = [":bootstrap.js"],
+ templated_args = ["--node_options=--require=$$(rlocation $(rootpath :bootstrap.js))"],
+)
+or if you’re in the context of a .js script you can pass the $(rootpath) as an argument to the script +and use the javascript runfiles helper to resolve to the absolute path:
+ +BUILD.bazel:
+nodejs_test(
+ name = "my_test",
+ data = [":some_file"],
+ entry_point = ":my_test.js",
+ templated_args = ["$(rootpath :some_file)"],
+)
+my_test.js
+const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
+const args = process.argv.slice(2);
+const some_file = runfiles.resolveWorkspaceRelative(args[0]);
+NB: Bazel will error if it sees the single dollar sign $(rlocation path) in templated_args as it will try to
+expand $(rlocation) since we now expand predefined & custom “make” variables such as $(COMPILATION_MODE),
+$(BINDIR) & $(TARGET_CPU) using ctx.expand_make_variables. See https://docs.bazel.build/versions/master/be/make-variables.html.
To prevent expansion of $(rlocation) write it as $$(rlocation). Bazel understands $$ to be
+the string literal $ and the expansion results in $(rlocation) being passed as an arg instead
+of being expanded. $(rlocation) is then evaluated by the bash node launcher script and it calls
+the rlocation function in the runfiles.bash helper. For example, the templated arg
+$$(rlocation $(rootpath //:some_file)) is expanded by Bazel to $(rlocation ./some_file) which
+is then converted in bash to the absolute path of //:some_file in runfiles by the runfiles.bash helper
+before being passed as an argument to the program.
NB: nodejs_binary and nodejs_test will preserve the legacy behavior of $(rlocation) so users don’t
+need to update to $$(rlocation). This may be changed in the future.
-
+
- Subject to predefined variables & custom variable substitutions. +
Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded. +See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.
+ +Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE. +See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.
+ +Predefined genrule variables are not supported in this context.
+ +Defaults to []
nodejs_test
+ +USAGE
+ ++nodejs_test(name, chdir, configuration_env_vars, data, default_env_vars, entry_point, env, + expected_exit_code, link_workspace_root, templated_args) ++ +
Identical to nodejs_binary, except this can be used with bazel test as well.
+When the binary returns zero exit code, the test passes; otherwise it fails.
nodejs_test is a convenient way to write a novel kind of test based on running
+your own test runner. For example, the ts-api-guardian library has a way to
+assert the public API of a TypeScript program, and uses nodejs_test here:
+https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl
If you just want to run a standard test using a test runner from npm, use the generated
+*_test target created by npm_install/yarn_install, such as mocha_test.
+Some test runners like Karma and Jasmine have custom rules with added features, e.g. jasmine_node_test.
By default, Bazel runs tests with a working directory set to your workspace root.
+Use the chdir attribute to change the working directory before the program starts.
To debug a Node.js test, we recommend saving a group of flags together in a “config”.
+Put this in your tools/bazel.rc so it’s shared with your team:
# Enable debugging tests with --config=debug
+test:debug --test_arg=--node_options=--inspect-brk --test_output=streamed --test_strategy=exclusive --test_timeout=9999 --nocache_test_results
+Now you can add --config=debug to any bazel test command line.
+The runtime will pause before executing the program, allowing you to connect a
+remote debugger.
ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this target.
+ +chdir
+ +(String): Working directory to run the binary or test in, relative to the workspace. +By default, Bazel always runs in the workspace root. +Due to implementation details, this argument must be underneath this package directory.
+ +To run in the directory containing the nodejs_binary / nodejs_test, use
chdir = package_name()
+(or if you’re in a macro, use native.package_name())
WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+which are workspace-relative.
+You may need ../../ segments to re-relativize such paths to the new working directory.
Defaults to ""
configuration_env_vars
+ +(List of strings): Pass these configuration environment variables to the resulting binary.
+Chooses a subset of the configuration environment variables (taken from ctx.var), which also
+includes anything specified via the –define flag.
+Note, this can lead to different outputs produced by this rule.
Defaults to []
data
+ +(List of labels): Runtime dependencies which may be loaded during execution.
+ +Defaults to []
default_env_vars
+ +(List of strings): Default environment variables that are added to configuration_env_vars.
This is separate from the default of configuration_env_vars so that a user can set configuration_env_vars
+without losing the defaults that should be set in most cases.
The set of default environment variables is:
+ +-
+
VERBOSE_LOGS: use by some rules & tools to turn on debug output in their logs
+ NODE_DEBUG: used by node.js itself to print more logs
+ RUNFILES_LIB_DEBUG: print diagnostic message from Bazel runfiles.bash helper
+
Defaults to ["VERBOSE_LOGS", "NODE_DEBUG", "RUNFILES_LIB_DEBUG"]
entry_point
+ +(Label, mandatory): The script which should be executed first, usually containing a main function.
+ +If the entry JavaScript file belongs to the same package (as the BUILD file), +you can simply reference it by its relative name to the package directory:
+ +nodejs_binary(
+ name = "my_binary",
+ ...
+ entry_point = ":file.js",
+)
+You can specify the entry point as a typescript file so long as you also include +the ts_library target in data:
+ +ts_library(
+ name = "main",
+ srcs = ["main.ts"],
+)
+
+nodejs_binary(
+ name = "bin",
+ data = [":main"]
+ entry_point = ":main.ts",
+)
+The rule will use the corresponding .js output of the ts_library rule as the entry point.
If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule. +For example:
+ +filegroup(
+ name = "entry_file",
+ srcs = ["main.js"],
+)
+
+nodejs_binary(
+ name = "my_binary",
+ entry_point = ":entry_file",
+)
+The entry_point can also be a label in another workspace:
+ +nodejs_binary(
+ name = "history-server",
+ entry_point = "@npm//:node_modules/history-server/modules/cli.js",
+ data = ["@npm//history-server"],
+)
+env
+ +(Dictionary: String -> String): Specifies additional environment variables to set when the target is executed, subject to location +expansion.
+ +Defaults to {}
expected_exit_code
+ +(Integer): The expected exit code for the test. Defaults to 0.
+ +Defaults to 0
link_workspace_root
+ +(Boolean): Link the workspace root to the bin_dir to support absolute requires like ‘my_wksp/path/to/file’. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin.
+ +Defaults to False
templated_args
+ +(List of strings): Arguments which are passed to every execution of the program.
+ To pass a node startup option, prepend it with --node_options=, e.g.
+ --node_options=--preserve-symlinks.
Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.
+ +-
+
- Subject to predefined source/output path variables substitutions. +
The predefined variables execpath, execpaths, rootpath, rootpaths, location, and locations take
+label parameters (e.g. $(execpath //foo:bar)) and substitute the file paths denoted by that label.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables for more info.
+ +NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test
+args and genrule bazel substitions. This will be fixed in a future major release.
+See docs string of expand_location_into_runfiles macro in internal/common/expand_into_runfiles.bzl
+for more info.
The recommended approach is to now use $(rootpath) where you previously used $(location).
To get from a $(rootpath) to the absolute path that $$(rlocation $(location)) returned you can either use
+$$(rlocation $(rootpath)) if you are in the templated_args of a nodejs_binary or nodejs_test:
BUILD.bazel:
+nodejs_test(
+ name = "my_test",
+ data = [":bootstrap.js"],
+ templated_args = ["--node_options=--require=$$(rlocation $(rootpath :bootstrap.js))"],
+)
+or if you’re in the context of a .js script you can pass the $(rootpath) as an argument to the script +and use the javascript runfiles helper to resolve to the absolute path:
+ +BUILD.bazel:
+nodejs_test(
+ name = "my_test",
+ data = [":some_file"],
+ entry_point = ":my_test.js",
+ templated_args = ["$(rootpath :some_file)"],
+)
+my_test.js
+const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
+const args = process.argv.slice(2);
+const some_file = runfiles.resolveWorkspaceRelative(args[0]);
+NB: Bazel will error if it sees the single dollar sign $(rlocation path) in templated_args as it will try to
+expand $(rlocation) since we now expand predefined & custom “make” variables such as $(COMPILATION_MODE),
+$(BINDIR) & $(TARGET_CPU) using ctx.expand_make_variables. See https://docs.bazel.build/versions/master/be/make-variables.html.
To prevent expansion of $(rlocation) write it as $$(rlocation). Bazel understands $$ to be
+the string literal $ and the expansion results in $(rlocation) being passed as an arg instead
+of being expanded. $(rlocation) is then evaluated by the bash node launcher script and it calls
+the rlocation function in the runfiles.bash helper. For example, the templated arg
+$$(rlocation $(rootpath //:some_file)) is expanded by Bazel to $(rlocation ./some_file) which
+is then converted in bash to the absolute path of //:some_file in runfiles by the runfiles.bash helper
+before being passed as an argument to the program.
NB: nodejs_binary and nodejs_test will preserve the legacy behavior of $(rlocation) so users don’t
+need to update to $$(rlocation). This may be changed in the future.
-
+
- Subject to predefined variables & custom variable substitutions. +
Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded. +See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.
+ +Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE. +See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.
+ +Predefined genrule variables are not supported in this context.
+ +Defaults to []
npm_install
+ +USAGE
+ ++npm_install(name, args, data, environment, generate_local_modules_build_files, included_files, + links, manual_build_file_contents, npm_command, package_json, package_lock_json, + package_path, patch_args, patch_tool, post_install_patches, pre_install_patches, quiet, + repo_mapping, strict_visibility, symlink_node_modules, timeout) ++ +
Runs npm install during workspace setup.
+ +This rule will set the environment variable BAZEL_NPM_INSTALL to ‘1’ (unless it
+set to another value in the environment attribute). Scripts may use to this to
+check if yarn is being run by the npm_install repository rule.
ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this repository.
+ +args
+ +(List of strings): Arguments passed to npm install.
+ +See npm CLI docs https://docs.npmjs.com/cli/install.html for complete list of supported arguments.
+ +Defaults to []
data
+ +(List of labels): Data files required by this rule.
+ +If symlink_node_modules is True, this attribute is optional since the package manager
+will run in your workspace folder. It is recommended, however, that all files that the
+package manager depends on, such as .rc files or files used in postinstall, are added
+symlink_node_modules is True so that the repository rule is rerun when any of these files
+change.
If symlink_node_modules is False, the package manager is run in the bazel external +repository so all files that the package manager depends on must be listed.
+ +Defaults to []
environment
+ +(Dictionary: String -> String): Environment variables to set before calling the package manager.
+ +Defaults to {}
generate_local_modules_build_files
+ +(Boolean): Enables the BUILD files auto generation for local modules installed with file: (npm) or link: (yarn)
When using a monorepo it’s common to have modules that we want to use locally and
+publish to an external package repository. This can be achieved using a js_library rule
+with a package_name attribute defined inside the local package BUILD file. However,
+if the project relies on the local package dependency with file: (npm) or link: (yarn) to be used outside Bazel, this
+could introduce a race condition with both npm_install or yarn_install rules.
In order to overcome it, a link could be created to the package BUILD file from the
+npm external Bazel repository (so we can use a local BUILD file instead of an auto generated one),
+which require us to set generate_local_modules_build_files = False and complete a last step which is writing the
+expected targets on that same BUILD file to be later used both by npm_install or yarn_install
+rules, which are: <package_name__files>, <package_name__nested_node_modules>,
+<package_name__contents>, <package_name__typings> and the last one just <package_name>. If you doubt what those targets
+should look like, check the generated BUILD file for a given node module.
When true, the rule will follow the default behaviour of auto generating BUILD files for each node_module at install time.
When False, the rule will not auto generate BUILD files for node_modules that are installed as symlinks for local modules.
Defaults to True
included_files
+ +(List of strings): List of file extensions to be included in the npm package targets.
+ +For example, [“.js”, “.d.ts”, “.proto”, “.json”, “”].
+ +This option is useful to limit the number of files that are inputs +to actions that depend on npm package targets. See +https://github.com/bazelbuild/bazel/issues/5153.
+ +If set to an empty list then all files are included in the package targets.
+If set to a list of extensions, only files with matching extensions are
+included in the package targets. An empty string in the list is a special
+string that denotes that files with no extensions such as README should
+be included in the package targets.
This attribute applies to both the coarse @wksp//:node_modules target
+as well as the fine grained targets such as @wksp//foo.
Defaults to []
links
+ +(Dictionary: String -> String): Targets to link as npm packages.
+ +A mapping of npm package names to bazel targets to linked into node_modules.
+ +If package_path is also set, the bazel target will be linked to the node_modules at package_path
+along with other 3rd party npm packages from this rule.
For example,
+ +yarn_install(
+ name = "npm",
+ package_json = "//web:package.json",
+ yarn_lock = "//web:yarn.lock",
+ package_path = "web",
+ links = {
+ "@scope/target": "//some/scoped/target",
+ "target": "//some/target",
+ },
+)
+creates targets in the @npm external workspace that can be used by other rules which
+are linked into web/node_modules along side the 3rd party deps since the project_path is web.
The above links will create the targets,
+ +@npm//@scope/target
+@npm//target
+that can be referenced as data or deps by other rules such as nodejs_binary and ts_project
+and can be required as @scope/target and target with standard node_modules resolution at runtime,
nodejs_binary(
+ name = "bin",
+ entry_point = "bin.js",
+ deps = [
+ "@npm//@scope/target",
+ "@npm//target"
+ "@npm//other/dep"
+ ],
+)
+
+ts_project(
+ name = "test",
+ srcs = [...],
+ deps = [
+ "@npm//@scope/target",
+ "@npm//target"
+ "@npm//other/dep"
+ ],
+)
+Defaults to {}
manual_build_file_contents
+ +(String): Experimental attribute that can be used to override the generated BUILD.bazel file and set its contents manually.
+ +Can be used to work-around a bazel performance issue if the
+default @wksp//:node_modules target has too many files in it.
+See https://github.com/bazelbuild/bazel/issues/5153. If
+you are running into performance issues due to a large
+node_modules target it is recommended to switch to using
+fine grained npm dependencies.
Defaults to ""
npm_command
+ +(String): The npm command to run, to install dependencies.
+ + See npm docs <https://docs.npmjs.com/cli/v6/commands>
+
+ In particular, for "ci" it says:
+ > If dependencies in the package lock do not match those in package.json, npm ci will exit with an error, instead of updating the package lock.
+Defaults to "ci"
package_json
+ +(Label, mandatory)
+ +package_lock_json
+ +(Label, mandatory)
+ +package_path
+ +(String): If set, link the 3rd party node_modules dependencies under the package path specified.
+ +In most cases, this should be the directory of the package.json file so that the linker links the node_modules +in the same location they are found in the source tree. In a future release, this will default to the package.json +directory. This is planned for 4.0: https://github.com/bazelbuild/rules_nodejs/issues/2451
+ +Defaults to ""
patch_args
+ +(List of strings): The arguments given to the patch tool. Defaults to -p0, however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, patch will be used.
Defaults to ["-p0"]
patch_tool
+ +(String): The patch(1) utility to use. If this is specified, Bazel will use the specifed patch tool instead of the Bazel-native patch implementation.
+ +Defaults to ""
post_install_patches
+ +(List of labels): Patch files to apply after running package manager.
+ +This can be used to make changes to installed packages after the package manager runs.
+ +File paths in patches should be relative to workspace root.
+ +Defaults to []
pre_install_patches
+ +(List of labels): Patch files to apply before running package manager.
+ +This can be used to make changes to package.json or other data files passed in before running the +package manager.
+ +File paths in patches should be relative to workspace root.
+ +Defaults to []
quiet
+ +(Boolean): If stdout and stderr should be printed to the terminal.
+ +Defaults to True
repo_mapping
+ +(Dictionary: String -> String, mandatory): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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).
strict_visibility
+ +(Boolean): Turn on stricter visibility for generated BUILD.bazel files
+ +When enabled, only dependencies within the given package.json file are given public visibility.
+All transitive dependencies are given limited visibility, enforcing that all direct dependencies are
+listed in the package.json file.
Defaults to True
symlink_node_modules
+ +(Boolean): Turn symlinking of node_modules on
+ +This requires the use of Bazel 0.26.0 and the experimental +managed_directories feature.
+ +When true, the package manager will run in the package.json folder +and the resulting node_modules folder will be symlinked into the +external repository create by this rule.
+ +When false, the package manager will run in the external repository +created by this rule and any files other than the package.json file and +the lock file that are required for it to run should be listed in the +data attribute.
+ +Defaults to True
timeout
+ +(Integer): Maximum duration of the package manager execution in seconds.
+ +Defaults to 3600
pkg_npm
+ +USAGE
+ ++pkg_npm(name, deps, nested_packages, node_context_data, package_name, package_path, srcs, + substitutions, tgz, vendor_external) ++ +
The pkg_npm rule creates a directory containing a publishable npm artifact.
+ +Example:
+ +load("@build_bazel_rules_nodejs//:index.bzl", "pkg_npm")
+
+pkg_npm(
+ name = "my_package",
+ srcs = ["package.json"],
+ deps = [":my_typescript_lib"],
+ substitutions = {"//internal/": "//"},
+)
+You can use a pair of // BEGIN-INTERNAL ... // END-INTERNAL comments to mark regions of files that should be elided during publishing.
+For example:
function doThing() {
+ // BEGIN-INTERNAL
+ // This is a secret internal-only comment
+ doInternalOnlyThing();
+ // END-INTERNAL
+}
+With the Bazel stamping feature, pkg_npm will replace any placeholder version in your package with the actual version control tag. +See the stamping documentation
+ +Usage:
+ +pkg_npm yields four labels. Build the package directory using the default label:
$ bazel build :my_package
+Target //:my_package up-to-date:
+ bazel-out/fastbuild/bin/my_package
+$ ls -R bazel-out/fastbuild/bin/my_package
+Dry-run of publishing to npm, calling npm pack (it builds the package first if needed):
$ bazel run :my_package.pack
+INFO: Running command line: bazel-out/fastbuild/bin/my_package.pack
+my-package-name-1.2.3.tgz
+$ tar -tzf my-package-name-1.2.3.tgz
+Actually publish the package with npm publish (also builds first):
# Check login credentials
+$ bazel run @nodejs//:npm_node_repositories who
+# Publishes the package
+$ bazel run :my_package.publish
+You can pass arguments to npm by escaping them from Bazel using a double-hyphen, for example:
+ +bazel run my_package.publish -- --tag=next
It is also possible to use the resulting tar file file from the .pack as an action input via the .tar label.
+To make use of this label, the tgz attribute must be set, and the generating pkg_npm rule must have a valid package.json file
+as part of its sources:
pkg_npm(
+ name = "my_package",
+ srcs = ["package.json"],
+ deps = [":my_typescript_lib"],
+ tgz = "my_package.tgz",
+)
+
+my_rule(
+ name = "foo",
+ srcs = [
+ "//:my_package.tar",
+ ],
+)
+ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this target.
+ +deps
+ +(List of labels): Other targets which produce files that should be included in the package, such as rollup_bundle
Defaults to []
nested_packages
+ +(List of labels): Other pkg_npm rules whose content is copied into this package.
+ +Defaults to []
node_context_data
+ +(Label): Provides info about the build context, such as stamping.
+ +By default it reads from the bazel command line, such as the --stamp argument.
+Use this to override values for this target, such as enabling or disabling stamping.
+You can use the node_context_data rule in @build_bazel_rules_nodejs//internal/node:context.bzl
+to create a NodeContextInfo. The dependencies of this attribute must provide: NodeContextInfo
Defaults to @build_bazel_rules_nodejs//internal:node_context_data
package_name
+ +(String): Optional package_name that this npm package may be imported as.
+ +Defaults to ""
package_path
+ +(String): The directory in the workspace to link to. +If set, link this pkg_npm to the node_modules under the package path specified. +If unset, the default is to link to the node_modules root of the workspace.
+ +Defaults to ""
srcs
+ +(List of labels): Files inside this directory which are simply copied into the package.
+ +Defaults to []
substitutions
+ +(Dictionary: String -> String): Key-value pairs which are replaced in all the files while building the package.
+ +You can use values from the workspace status command using curly braces, for example
+{"0.0.0-PLACEHOLDER": "{STABLE_GIT_VERSION}"}.
See the section on stamping in the README
+ +Defaults to {}
tgz
+ +(String): If set, will create a .tgz file that can be used as an input to another rule, the tar will be given the name assigned to this attribute.
NOTE: If this attribute is set, a valid `package.json` file must be included in the sources of this target
+Defaults to ""
vendor_external
+ +(List of strings): External workspaces whose contents should be vendored into this workspace.
+ Avoids external/foo path segments in the resulting package.
Defaults to []
pkg_web
+ +USAGE
+ ++pkg_web(name, additional_root_paths, node_context_data, srcs, substitutions) ++ +
Assembles a web application from source files.
+ +ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this target.
+ +additional_root_paths
+ +(List of strings): Path prefixes to strip off all srcs, in addition to the current package. Longest wins.
+ +Defaults to []
node_context_data
+ +(Label): Provides info about the build context, such as stamping.
+ +By default it reads from the bazel command line, such as the --stamp argument.
+Use this to override values for this target, such as enabling or disabling stamping.
+You can use the node_context_data rule in @build_bazel_rules_nodejs//internal/node:context.bzl
+to create a NodeContextInfo. The dependencies of this attribute must provide: NodeContextInfo
Defaults to @build_bazel_rules_nodejs//internal:node_context_data
srcs
+ +(List of labels): Files which should be copied into the package
+ +Defaults to []
substitutions
+ +(Dictionary: String -> String): Key-value pairs which are replaced in all the files while building the package.
+ +You can use values from the workspace status command using curly braces, for example
+{"0.0.0-PLACEHOLDER": "{STABLE_GIT_VERSION}"}.
+See the section on stamping in the README.
Defaults to {}
yarn_install
+ +USAGE
+ ++yarn_install(name, args, data, environment, frozen_lockfile, generate_local_modules_build_files, + included_files, links, manual_build_file_contents, package_json, package_path, + patch_args, patch_tool, post_install_patches, pre_install_patches, quiet, repo_mapping, + strict_visibility, symlink_node_modules, timeout, use_global_yarn_cache, yarn_lock) ++ +
Runs yarn install during workspace setup.
+ +This rule will set the environment variable BAZEL_YARN_INSTALL to ‘1’ (unless it
+set to another value in the environment attribute). Scripts may use to this to
+check if yarn is being run by the yarn_install repository rule.
ATTRIBUTES
+ +name
+ +(Name, mandatory): A unique name for this repository.
+ +args
+ +(List of strings): Arguments passed to yarn install.
+ +See yarn CLI docs https://yarnpkg.com/en/docs/cli/install for complete list of supported arguments.
+ +Defaults to []
data
+ +(List of labels): Data files required by this rule.
+ +If symlink_node_modules is True, this attribute is optional since the package manager
+will run in your workspace folder. It is recommended, however, that all files that the
+package manager depends on, such as .rc files or files used in postinstall, are added
+symlink_node_modules is True so that the repository rule is rerun when any of these files
+change.
If symlink_node_modules is False, the package manager is run in the bazel external +repository so all files that the package manager depends on must be listed.
+ +Defaults to []
environment
+ +(Dictionary: String -> String): Environment variables to set before calling the package manager.
+ +Defaults to {}
frozen_lockfile
+ +(Boolean): Use the --frozen-lockfile flag for yarn.
Don’t generate a yarn.lock lockfile and fail if an update is needed.
This flag enables an exact install of the version that is specified in the yarn.lock
+file. This helps to have reproducible builds across builds.
To update a dependency or install a new one run the yarn install command with the
+vendored yarn binary. bazel run @nodejs//:yarn install. You can pass the options like
+bazel run @nodejs//:yarn install -- -D <dep-name>.
Defaults to True
generate_local_modules_build_files
+ +(Boolean): Enables the BUILD files auto generation for local modules installed with file: (npm) or link: (yarn)
When using a monorepo it’s common to have modules that we want to use locally and
+publish to an external package repository. This can be achieved using a js_library rule
+with a package_name attribute defined inside the local package BUILD file. However,
+if the project relies on the local package dependency with file: (npm) or link: (yarn) to be used outside Bazel, this
+could introduce a race condition with both npm_install or yarn_install rules.
In order to overcome it, a link could be created to the package BUILD file from the
+npm external Bazel repository (so we can use a local BUILD file instead of an auto generated one),
+which require us to set generate_local_modules_build_files = False and complete a last step which is writing the
+expected targets on that same BUILD file to be later used both by npm_install or yarn_install
+rules, which are: <package_name__files>, <package_name__nested_node_modules>,
+<package_name__contents>, <package_name__typings> and the last one just <package_name>. If you doubt what those targets
+should look like, check the generated BUILD file for a given node module.
When true, the rule will follow the default behaviour of auto generating BUILD files for each node_module at install time.
When False, the rule will not auto generate BUILD files for node_modules that are installed as symlinks for local modules.
Defaults to True
included_files
+ +(List of strings): List of file extensions to be included in the npm package targets.
+ +For example, [“.js”, “.d.ts”, “.proto”, “.json”, “”].
+ +This option is useful to limit the number of files that are inputs +to actions that depend on npm package targets. See +https://github.com/bazelbuild/bazel/issues/5153.
+ +If set to an empty list then all files are included in the package targets.
+If set to a list of extensions, only files with matching extensions are
+included in the package targets. An empty string in the list is a special
+string that denotes that files with no extensions such as README should
+be included in the package targets.
This attribute applies to both the coarse @wksp//:node_modules target
+as well as the fine grained targets such as @wksp//foo.
Defaults to []
links
+ +(Dictionary: String -> String): Targets to link as npm packages.
+ +A mapping of npm package names to bazel targets to linked into node_modules.
+ +If package_path is also set, the bazel target will be linked to the node_modules at package_path
+along with other 3rd party npm packages from this rule.
For example,
+ +yarn_install(
+ name = "npm",
+ package_json = "//web:package.json",
+ yarn_lock = "//web:yarn.lock",
+ package_path = "web",
+ links = {
+ "@scope/target": "//some/scoped/target",
+ "target": "//some/target",
+ },
+)
+creates targets in the @npm external workspace that can be used by other rules which
+are linked into web/node_modules along side the 3rd party deps since the project_path is web.
The above links will create the targets,
+ +@npm//@scope/target
+@npm//target
+that can be referenced as data or deps by other rules such as nodejs_binary and ts_project
+and can be required as @scope/target and target with standard node_modules resolution at runtime,
nodejs_binary(
+ name = "bin",
+ entry_point = "bin.js",
+ deps = [
+ "@npm//@scope/target",
+ "@npm//target"
+ "@npm//other/dep"
+ ],
+)
+
+ts_project(
+ name = "test",
+ srcs = [...],
+ deps = [
+ "@npm//@scope/target",
+ "@npm//target"
+ "@npm//other/dep"
+ ],
+)
+Defaults to {}
manual_build_file_contents
+ +(String): Experimental attribute that can be used to override the generated BUILD.bazel file and set its contents manually.
+ +Can be used to work-around a bazel performance issue if the
+default @wksp//:node_modules target has too many files in it.
+See https://github.com/bazelbuild/bazel/issues/5153. If
+you are running into performance issues due to a large
+node_modules target it is recommended to switch to using
+fine grained npm dependencies.
Defaults to ""
package_json
+ +(Label, mandatory)
+ +package_path
+ +(String): If set, link the 3rd party node_modules dependencies under the package path specified.
+ +In most cases, this should be the directory of the package.json file so that the linker links the node_modules +in the same location they are found in the source tree. In a future release, this will default to the package.json +directory. This is planned for 4.0: https://github.com/bazelbuild/rules_nodejs/issues/2451
+ +Defaults to ""
patch_args
+ +(List of strings): The arguments given to the patch tool. Defaults to -p0, however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, patch will be used.
Defaults to ["-p0"]
patch_tool
+ +(String): The patch(1) utility to use. If this is specified, Bazel will use the specifed patch tool instead of the Bazel-native patch implementation.
+ +Defaults to ""
post_install_patches
+ +(List of labels): Patch files to apply after running package manager.
+ +This can be used to make changes to installed packages after the package manager runs.
+ +File paths in patches should be relative to workspace root.
+ +Defaults to []
pre_install_patches
+ +(List of labels): Patch files to apply before running package manager.
+ +This can be used to make changes to package.json or other data files passed in before running the +package manager.
+ +File paths in patches should be relative to workspace root.
+ +Defaults to []
quiet
+ +(Boolean): If stdout and stderr should be printed to the terminal.
+ +Defaults to True
repo_mapping
+ +(Dictionary: String -> String, mandatory): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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).
strict_visibility
+ +(Boolean): Turn on stricter visibility for generated BUILD.bazel files
+ +When enabled, only dependencies within the given package.json file are given public visibility.
+All transitive dependencies are given limited visibility, enforcing that all direct dependencies are
+listed in the package.json file.
Defaults to True
symlink_node_modules
+ +(Boolean): Turn symlinking of node_modules on
+ +This requires the use of Bazel 0.26.0 and the experimental +managed_directories feature.
+ +When true, the package manager will run in the package.json folder +and the resulting node_modules folder will be symlinked into the +external repository create by this rule.
+ +When false, the package manager will run in the external repository +created by this rule and any files other than the package.json file and +the lock file that are required for it to run should be listed in the +data attribute.
+ +Defaults to True
timeout
+ +(Integer): Maximum duration of the package manager execution in seconds.
+ +Defaults to 3600
use_global_yarn_cache
+ +(Boolean): Use the global yarn cache on the system.
+ +The cache lets you avoid downloading packages multiple times. +However, it can introduce non-hermeticity, and the yarn cache can +have bugs.
+ +Disabling this attribute causes every run of yarn to have a unique +cache_directory.
+ +If True, this rule will pass --mutex network to yarn to ensure that
+the global cache can be shared by parallelized yarn_install rules.
If False, this rule will pass --cache-folder /path/to/external/repository/__yarn_cache
+to yarn so that the local cache is contained within the external repository.
Defaults to True
yarn_lock
+ +(Label, mandatory)
+ +check_bazel_version
+ +USAGE
+ ++check_bazel_version(minimum_bazel_version, message) ++ +
Verify the users Bazel version is at least the given one.
+This can be used in rule implementations that depend on changes in Bazel, +to warn users about a mismatch between the rule and their installed Bazel +version.
+ +This should not be used in users WORKSPACE files. To locally pin your +Bazel version, just create the .bazelversion file in your workspace.
+ +PARAMETERS
+ +minimum_bazel_version
+ +a string indicating the minimum version
+ +message
+ +optional string to print to your users, could be used to help them update
+ +Defaults to ""
copy_to_bin
+ +USAGE
+ ++copy_to_bin(name, srcs, kwargs) ++ +
Copies a source file to bazel-bin at the same workspace-relative path.
+ +e.g. <workspace_root>/foo/bar/a.txt -> <bazel-bin>/foo/bar/a.txt
This is useful to populate the output folder with all files needed at runtime, even +those which aren’t outputs of a Bazel rule.
+ +This way you can run a binary in the output folder (execroot or runfiles_root) +without that program needing to rely on a runfiles helper library or be aware that +files are divided between the source tree and the output tree.
+ +PARAMETERS
+ +name
+ +Name of the rule.
+ +srcs
+ +A List of Labels. File(s) to to copy.
+ +kwargs
+ +further keyword arguments, e.g. visibility
generated_file_test
+ +USAGE
+ ++generated_file_test(name, generated, src, substring_search, src_dbg, kwargs) ++ +
Tests that a file generated by Bazel has identical content to a file in the workspace.
+ +This is useful for testing, where a “snapshot” or “golden” file is checked in, +so that you can code review changes to the generated output.
+ +PARAMETERS
+ +name
+ +Name of the rule.
+ +generated
+ +a Label of the output file generated by another rule
+ +src
+ +Label of the source file in the workspace
+ +substring_search
+ +When true, creates a test that will fail only if the golden file is not found +anywhere within the generated file. Note that the .update rule is not generated in substring mode.
+ +Defaults to False
src_dbg
+ +if the build uses --compilation_mode dbg then some rules will produce different output.
+In this case you can specify what the dbg version of the output should look like
Defaults to None
kwargs
+ +extra arguments passed to the underlying nodejs_test
+ +js_library
+ +USAGE
+ ++js_library(name, srcs, package_name, package_path, deps, kwargs) ++ +
Groups JavaScript code so that it can be depended on like an npm package.
+ +js_library is intended to be used internally within Bazel, such as between two libraries in your monorepo.
+This rule doesn’t perform any build steps (“actions”) so it is similar to a filegroup.
+However it provides several Bazel “Providers” for interop with other rules.
++ +Compare this to
+pkg_npmwhich just produces a directory output, and therefore can’t expose individual +files to downstream targets and causes a cascading re-build of all transitive dependencies when any file +changes. Alsopkg_npmis intended to publish your code for external usage outside of Bazel, like +by publishing to npm or artifactory, whilejs_libraryis for internal dependencies within your repo.
js_library also copies any source files into the bazel-out folder.
+This is the same behavior as the copy_to_bin rule.
+By copying the complete package to the output tree, we ensure that the linker (our npm link equivalent)
+will make your source files available in the node_modules tree where resolvers expect them.
+It also means you can have relative imports between the files
+rather than being forced to use Bazel’s “Runfiles” semantics where any program might need a helper library
+to resolve files between the logical union of the source tree and the output tree.
Example
+ +A typical example usage of js_library is to expose some sources with a package name:
ts_project(
+ name = "compile_ts",
+ srcs = glob(["*.ts"]),
+)
+
+js_library(
+ name = "my_pkg",
+ # Code that depends on this target can import from "@myco/mypkg"
+ package_name = "@myco/mypkg",
+ # Consumers might need fields like "main" or "typings"
+ srcs = ["package.json"],
+ # The .js and .d.ts outputs from above will be part of the package
+ deps = [":compile_ts"],
+)
+++ +To help work with “named AMD” modules as required by
+concatjs_devserverand other Google-style “concatjs” rules, +js_libraryhas some undocumented advanced features you can find in the source code or in our examples. +These should not be considered a public API and aren’t subject to our usual support and semver guarantees.
Outputs
+ +Like all Bazel rules it produces a default output by providing DefaultInfo.
+You’ll get these outputs if you include this in the srcs of a typical rule like filegroup,
+and these will be the printed result when you bazel build //some:js_library_target.
+The default outputs are all of:
-
+
- DefaultInfo produced by targets in
deps
+ - A copy of all sources (InputArtifacts from your source tree) in the bazel-out directory +
When there are TypeScript typings files, js_library provides DeclarationInfo
+so this target can be a dependency of a TypeScript rule. This includes any .d.ts files in srcs as well
+as transitive ones from deps.
+It will also provide OutputGroupInfo with a “types” field, so you can select the typings outputs with
+bazel build //some:js_library_target --output_groups=types or with a filegroup rule using the
+output_group attribute.
In order to work with the linker (similar to npm link for first-party monorepo deps), js_library provides
+LinkablePackageInfo for use with our “linker” that makes this package importable.
It also provides:
+-
+
- ExternalNpmPackageInfo to interop with rules that expect third-party npm packages. +
- JSModuleInfo so rules like bundlers can collect the transitive set of .js files +
- JSNamedModuleInfo for rules that expect named AMD or
goog.moduleformat JS
+
PARAMETERS
+ +name
+ +The name for the target
+ +srcs
+ +The list of files that comprise the package
+ +Defaults to []
package_name
+ +The name it will be imported by. Should match the “name” field in the package.json file.
+ +If package_name == “$node_modules$” this indictates that this js_library target is one or more external npm
+packages in node_modules. This is a special case that used be covered by the internal only
+external_npm_package attribute. NB: ‘$’ is an illegal character
+for npm packages names so this reserved name will not conflict with any valid package_name values
This is used by the yarn_install & npm_install repository rules for npm dependencies installed by +yarn & npm. When true, js_library will provide ExternalNpmPackageInfo.
+ +It can also be used for user-managed npm dependencies if node_modules is layed out outside of bazel. +For example,
+ +js_library( + name = “node_modules”, + srcs = glob( + include = [ + “node_modules//.js”, + “node_modules/**/.d.ts”, + “node_modules//.json”, + “node_modules/.bin/”, + ], + exclude = [ + # Files under test & docs may contain file names that + # are not legal Bazel labels (e.g., + # node_modules/ecstatic/test/public/ä¸æ/æªæ¡.html) + “node_modules//test/”, + “node_modules//docs/”, + # Files with spaces in the name are not legal Bazel labels + “node_modules/*/ /”, + “node_modules// *”, + ], + ), + # Special value to provide ExternalNpmPackageInfo which is used by downstream + # rules that use these npm dependencies + package_name = “$node_modules$”, +)
+ +See examples/user_managed_deps for a working example of user-managed npm dependencies.
Defaults to None
package_path
+ +The directory in the workspace to link to. +If set, link this js_library to the node_modules under the package path specified. +If unset, the default is to link to the node_modules root of the workspace.
+ +Defaults to ""
deps
+ +Other targets that provide JavaScript code
+ +Defaults to []
kwargs
+ +Other attributes
+ +npm_package_bin
+ +USAGE
+ ++npm_package_bin(tool, package, package_bin, data, env, outs, args, stderr, stdout, exit_code_out, + output_dir, link_workspace_root, chdir, kwargs) ++ +
Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel.
+ +It must produce outputs. If you just want to run a program with bazel run, use the nodejs_binary rule.
This is like a genrule() except that it runs our launcher script that first +links the node_modules tree before running the program.
+ +By default, Bazel runs actions with a working directory set to your workspace root.
+Use the chdir attribute to change the working directory before the program runs.
This is a great candidate to wrap with a macro, as documented: +https://docs.bazel.build/versions/master/skylark/macros.html#full-example
+ +PARAMETERS
+ +tool
+ +a label for a binary to run, like @npm//terser/bin:terser. This is the longer form of package/package_bin.
+Note that you can also refer to a binary in your local workspace.
Defaults to None
package
+ +an npm package whose binary to run, like “terser”. Assumes your node_modules are installed in a workspace called “npm”
+ +Defaults to None
package_bin
+ +the “bin” entry from package that should be run. By default package_bin is the same string as package
Defaults to None
data
+ +similar to genrule.srcs +may also include targets that produce or reference npm packages which are needed by the tool
+ +Defaults to []
env
+ +specifies additional environment variables to set when the target is executed
+ +Defaults to {}
outs
+ +similar to genrule.outs
+ +Defaults to []
args
+ +Command-line arguments to the tool.
+ +Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.
+ +-
+
- Predefined source/output path substitions is applied first: +
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables.
+ +Use $(execpath) $(execpaths) to expand labels to the execroot (where Bazel runs build actions).
+ +Use $(rootpath) $(rootpaths) to expand labels to the runfiles path that a built binary can use +to find its dependencies.
+ +Since npm_package_bin is used primarily for build actions, in most cases you’ll want to +use $(execpath) or $(execpaths) to expand locations.
+ +Using $(location) and $(locations) expansions is not recommended as these are a synonyms +for either $(execpath) or $(rootpath) depending on the context.
+ +-
+
- “Make” variables are expanded second: +
Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded. +See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.
+ +Like genrule, you may also use some syntax sugar for locations.
+ +-
+
$@: if you have only one output file, the location of the output
+ $(@D): The output directory. If output_dir=False and there is only one file name in outs, this expands to the directory + containing that file. If there are multiple files, this instead expands to the package’s root directory in the genfiles + tree, even if all generated files belong to the same subdirectory! If output_dir=True then this corresponds + to the output directory which is the $(RULEDIR)/{target_name}.
+ $(RULEDIR): the root output directory of the rule, corresponding with its package + (can be used with output_dir=True or False)
+
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_genrule_variables.
+ +Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE. +See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.
+ +Defaults to []
stderr
+ +set to capture the stderr of the binary to a file, which can later be used as an input to another target
+subject to the same semantics as outs
Defaults to None
stdout
+ +set to capture the stdout of the binary to a file, which can later be used as an input to another target
+subject to the same semantics as outs
Defaults to None
exit_code_out
+ +set to capture the exit code of the binary to a file, which can later be used as an input to another target
+subject to the same semantics as outs. Note that setting this will force the binary to exit 0.
+If the binary creates outputs and these are declared, they must still be created
Defaults to None
output_dir
+ +set to True if you want the output to be a directory
+Exactly one of outs, output_dir may be used.
+If you output a directory, there can only be one output, which will be a directory named the same as the target.
Defaults to False
link_workspace_root
+ +Link the workspace root to the bin_dir to support absolute requires like ‘my_wksp/path/to/file’. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin.
+ +Defaults to False
chdir
+ +Working directory to run the binary or test in, relative to the workspace.
+ +By default, Bazel always runs in the workspace root.
+ +To run in the directory containing the npm_package_bin under the source tree, use
+chdir = package_name()
+(or if you’re in a macro, use native.package_name()).
To run in the output directory where the npm_package_bin writes outputs, use
+chdir = "$(RULEDIR)"
WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+which are workspace-relative.
+You may need ../../ segments to re-relativize such paths to the new working directory.
+In a BUILD file you could do something like this to point to the output path:
_package_segments = len(package_name().split("/"))
+npm_package_bin(
+ ...
+ chdir = package_name(),
+ # ../.. segments to re-relative paths from the chdir back to workspace
+ args = ["/".join([".."] * _package_segments + ["$@"])],
+)
+Defaults to None
kwargs
+ +additional undocumented keyword args
+ +params_file
+ +USAGE
+ ++params_file(name, out, args, data, newline, kwargs) ++ +
Generates a UTF-8 encoded params file from a list of arguments.
+ +Handles variable substitutions for args.
+ +PARAMETERS
+ +name
+ +Name of the rule.
+ +out
+ +Path of the output file, relative to this package.
+ +args
+ +Arguments to concatenate into a params file.
+ +Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.
+ +-
+
- Subject to predefined source/output path variables substitutions. +
The predefined variables execpath, execpaths, rootpath, rootpaths, location, and locations take
+label parameters (e.g. $(execpath //foo:bar)) and substitute the file paths denoted by that label.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables for more info.
+ +NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test
+args and genrule bazel substitions. This will be fixed in a future major release.
+See docs string of expand_location_into_runfiles macro in internal/common/expand_into_runfiles.bzl
+for more info.
-
+
- Subject to predefined variables & custom variable substitutions. +
Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded. +See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.
+ +Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE. +See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.
+ +Predefined genrule variables are not supported in this context.
+ +Defaults to []
data
+ +Data for $(location) expansions in args.
+ +Defaults to []
newline
+ +Line endings to use. One of [“auto”, “unix”, “windows”].
+ +“auto” for platform-determined +“unix” for LF +“windows” for CRLF
+ +Defaults to "auto"
kwargs
+ +DeclarationInfo
+ +USAGE
+ ++DeclarationInfo(declarations, transitive_declarations, type_blacklisted_declarations) ++ +
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.
+ +FIELDS
+ +declarations
+ +A depset of typings files produced by this rule
+transitive_declarations
+ +A depset of typings files produced by this rule and all its transitive dependencies. +This prevents needing an aspect in rules that consume the typings, which improves performance.
+type_blacklisted_declarations
+ +A depset of .d.ts files that we should not use to infer JSCompiler types (via tsickle)
+ +ExternalNpmPackageInfo
+ +USAGE
+ ++ExternalNpmPackageInfo(direct_sources, path, sources, workspace) ++ +
Provides information about one or more external npm packages
+ +FIELDS
+ +direct_sources
+ +Depset of direct source files in these external npm package(s)
+path
+ +The local workspace path that these external npm deps should be linked at. If empty, they will be linked at the root.
+sources
+ +Depset of direct & transitive source files in these external npm package(s) and transitive dependencies
+workspace
+ +The workspace name that these external npm package(s) are provided from
+ +JSEcmaScriptModuleInfo
+ +USAGE
+ ++JSEcmaScriptModuleInfo(direct_sources, sources) ++ +
JavaScript files (and sourcemaps) that are intended to be consumed by downstream tooling.
+ +They should use modern syntax and ESModules. +These files should typically be named “foo.mjs”
+ +Historical note: this was the typescript.es6_sources output
+ +FIELDS
+ +direct_sources
+ +Depset of direct JavaScript files and sourcemaps
+sources
+ +Depset of direct and transitive JavaScript files and sourcemaps
+ +JSModuleInfo
+ +USAGE
+ ++JSModuleInfo(direct_sources, sources) ++ +
JavaScript files and sourcemaps.
+ +FIELDS
+ +direct_sources
+ +Depset of direct JavaScript files and sourcemaps
+sources
+ +Depset of direct and transitive JavaScript files and sourcemaps
+ +JSNamedModuleInfo
+ +USAGE
+ ++JSNamedModuleInfo(direct_sources, sources) ++ +
JavaScript files whose module name is self-contained.
+ +For example named AMD/UMD or goog.module format. +These files can be efficiently served with the concatjs bundler. +These outputs should be named “foo.umd.js” +(note that renaming it from “foo.js” doesn’t affect the module id)
+ +Historical note: this was the typescript.es5_sources output.
+ +FIELDS
+ +direct_sources
+ +Depset of direct JavaScript files and sourcemaps
+sources
+ +Depset of direct and transitive JavaScript files and sourcemaps
+ +LinkablePackageInfo
+ +USAGE
+ ++LinkablePackageInfo(files, package_name, package_path, path, _tslibrary) ++ +
The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages
+ +FIELDS
+ +files
+ +Depset of files in this package (must all be contained within path)
+package_name
+ +The package name.
+ +This field is optional. If not set, the target can be made linkable to a package_name with the npm_link rule.
+package_path
+ +The directory in the workspace to link to.
+ +If set, link the 1st party dependencies to the node_modules under the package path specified. +If unset, the default is to link to the node_modules root of the workspace.
+path
+ +The path to link to.
+ +Path must be relative to execroot/wksp. It can either an output dir path such as,
+ +bazel-out/<platform>-<build>/bin/path/to/package or
+bazel-out/<platform>-<build>/bin/external/external_wksp>/path/to/package
or a source file path such as,
+ +path/to/package or
+external/<external_wksp>/path/to/package
_tslibrary
+ +For internal use only
+ +NodeContextInfo
+ +USAGE
+ ++NodeContextInfo(stamp) ++ +
Provides data about the build context, like config_setting’s
+ +FIELDS
+ +stamp
+ +If stamping is enabled
+ +NodeRuntimeDepsInfo
+ +USAGE
+ ++NodeRuntimeDepsInfo(deps, pkgs) ++ +
Stores runtime dependencies of a nodejs_binary or nodejs_test
+ +These are files that need to be found by the node module resolver at runtime.
+ +Historically these files were passed using the Runfiles mechanism. +However runfiles has a big performance penalty of creating a symlink forest +with FS API calls for every file in node_modules. +It also causes there to be separate node_modules trees under each binary. This +prevents user-contributed modules passed as deps[] to a particular action from +being found by node module resolver, which expects everything in one tree.
+ +In node, this resolution is done dynamically by assuming a node_modules +tree will exist on disk, so we assume node actions/binary/test executions will +do the same.
+ +FIELDS
+ +deps
+ +depset of runtime dependency labels
+pkgs
+ +list of labels of packages that provide ExternalNpmPackageInfo
+ +NpmPackageInfo
+ +USAGE
+ ++NpmPackageInfo(direct_sources, path, sources, workspace) ++ +
Provides information about one or more external npm packages
+ +FIELDS
+ +direct_sources
+ +Depset of direct source files in these external npm package(s)
+path
+ +The local workspace path that these external npm deps should be linked at. If empty, they will be linked at the root.
+sources
+ +Depset of direct & transitive source files in these external npm package(s) and transitive dependencies
+workspace
+ +The workspace name that these external npm package(s) are provided from
+ +declaration_info
+ +USAGE
+ ++declaration_info(declarations, deps) ++ +
Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps.
+ +PARAMETERS
+ +declarations
+ +list of typings files
+ +deps
+ +list of labels of dependencies where we should collect their DeclarationInfo to pass transitively
+ +Defaults to []
js_ecma_script_module_info
+ +USAGE
+ ++js_ecma_script_module_info(sources, deps) ++ +
Constructs a JSEcmaScriptModuleInfo including all transitive sources from JSEcmaScriptModuleInfo providers in a list of deps.
+ +Returns a single JSEcmaScriptModuleInfo.
+ +PARAMETERS
+ +sources
+ +deps
+ +Defaults to []
js_module_info
+ +USAGE
+ ++js_module_info(sources, deps) ++ +
Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps.
+ +Returns a single JSModuleInfo.
+ +PARAMETERS
+ +sources
+ +deps
+ +Defaults to []
js_named_module_info
+ +USAGE
+ ++js_named_module_info(sources, deps) ++ +
Constructs a JSNamedModuleInfo including all transitive sources from JSNamedModuleInfo providers in a list of deps.
+ +Returns a single JSNamedModuleInfo.
+ +PARAMETERS
+ +sources
+ +deps
+ +Defaults to []
run_node
+ +USAGE
+ ++run_node(ctx, inputs, arguments, executable, chdir, kwargs) ++ +
Helper to replace ctx.actions.run
+ +This calls node programs with a node_modules directory in place
+ +PARAMETERS
+ +ctx
+ +rule context from the calling rule implementation function
+ +inputs
+ +list or depset of inputs to the action
+ +arguments
+ +list or ctx.actions.Args object containing arguments to pass to the executable
+ +executable
+ +stringy representation of the executable this action will run, eg eg. “my_executable” rather than ctx.executable.my_executable
+ +chdir
+ +directory we should change to be the working dir
+ +Defaults to None
kwargs
+ +all other args accepted by ctx.actions.run
+ +node_modules_aspect
+ +USAGE
+ ++node_modules_aspect(name) ++ +
ASPECT ATTRIBUTES
+ +deps
+ +ATTRIBUTES
+ +name
+ +(Name, {util.mandatoryString(name: “name” +doc_string: “A unique name for this target.” +type: NAME +mandatory: true +)}) + A unique name for this target.
+ + +