Google Git
Sign in
pigweed / third_party / github / bazel-contrib / rules_nodejs / refs/heads/upstream/6.x-nodeps / . / docs / Built-ins.md
blob: c650ec4a3154692cf9cbae5ce6685541d60e03b7 [file] [log] [blame] [view] [edit]
<!-- *********************
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.
## directory_file_path
**USAGE**
<pre>
directory_file_path(<a href="#directory_file_path-name">name</a>, <a href="#directory_file_path-directory">directory</a>, <a href="#directory_file_path-path">path</a>)
</pre>
Provide DirectoryFilePathInfo to reference some file within a directory.
Otherwise there is no way to give a Bazel label for it.
**ATTRIBUTES**
<h4 id="directory_file_path-name">name</h4>
(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.
<h4 id="directory_file_path-directory">directory</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*): a directory
<h4 id="directory_file_path-path">path</h4>
(*String, mandatory*): a path within that directory
## nodejs_binary
**USAGE**
<pre>
nodejs_binary(<a href="#nodejs_binary-name">name</a>, <a href="#nodejs_binary-chdir">chdir</a>, <a href="#nodejs_binary-configuration_env_vars">configuration_env_vars</a>, <a href="#nodejs_binary-data">data</a>, <a href="#nodejs_binary-default_env_vars">default_env_vars</a>, <a href="#nodejs_binary-entry_point">entry_point</a>, <a href="#nodejs_binary-env">env</a>,
<a href="#nodejs_binary-link_workspace_root">link_workspace_root</a>, <a href="#nodejs_binary-templated_args">templated_args</a>, <a href="#nodejs_binary-toolchain">toolchain</a>)
</pre>
Runs some JavaScript code in NodeJS. You can also change the default args that are sent to nodejs. This can be done through a flag. The default is --preserve-symlinks while anything
can be passed. The flag is --@rules_nodejs//nodejs:default_args="" ex: bazel build --@rules_nodejs//nodejs:default_args="--preserve-symlinks --no-warnings" //:target.
This will pass --preserve-symlinks and --no-warnings flags to nodejs. Available node flags can be found here: https://nodejs.org/api/cli.html.
**ATTRIBUTES**
<h4 id="nodejs_binary-name">name</h4>
(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.
<h4 id="nodejs_binary-chdir">chdir</h4>
(*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 `""`
<h4 id="nodejs_binary-configuration_env_vars">configuration_env_vars</h4>
(*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 `[]`
<h4 id="nodejs_binary-data">data</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Runtime dependencies which may be loaded during execution.
Defaults to `[]`
<h4 id="nodejs_binary-default_env_vars">default_env_vars</h4>
(*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"]`
<h4 id="nodejs_binary-entry_point">entry_point</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, 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:
```python
nodejs_binary(
name = "my_binary",
...
entry_point = ":file.js",
)
```
```python
nodejs_binary(
name = "bin",
entry_point = ":main.js",
)
```
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:
```python
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:
```python
nodejs_binary(
name = "history-server",
entry_point = "@npm//:node_modules/history-server/modules/cli.js",
data = ["@npm//history-server"],
)
```
<h4 id="nodejs_binary-env">env</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Specifies additional environment variables to set when the target is executed, subject to location
and make variable expansion.
Defaults to `{}`
<h4 id="nodejs_binary-link_workspace_root">link_workspace_root</h4>
(*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`
<h4 id="nodejs_binary-templated_args">templated_args</h4>
(*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/main/be/make-variables.html.
1. 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/main/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:
```python
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:
```python
nodejs_test(
name = "my_test",
data = [":some_file"],
entry_point = ":my_test.js",
templated_args = ["$(rootpath :some_file)"],
)
```
my_test.js
```python
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/main/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.
2. 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/main/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/main/be/make-variables.html#custom_variables.
Predefined genrule variables are not supported in this context.
Defaults to `[]`
<h4 id="nodejs_binary-toolchain">toolchain</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*)
Defaults to `None`
## nodejs_test
**USAGE**
<pre>
nodejs_test(<a href="#nodejs_test-name">name</a>, <a href="#nodejs_test-chdir">chdir</a>, <a href="#nodejs_test-configuration_env_vars">configuration_env_vars</a>, <a href="#nodejs_test-data">data</a>, <a href="#nodejs_test-default_env_vars">default_env_vars</a>, <a href="#nodejs_test-entry_point">entry_point</a>, <a href="#nodejs_test-env">env</a>,
<a href="#nodejs_test-expected_exit_code">expected_exit_code</a>, <a href="#nodejs_test-link_workspace_root">link_workspace_root</a>, <a href="#nodejs_test-templated_args">templated_args</a>, <a href="#nodejs_test-toolchain">toolchain</a>)
</pre>
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`.
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:
```python
# 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.
You can also change the default args that are sent to nodejs. This can be done through a flag. The default is --preserve-symlinks while anything
can be passed. The flag is --@rules_nodejs//nodejs:default_args="" ex: bazel test --@rules_nodejs//nodejs:default_args="--preserve-symlinks --no-warnings" //:target.
This will pass --preserve-symlinks and --no-warnings flags to nodejs. Available node flags can be found here: https://nodejs.org/api/cli.html.
**ATTRIBUTES**
<h4 id="nodejs_test-name">name</h4>
(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.
<h4 id="nodejs_test-chdir">chdir</h4>
(*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 `""`
<h4 id="nodejs_test-configuration_env_vars">configuration_env_vars</h4>
(*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 `[]`
<h4 id="nodejs_test-data">data</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Runtime dependencies which may be loaded during execution.
Defaults to `[]`
<h4 id="nodejs_test-default_env_vars">default_env_vars</h4>
(*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"]`
<h4 id="nodejs_test-entry_point">entry_point</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, 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:
```python
nodejs_binary(
name = "my_binary",
...
entry_point = ":file.js",
)
```
```python
nodejs_binary(
name = "bin",
entry_point = ":main.js",
)
```
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:
```python
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:
```python
nodejs_binary(
name = "history-server",
entry_point = "@npm//:node_modules/history-server/modules/cli.js",
data = ["@npm//history-server"],
)
```
<h4 id="nodejs_test-env">env</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Specifies additional environment variables to set when the target is executed, subject to location
and make variable expansion.
Defaults to `{}`
<h4 id="nodejs_test-expected_exit_code">expected_exit_code</h4>
(*Integer*): The expected exit code for the test. Defaults to 0.
Defaults to `0`
<h4 id="nodejs_test-link_workspace_root">link_workspace_root</h4>
(*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`
<h4 id="nodejs_test-templated_args">templated_args</h4>
(*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/main/be/make-variables.html.
1. 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/main/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:
```python
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:
```python
nodejs_test(
name = "my_test",
data = [":some_file"],
entry_point = ":my_test.js",
templated_args = ["$(rootpath :some_file)"],
)
```
my_test.js
```python
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/main/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.
2. 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/main/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/main/be/make-variables.html#custom_variables.
Predefined genrule variables are not supported in this context.
Defaults to `[]`
<h4 id="nodejs_test-toolchain">toolchain</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*)
Defaults to `None`
## npm_install
**USAGE**
<pre>
npm_install(<a href="#npm_install-name">name</a>, <a href="#npm_install-all_node_modules_target_name">all_node_modules_target_name</a>, <a href="#npm_install-args">args</a>, <a href="#npm_install-data">data</a>, <a href="#npm_install-environment">environment</a>, <a href="#npm_install-exports_directories_only">exports_directories_only</a>,
<a href="#npm_install-generate_build_files_concurrency_limit">generate_build_files_concurrency_limit</a>, <a href="#npm_install-generate_local_modules_build_files">generate_local_modules_build_files</a>,
<a href="#npm_install-included_files">included_files</a>, <a href="#npm_install-links">links</a>, <a href="#npm_install-manual_build_file_contents">manual_build_file_contents</a>, <a href="#npm_install-node_repository">node_repository</a>, <a href="#npm_install-npm_command">npm_command</a>,
<a href="#npm_install-package_json">package_json</a>, <a href="#npm_install-package_json_remove">package_json_remove</a>, <a href="#npm_install-package_json_replace">package_json_replace</a>, <a href="#npm_install-package_lock_json">package_lock_json</a>, <a href="#npm_install-package_path">package_path</a>,
<a href="#npm_install-patch_args">patch_args</a>, <a href="#npm_install-patch_tool">patch_tool</a>, <a href="#npm_install-post_install_patches">post_install_patches</a>, <a href="#npm_install-pre_install_patches">pre_install_patches</a>, <a href="#npm_install-quiet">quiet</a>, <a href="#npm_install-repo_mapping">repo_mapping</a>,
<a href="#npm_install-strict_visibility">strict_visibility</a>, <a href="#npm_install-symlink_node_modules">symlink_node_modules</a>, <a href="#npm_install-timeout">timeout</a>)
</pre>
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**
<h4 id="npm_install-name">name</h4>
(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this repository.
<h4 id="npm_install-all_node_modules_target_name">all_node_modules_target_name</h4>
(*String*): The name used for the generated all node_modules js_library target.
This can be used to name the all node_modules target something other than `//:node_modules`,
such as `//:node_modules_all`, so you can use the `//:node_modules` label to reference the
`node_modules` source directory in `manual_build_file_contents` for custom use cases.
Defaults to `"node_modules"`
<h4 id="npm_install-args">args</h4>
(*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 `[]`
<h4 id="npm_install-data">data</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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
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 `[]`
<h4 id="npm_install-environment">environment</h4>
(*<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 `{}`
<h4 id="npm_install-exports_directories_only">exports_directories_only</h4>
(*Boolean*): Export only top-level package directory artifacts from node_modules.
Set to `False` to export all individual files from node_modules.
When enabled, this decreases the time it takes for Bazel to setup runfiles and sandboxing when
there are a large number of npm dependencies as inputs to an action.
To reference files within npm packages, you can use the `directory_file_path` rule and/or `DirectoryFilePathInfo` provider.
Note, some rules still need upgrading to support consuming `DirectoryFilePathInfo` where needed.
NB: This feature requires runfiles be enabled due to an issue in Bazel which we are still investigating.
On Windows runfiles are off by default and must be enabled with the `--enable_runfiles` flag when
using this feature.
For the `nodejs_binary` & `nodejs_test` `entry_point` attribute (which often needs to reference a file within
an npm package) you can set the entry_point to a dict with a single entry, where the key corresponds to the directory
label and the value corresponds to the path within that directory to the entry point, e.g.
```
nodejs_binary(
name = "prettier",
data = ["@npm//prettier"],
entry_point = { "@npm//:node_modules/prettier": "bin-prettier.js" },
)
```
For labels that are passed to `$(rootpath)`, `$(execpath)`, or `$(location)` you can simply break these apart into
the directory label that gets passed to the expander & path part to follows it, e.g.
```
$(rootpath @npm///:node_modules/prettier)/bin-prettier.js
```
Defaults to `True`
<h4 id="npm_install-generate_build_files_concurrency_limit">generate_build_files_concurrency_limit</h4>
(*Integer*): Limit the maximum concurrency of npm package processing when generating
BUILD files from the node_modules tree. Unlimited concurrency can lead to too many
open files errors (https://github.com/bazelbuild/rules_nodejs/issues/3507).
Set to 0 or negative for unlimited concurrency.
Defaults to `64`
<h4 id="npm_install-generate_local_modules_build_files">generate_local_modules_build_files</h4>
(*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`
<h4 id="npm_install-included_files">included_files</h4>
(*List of strings*): List of file extensions to be included in the npm package targets.
NB: This option has no effect when exports_directories_only is True as all files are
automatically included in the exported directory for each npm package.
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 `[]`
<h4 id="npm_install-links">links</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Targets to link as npm packages.
A mapping of npm package names to bazel targets to linked into node_modules.
For example,
```
yarn_install(
name = "npm",
package_json = "//web:package.json",
yarn_lock = "//web:yarn.lock",
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 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"
],
)
```
Defaults to `{}`
<h4 id="npm_install-manual_build_file_contents">manual_build_file_contents</h4>
(*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 `""`
<h4 id="npm_install-node_repository">node_repository</h4>
(*String*): The basename for a nodejs toolchain to use for running npm.
Usually this is the value of the `name` attribute given to a nodejs_register_toolchains call in WORKSPACE
Defaults to `"nodejs"`
<h4 id="npm_install-npm_command">npm_command</h4>
(*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"`
<h4 id="npm_install-package_json">package_json</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*)
<h4 id="npm_install-package_json_remove">package_json_remove</h4>
(*List of strings*): List of `package.json` keys to remove before running the package manager.
Keys are '.' separated. For example, a key of `dependencies.my-dep` in the list corresponds to the `package.json`
entry,
```
{
"dependencies": {
"my-dep": "..."
}
}
```
This can be used, for example, during a migration to remove first party file: deps that are required
for the non-bazel build but should not be installed via the package manager in the bazel build since
they will be reference as bazel targets instead.
NB: removals specified are performed after preinstall_patches so if you are using both then the patch file should be relative
to the source `package.json`. Non-existant keys are silently ignored.
Defaults to `[]`
<h4 id="npm_install-package_json_replace">package_json_replace</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Map of `package.json` keys to values to replace or create before running the package mangager.
Keys are '.' separated. For example, a key of `scripts.postinstall` corresponds to the `package.json`
entry,
```
{
"scripts": {
"postinstall": "..."
}
}
```
This can be used, for example, during a migration to override npm scripts such as preinstall & postinstall.
NB: replaces specified are performed after preinstall_patches so if you are using both then the patch file should be relative
to the source `package.json`.
Defaults to `{}`
<h4 id="npm_install-package_lock_json">package_lock_json</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*)
<h4 id="npm_install-package_path">package_path</h4>
(*String*): The directory to link `node_modules` to in the execroot and in runfiles.
If unset, link `node_modules` to the directory of the `package.json` file specified in the
`package_json` attribute. Set to "/" to link to the root directory.
Defaults to `""`
<h4 id="npm_install-patch_args">patch_args</h4>
(*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"]`
<h4 id="npm_install-patch_tool">patch_tool</h4>
(*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 `""`
<h4 id="npm_install-post_install_patches">post_install_patches</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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.
Use with caution when `symlink_node_modules` enabled as the patches will run in your workspace and
will modify files in your workspace.
NB: If `symlink_node_modules` is enabled, the node_modules folder is re-used between executions of the
repository rule. Patches may be re-applied to files in this case and fail to apply. A marker file
`node_modules/.bazel-post-install-patches` is left in this mode when patches are applied. When the
marker file is detected, patch file failures are treated as WARNINGS. For this reason, it is recommended
to patch npm packages with an npm tool such as https://www.npmjs.com/package/patch-package when
`symlink_node_modules` is enabled which handles re-apply patching logic more robustly.
Defaults to `[]`
<h4 id="npm_install-pre_install_patches">pre_install_patches</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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.
Not supported with `symlink_node_modules` enabled.
Defaults to `[]`
<h4 id="npm_install-quiet">quiet</h4>
(*Boolean*): If stdout and stderr should be printed to the terminal.
Defaults to `True`
<h4 id="npm_install-repo_mapping">repo_mapping</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>, 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`).
<h4 id="npm_install-strict_visibility">strict_visibility</h4>
(*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`
<h4 id="npm_install-symlink_node_modules">symlink_node_modules</h4>
(*Boolean*): Turn symlinking of node_modules on.
**Use of this feature is not recommended, as Bazel is removing `managed_directories`.
See https://github.com/bazelbuild/bazel/issues/15463
When False, the package manager will run in the external repository
created by this rule.
This requires that any files required for it to run should be listed in the
`data` attribute. These files would include things like patch files that are
read by a postinstall lifecycle hook such as the `patch-package` package uses.
`package.json` and the lock file are already specified in dedicated attributes
of this rule and do not need to be included in the `data`.
When True, we run the package manager (npm or yarn) with the working directory
set in your source tree, in the folder containing the package.json file.
The resulting `node_modules` folder in the source tree will be symlinked to the
external repository created by this rule.
This gives the user experience of running `bazel build` in a clean clone,
and the `node_modules` folder is created as if you had run `npm install` yourself.
It avoids installing the dependencies twice in a typical developer workflow, where you'd
need to `npm install` for tooling like formatters or editors, and then Bazel installs
a second copy in its external repository. This can save some time.
It also means you can patch the source files in the `node_modules` folder and these changes
will be reflected in subsequent Bazel executions.
WARNING: we suspect there are some hard-to-reproduce bugs when this feature is used,
because any corruption in the node_modules tree won't be corrected by Bazel.
When repairing this with `bazel clean --expunge` you'll also have to `rm -rf node_modules`
or else the next Bazel run will re-use the same corrupted `node_modules` folder by restoring
the symlink to it.
When using symlink_node_modules, we recommend also enabling Bazel's `managed_directories`
for the node_modules folder. This is documented in the
[workspace global](https://docs.bazel.build/versions/main/skylark/lib/globals.html#workspace)
Be sure to include the `node_modules` path in the `.bazelignore` file.
Using managed_directories will mean that
1. changes to files under `node_modules` are tracked by Bazel as if they were located
in the external repository folder, and
2. if the `node_modules` folder is deleted from the source tree, Bazel will re-run the
repository rule that creates it again on the next run.
Defaults to `False`
<h4 id="npm_install-timeout">timeout</h4>
(*Integer*): Maximum duration of the package manager execution in seconds.
Defaults to `3600`
## pkg_npm
**USAGE**
<pre>
pkg_npm(<a href="#pkg_npm-name">name</a>, <a href="#pkg_npm-deps">deps</a>, <a href="#pkg_npm-nested_packages">nested_packages</a>, <a href="#pkg_npm-package_name">package_name</a>, <a href="#pkg_npm-package_path">package_path</a>, <a href="#pkg_npm-srcs">srcs</a>, <a href="#pkg_npm-stamp">stamp</a>, <a href="#pkg_npm-substitutions">substitutions</a>, <a href="#pkg_npm-tgz">tgz</a>,
<a href="#pkg_npm-validate">validate</a>, <a href="#pkg_npm-vendor_external">vendor_external</a>)
</pre>
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 four 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_host//:npm 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:
```python
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**
<h4 id="pkg_npm-name">name</h4>
(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.
<h4 id="pkg_npm-deps">deps</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Other targets which produce files that should be included in the package
Defaults to `[]`
<h4 id="pkg_npm-nested_packages">nested_packages</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Other pkg_npm rules whose content is copied into this package.
Defaults to `[]`
<h4 id="pkg_npm-package_name">package_name</h4>
(*String*): The package name that the linker will link this npm package as.
If package_path is set, the linker will link this package under <package_path>/node_modules/<package_name>.
If package_path is not set the this will be the root node_modules of the workspace.
Defaults to `""`
<h4 id="pkg_npm-package_path">package_path</h4>
(*String*): The package path in the workspace that the linker will link this npm package to.
If package_path is set, the linker will link this package under <package_path>/node_modules/<package_name>.
If package_path is not set the this will be the root node_modules of the workspace.
Defaults to `""`
<h4 id="pkg_npm-srcs">srcs</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Files inside this directory which are simply copied into the package.
Defaults to `[]`
<h4 id="pkg_npm-stamp">stamp</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): Whether to encode build information into the output. Possible values:
- `@rules_nodejs//nodejs/stamp:always`:
Always stamp the build information into the output, even in [--nostamp][stamp] builds.
This setting should be avoided, since it potentially causes cache misses remote caching for
any downstream actions that depend on it.
- `@rules_nodejs//nodejs/stamp:never`:
Always replace build information by constant values. This gives good build result caching.
- `@rules_nodejs//nodejs/stamp:use_stamp_flag`:
Embedding of build information is controlled by the [--[no]stamp][stamp] flag.
Stamped binaries are not rebuilt unless their dependencies change.
[stamp]: https://docs.bazel.build/versions/main/user-manual.html#flag--stamp The dependencies of this attribute must provide: StampSettingInfo
Defaults to `@rules_nodejs//nodejs/stamp:use_stamp_flag`
<h4 id="pkg_npm-substitutions">substitutions</h4>
(*<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.
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](stamping)
Defaults to `{}`
<h4 id="pkg_npm-tgz">tgz</h4>
(*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 `""`
<h4 id="pkg_npm-validate">validate</h4>
(*Boolean*): Whether to check that the attributes match the package.json
Defaults to `True`
<h4 id="pkg_npm-vendor_external">vendor_external</h4>
(*List of strings*): External workspaces whose contents should be vendored into this workspace.
Avoids `external/foo` path segments in the resulting package.
Defaults to `[]`
## yarn_install
**USAGE**
<pre>
yarn_install(<a href="#yarn_install-name">name</a>, <a href="#yarn_install-all_node_modules_target_name">all_node_modules_target_name</a>, <a href="#yarn_install-args">args</a>, <a href="#yarn_install-data">data</a>, <a href="#yarn_install-environment">environment</a>, <a href="#yarn_install-exports_directories_only">exports_directories_only</a>,
<a href="#yarn_install-frozen_lockfile">frozen_lockfile</a>, <a href="#yarn_install-generate_build_files_concurrency_limit">generate_build_files_concurrency_limit</a>,
<a href="#yarn_install-generate_local_modules_build_files">generate_local_modules_build_files</a>, <a href="#yarn_install-included_files">included_files</a>, <a href="#yarn_install-links">links</a>, <a href="#yarn_install-manual_build_file_contents">manual_build_file_contents</a>,
<a href="#yarn_install-node_repository">node_repository</a>, <a href="#yarn_install-package_json">package_json</a>, <a href="#yarn_install-package_json_remove">package_json_remove</a>, <a href="#yarn_install-package_json_replace">package_json_replace</a>, <a href="#yarn_install-package_path">package_path</a>,
<a href="#yarn_install-patch_args">patch_args</a>, <a href="#yarn_install-patch_tool">patch_tool</a>, <a href="#yarn_install-post_install_patches">post_install_patches</a>, <a href="#yarn_install-pre_install_patches">pre_install_patches</a>, <a href="#yarn_install-quiet">quiet</a>, <a href="#yarn_install-repo_mapping">repo_mapping</a>,
<a href="#yarn_install-strict_visibility">strict_visibility</a>, <a href="#yarn_install-symlink_node_modules">symlink_node_modules</a>, <a href="#yarn_install-timeout">timeout</a>, <a href="#yarn_install-use_global_yarn_cache">use_global_yarn_cache</a>, <a href="#yarn_install-yarn">yarn</a>, <a href="#yarn_install-yarn_lock">yarn_lock</a>)
</pre>
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**
<h4 id="yarn_install-name">name</h4>
(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this repository.
<h4 id="yarn_install-all_node_modules_target_name">all_node_modules_target_name</h4>
(*String*): The name used for the generated all node_modules js_library target.
This can be used to name the all node_modules target something other than `//:node_modules`,
such as `//:node_modules_all`, so you can use the `//:node_modules` label to reference the
`node_modules` source directory in `manual_build_file_contents` for custom use cases.
Defaults to `"node_modules"`
<h4 id="yarn_install-args">args</h4>
(*List of strings*): Arguments passed to yarn install.
See yarn CLI docs for complete list of supported arguments.
Yarn 1: https://yarnpkg.com/en/docs/cli/install
Yarn 2+ (Berry): https://yarnpkg.com/cli/install
Note that Yarn Berry PnP is *not* supported, follow
https://github.com/bazelbuild/rules_nodejs/issues/1599
Defaults to `[]`
<h4 id="yarn_install-data">data</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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
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 `[]`
<h4 id="yarn_install-environment">environment</h4>
(*<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 `{}`
<h4 id="yarn_install-exports_directories_only">exports_directories_only</h4>
(*Boolean*): Export only top-level package directory artifacts from node_modules.
Set to `False` to export all individual files from node_modules.
When enabled, this decreases the time it takes for Bazel to setup runfiles and sandboxing when
there are a large number of npm dependencies as inputs to an action.
To reference files within npm packages, you can use the `directory_file_path` rule and/or `DirectoryFilePathInfo` provider.
Note, some rules still need upgrading to support consuming `DirectoryFilePathInfo` where needed.
NB: This feature requires runfiles be enabled due to an issue in Bazel which we are still investigating.
On Windows runfiles are off by default and must be enabled with the `--enable_runfiles` flag when
using this feature.
For the `nodejs_binary` & `nodejs_test` `entry_point` attribute (which often needs to reference a file within
an npm package) you can set the entry_point to a dict with a single entry, where the key corresponds to the directory
label and the value corresponds to the path within that directory to the entry point, e.g.
```
nodejs_binary(
name = "prettier",
data = ["@npm//prettier"],
entry_point = { "@npm//:node_modules/prettier": "bin-prettier.js" },
)
```
For labels that are passed to `$(rootpath)`, `$(execpath)`, or `$(location)` you can simply break these apart into
the directory label that gets passed to the expander & path part to follows it, e.g.
```
$(rootpath @npm///:node_modules/prettier)/bin-prettier.js
```
Defaults to `True`
<h4 id="yarn_install-frozen_lockfile">frozen_lockfile</h4>
(*Boolean*): Use the `--frozen-lockfile` flag for yarn 1
Users of Yarn 2+ (Berry) should just pass `--immutable` to the `args` attribute.
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 @yarn//:yarn install`. You can pass the options like
`bazel run @yarn//:yarn install -- -D <dep-name>`.
Defaults to `True`
<h4 id="yarn_install-generate_build_files_concurrency_limit">generate_build_files_concurrency_limit</h4>
(*Integer*): Limit the maximum concurrency of npm package processing when generating
BUILD files from the node_modules tree. Unlimited concurrency can lead to too many
open files errors (https://github.com/bazelbuild/rules_nodejs/issues/3507).
Set to 0 or negative for unlimited concurrency.
Defaults to `64`
<h4 id="yarn_install-generate_local_modules_build_files">generate_local_modules_build_files</h4>
(*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`
<h4 id="yarn_install-included_files">included_files</h4>
(*List of strings*): List of file extensions to be included in the npm package targets.
NB: This option has no effect when exports_directories_only is True as all files are
automatically included in the exported directory for each npm package.
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 `[]`
<h4 id="yarn_install-links">links</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Targets to link as npm packages.
A mapping of npm package names to bazel targets to linked into node_modules.
For example,
```
yarn_install(
name = "npm",
package_json = "//web:package.json",
yarn_lock = "//web:yarn.lock",
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 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"
],
)
```
Defaults to `{}`
<h4 id="yarn_install-manual_build_file_contents">manual_build_file_contents</h4>
(*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 `""`
<h4 id="yarn_install-node_repository">node_repository</h4>
(*String*): The basename for a nodejs toolchain to use for running npm.
Usually this is the value of the `name` attribute given to a nodejs_register_toolchains call in WORKSPACE
Defaults to `"nodejs"`
<h4 id="yarn_install-package_json">package_json</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*)
<h4 id="yarn_install-package_json_remove">package_json_remove</h4>
(*List of strings*): List of `package.json` keys to remove before running the package manager.
Keys are '.' separated. For example, a key of `dependencies.my-dep` in the list corresponds to the `package.json`
entry,
```
{
"dependencies": {
"my-dep": "..."
}
}
```
This can be used, for example, during a migration to remove first party file: deps that are required
for the non-bazel build but should not be installed via the package manager in the bazel build since
they will be reference as bazel targets instead.
NB: removals specified are performed after preinstall_patches so if you are using both then the patch file should be relative
to the source `package.json`. Non-existant keys are silently ignored.
Defaults to `[]`
<h4 id="yarn_install-package_json_replace">package_json_replace</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): Map of `package.json` keys to values to replace or create before running the package mangager.
Keys are '.' separated. For example, a key of `scripts.postinstall` corresponds to the `package.json`
entry,
```
{
"scripts": {
"postinstall": "..."
}
}
```
This can be used, for example, during a migration to override npm scripts such as preinstall & postinstall.
NB: replaces specified are performed after preinstall_patches so if you are using both then the patch file should be relative
to the source `package.json`.
Defaults to `{}`
<h4 id="yarn_install-package_path">package_path</h4>
(*String*): The directory to link `node_modules` to in the execroot and in runfiles.
If unset, link `node_modules` to the directory of the `package.json` file specified in the
`package_json` attribute. Set to "/" to link to the root directory.
Defaults to `""`
<h4 id="yarn_install-patch_args">patch_args</h4>
(*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"]`
<h4 id="yarn_install-patch_tool">patch_tool</h4>
(*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 `""`
<h4 id="yarn_install-post_install_patches">post_install_patches</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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.
Use with caution when `symlink_node_modules` enabled as the patches will run in your workspace and
will modify files in your workspace.
NB: If `symlink_node_modules` is enabled, the node_modules folder is re-used between executions of the
repository rule. Patches may be re-applied to files in this case and fail to apply. A marker file
`node_modules/.bazel-post-install-patches` is left in this mode when patches are applied. When the
marker file is detected, patch file failures are treated as WARNINGS. For this reason, it is recommended
to patch npm packages with an npm tool such as https://www.npmjs.com/package/patch-package when
`symlink_node_modules` is enabled which handles re-apply patching logic more robustly.
Defaults to `[]`
<h4 id="yarn_install-pre_install_patches">pre_install_patches</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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.
Not supported with `symlink_node_modules` enabled.
Defaults to `[]`
<h4 id="yarn_install-quiet">quiet</h4>
(*Boolean*): If stdout and stderr should be printed to the terminal.
Defaults to `True`
<h4 id="yarn_install-repo_mapping">repo_mapping</h4>
(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>, 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`).
<h4 id="yarn_install-strict_visibility">strict_visibility</h4>
(*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`
<h4 id="yarn_install-symlink_node_modules">symlink_node_modules</h4>
(*Boolean*): Turn symlinking of node_modules on.
**Use of this feature is not recommended, as Bazel is removing `managed_directories`.
See https://github.com/bazelbuild/bazel/issues/15463
When False, the package manager will run in the external repository
created by this rule.
This requires that any files required for it to run should be listed in the
`data` attribute. These files would include things like patch files that are
read by a postinstall lifecycle hook such as the `patch-package` package uses.
`package.json` and the lock file are already specified in dedicated attributes
of this rule and do not need to be included in the `data`.
When True, we run the package manager (npm or yarn) with the working directory
set in your source tree, in the folder containing the package.json file.
The resulting `node_modules` folder in the source tree will be symlinked to the
external repository created by this rule.
This gives the user experience of running `bazel build` in a clean clone,
and the `node_modules` folder is created as if you had run `npm install` yourself.
It avoids installing the dependencies twice in a typical developer workflow, where you'd
need to `npm install` for tooling like formatters or editors, and then Bazel installs
a second copy in its external repository. This can save some time.
It also means you can patch the source files in the `node_modules` folder and these changes
will be reflected in subsequent Bazel executions.
WARNING: we suspect there are some hard-to-reproduce bugs when this feature is used,
because any corruption in the node_modules tree won't be corrected by Bazel.
When repairing this with `bazel clean --expunge` you'll also have to `rm -rf node_modules`
or else the next Bazel run will re-use the same corrupted `node_modules` folder by restoring
the symlink to it.
When using symlink_node_modules, we recommend also enabling Bazel's `managed_directories`
for the node_modules folder. This is documented in the
[workspace global](https://docs.bazel.build/versions/main/skylark/lib/globals.html#workspace)
Be sure to include the `node_modules` path in the `.bazelignore` file.
Using managed_directories will mean that
1. changes to files under `node_modules` are tracked by Bazel as if they were located
in the external repository folder, and
2. if the `node_modules` folder is deleted from the source tree, Bazel will re-run the
repository rule that creates it again on the next run.
Defaults to `False`
<h4 id="yarn_install-timeout">timeout</h4>
(*Integer*): Maximum duration of the package manager execution in seconds.
Defaults to `3600`
<h4 id="yarn_install-use_global_yarn_cache">use_global_yarn_cache</h4>
(*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 and using Yarn 1, this rule will pass `--mutex network` to yarn to ensure that
the global cache can be shared by parallelized yarn_install rules.
The True value has no effect on Yarn 2+ (Berry).
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`
<h4 id="yarn_install-yarn">yarn</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): The yarn.js entry point to execute
Defaults to `@yarn//:bin/yarn`
<h4 id="yarn_install-yarn_lock">yarn_lock</h4>
(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*)
## DeclarationInfo
**USAGE**
<pre>
DeclarationInfo(<a href="#DeclarationInfo-declarations">declarations</a>, <a href="#DeclarationInfo-transitive_declarations">transitive_declarations</a>, <a href="#DeclarationInfo-type_blocklisted_declarations">type_blocklisted_declarations</a>)
</pre>
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**
<h4 id="DeclarationInfo-declarations">declarations</h4>
A depset of typings files produced by this rule
<h4 id="DeclarationInfo-transitive_declarations">transitive_declarations</h4>
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.
<h4 id="DeclarationInfo-type_blocklisted_declarations">type_blocklisted_declarations</h4>
A depset of .d.ts files that we should not use to infer JSCompiler types (via tsickle)
## DirectoryFilePathInfo
**USAGE**
<pre>
DirectoryFilePathInfo(<a href="#DirectoryFilePathInfo-directory">directory</a>, <a href="#DirectoryFilePathInfo-path">path</a>)
</pre>
Joins a label pointing to a TreeArtifact with a path nested within that directory.
**FIELDS**
<h4 id="DirectoryFilePathInfo-directory">directory</h4>
a TreeArtifact (ctx.actions.declare_directory)
<h4 id="DirectoryFilePathInfo-path">path</h4>
path relative to the directory
## JSModuleInfo
**USAGE**
<pre>
JSModuleInfo(<a href="#JSModuleInfo-direct_sources">direct_sources</a>, <a href="#JSModuleInfo-sources">sources</a>)
</pre>
JavaScript files and sourcemaps.
**FIELDS**
<h4 id="JSModuleInfo-direct_sources">direct_sources</h4>
Depset of direct JavaScript files and sourcemaps
<h4 id="JSModuleInfo-sources">sources</h4>
Depset of direct and transitive JavaScript files and sourcemaps
## LinkablePackageInfo
**USAGE**
<pre>
LinkablePackageInfo(<a href="#LinkablePackageInfo-files">files</a>, <a href="#LinkablePackageInfo-package_name">package_name</a>, <a href="#LinkablePackageInfo-package_path">package_path</a>, <a href="#LinkablePackageInfo-path">path</a>)
</pre>
The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages
**FIELDS**
<h4 id="LinkablePackageInfo-files">files</h4>
Depset of files in this package (must all be contained within path)
<h4 id="LinkablePackageInfo-package_name">package_name</h4>
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.
<h4 id="LinkablePackageInfo-package_path">package_path</h4>
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.
<h4 id="LinkablePackageInfo-path">path</h4>
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`
## copy_to_bin
**USAGE**
<pre>
copy_to_bin(<a href="#copy_to_bin-name">name</a>, <a href="#copy_to_bin-srcs">srcs</a>, <a href="#copy_to_bin-kwargs">kwargs</a>)
</pre>
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**
<h4 id="copy_to_bin-name">name</h4>
Name of the rule.
<h4 id="copy_to_bin-srcs">srcs</h4>
A List of Labels. File(s) to to copy.
<h4 id="copy_to_bin-kwargs">kwargs</h4>
further keyword arguments, e.g. `visibility`
## declaration_info
**USAGE**
<pre>
declaration_info(<a href="#declaration_info-declarations">declarations</a>, <a href="#declaration_info-deps">deps</a>)
</pre>
Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps.
**PARAMETERS**
<h4 id="declaration_info-declarations">declarations</h4>
list of typings files
<h4 id="declaration_info-deps">deps</h4>
list of labels of dependencies where we should collect their DeclarationInfo to pass transitively
Defaults to `[]`
## js_library
**USAGE**
<pre>
js_library(<a href="#js_library-name">name</a>, <a href="#js_library-srcs">srcs</a>, <a href="#js_library-package_name">package_name</a>, <a href="#js_library-package_path">package_path</a>, <a href="#js_library-deps">deps</a>, <a href="#js_library-kwargs">kwargs</a>)
</pre>
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_npm` which 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. Also `pkg_npm` is intended to publish your code for external usage outside of Bazel, like
> by publishing to npm or artifactory, while `js_library` is 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:
```python
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
data = glob(["*.js"]),
)
```
### 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](#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](#linkablepackageinfo) for use with our "linker" that makes this package importable.
It also provides:
- [ExternalNpmPackageInfo](#externalnpmpackageinfo) to interop with rules that expect third-party npm packages.
- [JSModuleInfo](#jsmoduleinfo) so rules like bundlers can collect the transitive set of .js files
- [JSNamedModuleInfo](#jsnamedmoduleinfo) for rules that expect named AMD or `goog.module` format JS
[OutputGroupInfo]: https://docs.bazel.build/versions/main/skylark/lib/OutputGroupInfo.html
[DefaultInfo]: https://docs.bazel.build/versions/main/skylark/lib/DefaultInfo.html
[output_group]: https://docs.bazel.build/versions/main/be/general.html#filegroup.output_group
**PARAMETERS**
<h4 id="js_library-name">name</h4>
The name for the target
<h4 id="js_library-srcs">srcs</h4>
The list of files that comprise the package
Defaults to `[]`
<h4 id="js_library-package_name">package_name</h4>
The name it will be imported by.
Should match the "name" field in the package.json file if one is included.
Defaults to `None`
<h4 id="js_library-package_path">package_path</h4>
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 `""`
<h4 id="js_library-deps">deps</h4>
Other targets that provide JavaScript code
Defaults to `[]`
<h4 id="js_library-kwargs">kwargs</h4>
Other attributes
## js_module_info
**USAGE**
<pre>
js_module_info(<a href="#js_module_info-sources">sources</a>, <a href="#js_module_info-deps">deps</a>)
</pre>
Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps.
**PARAMETERS**
<h4 id="js_module_info-sources">sources</h4>
direct JS files
<h4 id="js_module_info-deps">deps</h4>
other targets that provide JSModuleInfo, typically from the deps attribute
Defaults to `[]`
## npm_package_bin
**USAGE**
<pre>
npm_package_bin(<a href="#npm_package_bin-tool">tool</a>, <a href="#npm_package_bin-package">package</a>, <a href="#npm_package_bin-package_bin">package_bin</a>, <a href="#npm_package_bin-data">data</a>, <a href="#npm_package_bin-env">env</a>, <a href="#npm_package_bin-outs">outs</a>, <a href="#npm_package_bin-args">args</a>, <a href="#npm_package_bin-stderr">stderr</a>, <a href="#npm_package_bin-stdout">stdout</a>, <a href="#npm_package_bin-exit_code_out">exit_code_out</a>,
<a href="#npm_package_bin-output_dir">output_dir</a>, <a href="#npm_package_bin-link_workspace_root">link_workspace_root</a>, <a href="#npm_package_bin-chdir">chdir</a>, <a href="#npm_package_bin-silent_on_success">silent_on_success</a>, <a href="#npm_package_bin-kwargs">kwargs</a>)
</pre>
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/main/skylark/macros.html#full-example
**PARAMETERS**
<h4 id="npm_package_bin-tool">tool</h4>
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`
<h4 id="npm_package_bin-package">package</h4>
an npm package whose binary to run, like "terser". Assumes your node_modules are installed in a workspace called "npm"
Defaults to `None`
<h4 id="npm_package_bin-package_bin">package_bin</h4>
the "bin" entry from `package` that should be run. By default package_bin is the same string as `package`
Defaults to `None`
<h4 id="npm_package_bin-data">data</h4>
similar to [genrule.srcs](https://docs.bazel.build/versions/main/be/general.html#genrule.srcs)
may also include targets that produce or reference npm packages which are needed by the tool
Defaults to `[]`
<h4 id="npm_package_bin-env">env</h4>
specifies additional environment variables to set when the target is executed. The values of environment variables
are subject to 'Make variable' substitution (see [args](#npm_package_bin-args)).
Defaults to `{}`
<h4 id="npm_package_bin-outs">outs</h4>
similar to [genrule.outs](https://docs.bazel.build/versions/main/be/general.html#genrule.outs)
Defaults to `[]`
<h4 id="npm_package_bin-args">args</h4>
Command-line arguments to the tool.
Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.
1. Predefined source/output path substitions is applied first:
See https://docs.bazel.build/versions/main/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/main/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/main/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/main/be/make-variables.html#custom_variables.
Defaults to `[]`
<h4 id="npm_package_bin-stderr">stderr</h4>
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`
<h4 id="npm_package_bin-stdout">stdout</h4>
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`
<h4 id="npm_package_bin-exit_code_out">exit_code_out</h4>
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`
<h4 id="npm_package_bin-output_dir">output_dir</h4>
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`
<h4 id="npm_package_bin-link_workspace_root">link_workspace_root</h4>
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`
<h4 id="npm_package_bin-chdir">chdir</h4>
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:
```python
_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`
<h4 id="npm_package_bin-silent_on_success">silent_on_success</h4>
produce no output on stdout nor stderr when program exits with status code 0.
This makes node binaries match the expected bazel paradigm.
Defaults to `False`
<h4 id="npm_package_bin-kwargs">kwargs</h4>
additional undocumented keyword args
## params_file
**USAGE**
<pre>
params_file(<a href="#params_file-name">name</a>, <a href="#params_file-out">out</a>, <a href="#params_file-args">args</a>, <a href="#params_file-data">data</a>, <a href="#params_file-newline">newline</a>, <a href="#params_file-kwargs">kwargs</a>)
</pre>
Generates a UTF-8 encoded params file from a list of arguments.
Handles variable substitutions for args.
**PARAMETERS**
<h4 id="params_file-name">name</h4>
Name of the rule.
<h4 id="params_file-out">out</h4>
Path of the output file, relative to this package.
<h4 id="params_file-args">args</h4>
Arguments to concatenate into a params file.
Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.
1. 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/main/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.
2. 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/main/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/main/be/make-variables.html#custom_variables.
Predefined genrule variables are not supported in this context.
Defaults to `[]`
<h4 id="params_file-data">data</h4>
Data for $(location) expansions in args.
Defaults to `[]`
<h4 id="params_file-newline">newline</h4>
Line endings to use. One of ["auto", "unix", "windows"].
"auto" for platform-determined
"unix" for LF
"windows" for CRLF
Defaults to `"auto"`
<h4 id="params_file-kwargs">kwargs</h4>