Google Git
Sign in
pigweed/third_party/github/bazel-contrib/rules_nodejs/8b43896eb586d43f99ae656d4e0478764beafe81/./docs/Built-ins.md
blob: 38f182ded1d80325566885822585a27b55a76ec9 [file] [view]
---
title: Built-ins
layout: default
stylesheet: docs
---
<!-- *********************
DO NOT EDIT THIS FILE
It is a generated build output from Stardoc.
Instead you must edit the .bzl file where the rules are declared,
or possibly a markdown file next to the .bzl file
********************* -->
# 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.
[name]: https://bazel.build/docs/build-ref.html#name
[label]: https://bazel.build/docs/build-ref.html#labels
[labels]: https://bazel.build/docs/build-ref.html#labels
## node_repositories
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.
- 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](repositories.html) for how to use the resulting repositories.
## Creating dependency installation scripts for manually-managed dependencies
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.
Example:
```
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.
### Usage
```
node_repositories(name, node_repositories, node_urls, node_version, package_json, preserve_symlinks, vendored_node, vendored_yarn, yarn_repositories, yarn_urls, yarn_version)
```
#### `name`
(*[name], mandatory*): A unique name for this repository.
#### `node_repositories`
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a>*): 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.
For example,
```python
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"),
},
)
```
Defaults to `{"8.9.1-darwin_amd64": ("node-v8.9.1-darwin-x64.tar.gz", "node-v8.9.1-darwin-x64", "05c992a6621d28d564b92bf3051a5dc0adf83839237c0d4653a8cdb8a1c73b94"), "8.9.1-linux_amd64": ("node-v8.9.1-linux-x64.tar.xz", "node-v8.9.1-linux-x64", "8be82805f7c1ab3e64d4569fb9a90ded2de78dd27cadbb91bad1bf975dae1e2d"), "8.9.1-windows_amd64": ("node-v8.9.1-win-x64.zip", "node-v8.9.1-win-x64", "db89c6e041da359561fbe7da075bb4f9881a0f7d3e98c203e83732cfb283fa4a"), "8.11.1-darwin_amd64": ("node-v8.11.1-darwin-x64.tar.gz", "node-v8.11.1-darwin-x64", "5c7b05899ff56910a2b8180f139d48612f349ac2c5d20f08dbbeffbed9e3a089"), "8.11.1-linux_amd64": ("node-v8.11.1-linux-x64.tar.xz", "node-v8.11.1-linux-x64", "6617e245fa0f7fbe0e373e71d543fea878315324ab31dc64b4eba10e42d04c11"), "8.11.1-windows_amd64": ("node-v8.11.1-win-x64.zip", "node-v8.11.1-win-x64", "7d49b59c2b5d73a14c138e8a215d558a64a5241cd5035d9824f608e7bba097b1"), "8.12.0-darwin_amd64": ("node-v8.12.0-darwin-x64.tar.gz", "node-v8.12.0-darwin-x64", "ca131b84dfcf2b6f653a6521d31f7a108ad7d83f4d7e781945b2eca8172064aa"), "8.12.0-linux_amd64": ("node-v8.12.0-linux-x64.tar.xz", "node-v8.12.0-linux-x64", "29a20479cd1e3a03396a4e74a1784ccdd1cf2f96928b56f6ffa4c8dae40c88f2"), "8.12.0-windows_amd64": ("node-v8.12.0-win-x64.zip", "node-v8.12.0-win-x64", "9b22c9b23148b61ea0052826b3ac0255b8a3a542c125272b8f014f15bf11b091"), "9.11.1-darwin_amd64": ("node-v9.11.1-darwin-x64.tar.gz", "node-v9.11.1-darwin-x64", "7b1fb394aa41a62b477e36df16644bd383cc9084808511f6cd318b835a06aac6"), "9.11.1-linux_amd64": ("node-v9.11.1-linux-x64.tar.xz", "node-v9.11.1-linux-x64", "4d27a95d5c2f1c8ef99118794c9c4903e63963418d3e16ca7576760cff39879b"), "9.11.1-windows_amd64": ("node-v9.11.1-win-x64.zip", "node-v9.11.1-win-x64", "0a3566d57ccb7fed95d18fc6c3bc1552a1b1e4753f9bc6c5d45e04f325e1ee53"), "10.3.0-darwin_amd64": ("node-v10.3.0-darwin-x64.tar.gz", "node-v10.3.0-darwin-x64", "0bb5b7e3fe8cccda2abda958d1eb0408f1518a8b0cb58b75ade5d507cd5d6053"), "10.3.0-linux_amd64": ("node-v10.3.0-linux-x64.tar.xz", "node-v10.3.0-linux-x64", "eb3c3e2585494699716ad3197c8eedf4003d3f110829b30c5a0dc34414c47423"), "10.3.0-windows_amd64": ("node-v10.3.0-win-x64.zip", "node-v10.3.0-win-x64", "65d586afb087406a2800d8e51f664c88b26d510f077b85a3b177a1bb79f73677"), "10.9.0-darwin_amd64": ("node-v10.9.0-darwin-x64.tar.gz", "node-v10.9.0-darwin-x64", "3c4fe75dacfcc495a432a7ba2dec9045cff359af2a5d7d0429c84a424ef686fc"), "10.9.0-linux_amd64": ("node-v10.9.0-linux-x64.tar.xz", "node-v10.9.0-linux-x64", "c5acb8b7055ee0b6ac653dc4e458c5db45348cecc564b388f4ed1def84a329ff"), "10.9.0-windows_amd64": ("node-v10.9.0-win-x64.zip", "node-v10.9.0-win-x64", "6a75cdbb69d62ed242d6cbf0238a470bcbf628567ee339d4d098a5efcda2401e"), "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"), "10.13.0-darwin_amd64": ("node-v10.13.0-darwin-x64.tar.gz", "node-v10.13.0-darwin-x64", "815a5d18516934a3963ace9f0574f7d41f0c0ce9186a19be3d89e039e57598c5"), "10.13.0-linux_amd64": ("node-v10.13.0-linux-x64.tar.xz", "node-v10.13.0-linux-x64", "0dc6dba645550b66f8f00541a428c29da7c3cde32fb7eda2eb626a9db3bbf08d"), "10.13.0-windows_amd64": ("node-v10.13.0-win-x64.zip", "node-v10.13.0-win-x64", "eb09c9e9677f1919ec1ca78623c09b2a718ec5388b72b7662d5c41e5f628a52c"), "10.16.0-darwin_amd64": ("node-v10.16.0-darwin-x64.tar.gz", "node-v10.16.0-darwin-x64", "6c009df1b724026d84ae9a838c5b382662e30f6c5563a0995532f2bece39fa9c"), "10.16.0-linux_amd64": ("node-v10.16.0-linux-x64.tar.xz", "node-v10.16.0-linux-x64", "1827f5b99084740234de0c506f4dd2202a696ed60f76059696747c34339b9d48"), "10.16.0-windows_amd64": ("node-v10.16.0-win-x64.zip", "node-v10.16.0-win-x64", "aa22cb357f0fb54ccbc06b19b60e37eefea5d7dd9940912675d3ed988bf9a059"), "12.13.0-darwin_amd64": ("node-v12.13.0-darwin-x64.tar.gz", "node-v12.13.0-darwin-x64", "49a7374670a111b033ce16611b20fd1aafd3296bbc662b184fe8fb26a29c22cc"), "12.13.0-linux_amd64": ("node-v12.13.0-linux-x64.tar.xz", "node-v12.13.0-linux-x64", "7a57ef2cb3036d7eacd50ae7ba07245a28336a93652641c065f747adb2a356d9"), "12.13.0-windows_amd64": ("node-v12.13.0-win-x64.zip", "node-v12.13.0-win-x64", "6f920cebeecb4957b4ef0def6d9b04c49d4582864f8d1a207ce8d0665865781a")}`
#### `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.
For example, given
```python
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`
Defaults to `["https://mirror.bazel.build/nodejs.org/dist/v{version}/{filename}", "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`
(*[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`
#### `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.
Bazel will automatically turn on features such as --preserve-symlinks-main if they
are supported by the node version being used.
Defaults to `None`
#### `vendored_yarn`
(*[label]*): the local path to a pre-installed yarn tool
Defaults to `None`
#### `yarn_repositories`
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a>*): Custom list of yarn repositories to use.
Dictionary mapping Yarn versions to their corresponding (filename, strip_prefix, sha256) tuples.
For example,
```python
node_repositories(
yarn_repositories = {
"1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
},
)
```
Defaults to `{"1.3.2": ("yarn-v1.3.2.tar.gz", "yarn-v1.3.2", "6cfe82e530ef0837212f13e45c1565ba53f5199eec2527b85ecbcd88bf26821d"), "1.5.1": ("yarn-v1.5.1.tar.gz", "yarn-v1.5.1", "cd31657232cf48d57fdbff55f38bfa058d2fb4950450bd34af72dac796af4de1"), "1.6.0": ("yarn-v1.6.0.tar.gz", "yarn-v1.6.0", "a57b2fdb2bfeeb083d45a883bc29af94d5e83a21c25f3fc001c295938e988509"), "1.9.2": ("yarn-v1.9.2.tar.gz", "yarn-v1.9.2", "3ad69cc7f68159a562c676e21998eb21b44138cae7e8fe0749a7d620cf940204"), "1.9.4": ("yarn-v1.9.4.tar.gz", "yarn-v1.9.4", "7667eb715077b4bad8e2a832e7084e0e6f1ba54d7280dc573c8f7031a7fb093e"), "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"), "1.12.3": ("yarn-v1.12.3.tar.gz", "yarn-v1.12.3", "02cd4b589ec22c4bdbd2bc5ebbfd99c5e99b07242ad68a539cb37896b93a24f2"), "1.13.0": ("yarn-v1.13.0.tar.gz", "yarn-v1.13.0", "125d40ebf621ebb08e3f66a618bd2cc5cd77fa317a312900a1ab4360ed38bf14"), "1.19.1": ("yarn-v1.19.1.tar.gz", "yarn-v1.19.1", "34293da6266f2aae9690d59c2d764056053ff7eebc56b80b8df05010c3da9343")}`
#### `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.
For example,
```python
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`.
Defaults to `["https://mirror.bazel.build/github.com/yarnpkg/yarn/releases/download/v{version}/{filename}", "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
Runs some JavaScript code in NodeJS.
### Usage
```
nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point, install_source_map_support, node_modules, templated_args)
```
#### `name`
(*[name], mandatory*): A unique name for this target.
#### `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`
(*[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
Defaults to `["VERBOSE_LOGS", "NODE_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"],
)
```
#### `install_source_map_support`
(*Boolean*): Install the source-map-support package.
Enable this to get stack traces that point to original sources, e.g. if the program was written
in TypeScript.
Defaults to `True`
#### `node_modules`
(*[label]*): The npm packages which should be available to `require()` during
execution.
This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
to npm dependencies is to use fine grained npm dependencies which are setup
with the `yarn_install` or `npm_install` rules. For example, in targets
that used a `//:node_modules` filegroup,
```
nodejs_binary(
name = "my_binary",
...
node_modules = "//:node_modules",
)
```
which specifies all files within the `//:node_modules` filegroup
to be inputs to the `my_binary`. Using fine grained npm dependencies,
`my_binary` is defined with only the npm dependencies that are
needed:
```
nodejs_binary(
name = "my_binary",
...
data = [
"@npm//foo",
"@npm//bar",
...
],
)
```
In this case, only the `foo` and `bar` npm packages and their
transitive deps are includes as inputs to the `my_binary` target
which reduces the time required to setup the runfiles for this
target (see https://github.com/bazelbuild/bazel/issues/5153).
The @npm external repository and the fine grained npm package
targets are setup using the `yarn_install` or `npm_install` rule
in your WORKSPACE file:
yarn_install(
name = "npm",
package_json = "//:package.json",
yarn_lock = "//:yarn.lock",
)
For other rules such as `jasmine_node_test`, fine grained
npm dependencies are specified in the `deps` attribute:
```
jasmine_node_test(
name = "my_test",
...
deps = [
"@npm//jasmine",
"@npm//foo",
"@npm//bar",
...
],
)
```
Defaults to `//:node_modules_none`
#### `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`
Defaults to `[]`
## nodejs_test
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 like Karma or Jasmine,
use the specific rules for those test runners, e.g. `jasmine_node_test`.
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.
### Usage
```
nodejs_test(name, configuration_env_vars, data, default_env_vars, entry_point, expected_exit_code, install_source_map_support, node_modules, templated_args)
```
#### `name`
(*[name], mandatory*): A unique name for this target.
#### `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`
(*[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
Defaults to `["VERBOSE_LOGS", "NODE_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"],
)
```
#### `expected_exit_code`
(*Integer*): The expected exit code for the test. Defaults to 0.
Defaults to `0`
#### `install_source_map_support`
(*Boolean*): Install the source-map-support package.
Enable this to get stack traces that point to original sources, e.g. if the program was written
in TypeScript.
Defaults to `True`
#### `node_modules`
(*[label]*): The npm packages which should be available to `require()` during
execution.
This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
to npm dependencies is to use fine grained npm dependencies which are setup
with the `yarn_install` or `npm_install` rules. For example, in targets
that used a `//:node_modules` filegroup,
```
nodejs_binary(
name = "my_binary",
...
node_modules = "//:node_modules",
)
```
which specifies all files within the `//:node_modules` filegroup
to be inputs to the `my_binary`. Using fine grained npm dependencies,
`my_binary` is defined with only the npm dependencies that are
needed:
```
nodejs_binary(
name = "my_binary",
...
data = [
"@npm//foo",
"@npm//bar",
...
],
)
```
In this case, only the `foo` and `bar` npm packages and their
transitive deps are includes as inputs to the `my_binary` target
which reduces the time required to setup the runfiles for this
target (see https://github.com/bazelbuild/bazel/issues/5153).
The @npm external repository and the fine grained npm package
targets are setup using the `yarn_install` or `npm_install` rule
in your WORKSPACE file:
yarn_install(
name = "npm",
package_json = "//:package.json",
yarn_lock = "//:yarn.lock",
)
For other rules such as `jasmine_node_test`, fine grained
npm dependencies are specified in the `deps` attribute:
```
jasmine_node_test(
name = "my_test",
...
deps = [
"@npm//jasmine",
"@npm//foo",
"@npm//bar",
...
],
)
```
Defaults to `//:node_modules_none`
#### `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`
Defaults to `[]`
## npm_install
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.
### Usage
```
npm_install(name, always_hide_bazel_files, args, data, environment, included_files, manual_build_file_contents, package_json, package_lock_json, quiet, symlink_node_modules, timeout)
```
#### `name`
(*[name], mandatory*): A unique name for this repository.
#### `always_hide_bazel_files`
(*Boolean*): Always hide Bazel build files such as `BUILD` and BUILD.bazel` by prefixing them with `_`.
This is only needed in Bazel 2.0 or earlier.
We recommend upgrading to a later version to avoid the problem this works around.
Defaults to False, in which case Bazel files are _not_ hidden when `symlink_node_modules`
is True. In this case, the rule will report an error when there are Bazel files detected
in npm packages.
Reporting the error is desirable as relying on this repository rule to hide
these files does not work in the case where a user deletes their node_modules folder
and manually re-creates it with yarn or npm outside of Bazel which would restore them.
On a subsequent Bazel build, this repository rule does not re-run and the presence
of the Bazel files leads to a build failure that looks like the following:
```
ERROR: /private/var/tmp/_bazel_greg/37b273501bbecefcf5ce4f3afcd7c47a/external/npm/BUILD.bazel:9:1:
Label '@npm//:node_modules/rxjs/src/AsyncSubject.ts' crosses boundary of subpackage '@npm//node_modules/rxjs/src'
(perhaps you meant to put the colon here: '@npm//node_modules/rxjs/src:AsyncSubject.ts'?)
```
See https://github.com/bazelbuild/rules_nodejs/issues/802 for more details.
The recommended solution is to use the @bazel/hide-bazel-files utility to hide these files.
See https://github.com/bazelbuild/rules_nodejs/blob/master/packages/hide-bazel-files/README.md
for installation instructions.
The alternate solution is to set `always_hide_bazel_files` to True which tell
this rule to hide Bazel files even when `symlink_node_modules` is True. This means
you won't need to use `@bazel/hide-bazel-files` utility but if you manually recreate
your `node_modules` folder via yarn or npm outside of Bazel you may run into the above
error.
Defaults to `False`
#### `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`
(*[labels]*): Data files required by this rule.
If symlink_node_modules is True, this attribute is ignored since
the dependency manager will run in the package.json location.
Defaults to `[]`
#### `environment`
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Environment variables to set before calling the package manager.
Defaults to `{}`
#### `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 `[]`
#### `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_lock_json`
(*[label], mandatory*)
#### `quiet`
(*Boolean*): If stdout and stderr should be printed to the terminal.
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
The pkg_npm rule creates a directory containing a publishable npm artifact.
Example:
```python
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:
```javascript
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](https://github.com/bazelbuild/rules_nodejs/blob/master/docs/index.md#stamping)
Usage:
`pkg_npm` yields three labels. Build the package directory using the default label:
```sh
$ 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):
```sh
$ 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):
```sh
# Check login credentials
$ bazel run @nodejs//:npm_node_repositories who
# Publishes the package
$ bazel run :my_package.publish
```
> Note that the `.pack` and `.publish` commands require that the `bazel-out` symlink exists in your project.
> Also, you must run the command from the workspace root directory containing the `bazel-out` symlink.
You can pass arguments to npm by escaping them from Bazel using a double-hyphen, for example:
`bazel run my_package.publish -- --tag=next`
### Usage
```
pkg_npm(name, deps, hide_build_files, nested_packages, node_context_data, replace_with_version, srcs, substitutions, vendor_external)
```
#### `name`
(*[name], mandatory*): A unique name for this target.
#### `deps`
(*[labels]*): Other targets which produce files that should be included in the package, such as `rollup_bundle`
Defaults to `[]`
#### `hide_build_files`
(*Boolean*): If set BUILD and BUILD.bazel files are prefixed with `_` in the npm package.
The default is True since npm packages that contain BUILD files don't work with
`yarn_install` and `npm_install` without a post-install step that deletes or renames them.
NB: Bazel has a change in https://github.com/bazelbuild/bazel/pull/10261
(expected in version 2.1) that adds .bazelignore
support for external repositories, which will make this attribute obsolete.
Defaults to `True`
#### `nested_packages`
(*[labels]*): Other pkg_npm rules whose content is copied into this package.
Defaults to `[]`
#### `node_context_data`
(*[label]*): Internal use only
Defaults to `@build_bazel_rules_nodejs//internal:node_context_data`
#### `replace_with_version`
(*String*): If set this value is replaced with the version stamp data.
See the section on stamping in the README.
Defaults to `"0.0.0-PLACEHOLDER"`
#### `srcs`
(*[labels]*): Files inside this directory which are simply copied into the package.
Defaults to `[]`
#### `substitutions`
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Key-value pairs which are replaced in all the files while building the package.
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
Assembles a web application from source files.
### Usage
```
pkg_web(name, additional_root_paths, srcs)
```
#### `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 `[]`
#### `srcs`
(*[labels]*): Files which should be copied into the package
Defaults to `[]`
## yarn_install
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.
### Usage
```
yarn_install(name, always_hide_bazel_files, args, data, environment, included_files, manual_build_file_contents, package_json, quiet, symlink_node_modules, timeout, use_global_yarn_cache, yarn_lock)
```
#### `name`
(*[name], mandatory*): A unique name for this repository.
#### `always_hide_bazel_files`
(*Boolean*): Always hide Bazel build files such as `BUILD` and BUILD.bazel` by prefixing them with `_`.
This is only needed in Bazel 2.0 or earlier.
We recommend upgrading to a later version to avoid the problem this works around.
Defaults to False, in which case Bazel files are _not_ hidden when `symlink_node_modules`
is True. In this case, the rule will report an error when there are Bazel files detected
in npm packages.
Reporting the error is desirable as relying on this repository rule to hide
these files does not work in the case where a user deletes their node_modules folder
and manually re-creates it with yarn or npm outside of Bazel which would restore them.
On a subsequent Bazel build, this repository rule does not re-run and the presence
of the Bazel files leads to a build failure that looks like the following:
```
ERROR: /private/var/tmp/_bazel_greg/37b273501bbecefcf5ce4f3afcd7c47a/external/npm/BUILD.bazel:9:1:
Label '@npm//:node_modules/rxjs/src/AsyncSubject.ts' crosses boundary of subpackage '@npm//node_modules/rxjs/src'
(perhaps you meant to put the colon here: '@npm//node_modules/rxjs/src:AsyncSubject.ts'?)
```
See https://github.com/bazelbuild/rules_nodejs/issues/802 for more details.
The recommended solution is to use the @bazel/hide-bazel-files utility to hide these files.
See https://github.com/bazelbuild/rules_nodejs/blob/master/packages/hide-bazel-files/README.md
for installation instructions.
The alternate solution is to set `always_hide_bazel_files` to True which tell
this rule to hide Bazel files even when `symlink_node_modules` is True. This means
you won't need to use `@bazel/hide-bazel-files` utility but if you manually recreate
your `node_modules` folder via yarn or npm outside of Bazel you may run into the above
error.
Defaults to `False`
#### `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`
(*[labels]*): Data files required by this rule.
If symlink_node_modules is True, this attribute is ignored since
the dependency manager will run in the package.json location.
Defaults to `[]`
#### `environment`
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Environment variables to set before calling the package manager.
Defaults to `{}`
#### `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 `[]`
#### `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*)
#### `quiet`
(*Boolean*): If stdout and stderr should be printed to the terminal.
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
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.
### Usage
```
check_bazel_version(minimum_bazel_version, message)
```
#### `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
Copies a source file to bazel-bin at the same workspace-relative path 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.
### Usage
```
copy_to_bin(name, srcs, kwargs)
```
#### `name`
Name of the rule.
#### `srcs`
A List of Labels. File(s) to to copy.
#### `kwargs`
further keyword arguments, e.g. `visibility`
## npm_package_bin
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.
This is a great candidate to wrap with a macro, as documented:
https://docs.bazel.build/versions/master/skylark/macros.html#full-example
### Usage
```
npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, kwargs)
```
#### `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](https://docs.bazel.build/versions/master/be/general.html#genrule.srcs)
may also include targets that produce or reference npm packages which are needed by the tool
Defaults to `[]`
#### `outs`
similar to [genrule.outs](https://docs.bazel.build/versions/master/be/general.html#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.
1. 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.
2. "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 `[]`
#### `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`
#### `kwargs`
## params_file
Generates a UTF-8 encoded params file from a list of arguments.
Handles $(location) expansions for arguments.
### Usage
```
params_file(name, out, args, newline, kwargs)
```
#### `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 $(location) substitutions
Defaults to `[]`
#### `newline`
one of ["auto", "unix", "windows"]: line endings to use. "auto"
for platform-determined, "unix" for LF, and "windows" for CRLF.
Defaults to `"auto"`
#### `kwargs`
further keyword arguments, e.g. <code>visibility</code>