diff --git a/WORKSPACE b/WORKSPACE
index 07c4e6d68..efe761b10 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -187,23 +187,3 @@ buildifier_prebuilt_deps()
load("@buildifier_prebuilt//:defs.bzl", "buildifier_prebuilt_register_toolchains")
buildifier_prebuilt_register_toolchains()
-
-load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
-
-stardoc_repositories()
-
-load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
-
-rules_jvm_external_deps()
-
-load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
-
-rules_jvm_external_setup()
-
-load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")
-
-stardoc_external_deps()
-
-load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
-
-stardoc_pinned_maven_install()
diff --git a/docs/js_binary.md b/docs/js_binary.md
index c3908b1b1..5177a56bf 100644
--- a/docs/js_binary.md
+++ b/docs/js_binary.md
@@ -16,12 +16,13 @@ js_binary(
)
```
+
## js_binary
-js_binary(name, data, chdir, copy_data_to_bin, enable_runfiles, entry_point, env,
+js_binary(name, chdir, copy_data_to_bin, data, enable_runfiles, entry_point, env,
expected_exit_code, fixed_args, include_declarations, include_npm,
include_npm_linked_packages, include_transitive_sources, log_level, no_copy_to_bin,
node_options, node_toolchain, patch_node_fs, preserve_symlinks_main,
@@ -62,7 +63,8 @@ The following environment variables are made available to the Node.js runtime ba
* JS_BINARY__EXECROOT: the absolute path to the root of the execution root for the action; if in the sandbox, this path absolute path to the root of the execution root within the sandbox
This rules requires that Bazel was run with
-[`--enable_runfiles`](https://docs.bazel.build/versions/main/command-line-reference.html#flag--enable_runfiles).
+[`--enable_runfiles`](https://docs.bazel.build/versions/main/command-line-reference.html#flag--enable_runfiles).
+
**ATTRIBUTES**
@@ -70,25 +72,25 @@ This rules requires that Bazel was run with
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
-| data | Runtime dependencies of the program.
The transitive closure of the `data` dependencies will be available in the .runfiles folder for this binary/test.
NB: `data` files are copied to the Bazel output tree before being passed as inputs to runfiles. See `copy_data_to_bin` docstring for more info. | List of labels | optional | `[]` |
-| chdir | Working directory to run the binary or test in, relative to the workspace.
By default, `js_binary` runs in the root of the output tree.
To run in the directory containing the `js_binary` 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. In a `BUILD` file you could do something like this to point to the output path:
js_binary(
...
chdir = package_name(),
# ../.. segments to re-relative paths from the chdir back to workspace;
# add an additional 3 segments to account for running js_binary running
# in the root of the output tree
args = ["/".join([".."] * len(package_name().split("/"))) + "$(rootpath //path/to/some:file)"],
)
| String | optional | `""` |
-| copy_data_to_bin | When True, `data` files and the `entry_point` file are copied to the Bazel output tree before being passed as inputs to runfiles.
Defaults to True so that a `js_binary` with the default value is compatible with `js_run_binary` with `use_execroot_entry_point` set to True, the default there.
Setting this to False is more optimal in terms of inputs, but there is a yet unresolved issue of ESM imports skirting the node fs patches and escaping the sandbox: https://github.com/aspect-build/rules_js/issues/362. This is hit in some popular test runners such as mocha, which use native `import()` statements (https://github.com/aspect-build/rules_js/pull/353). When set to False, a program such as mocha that uses ESM imports may escape the execroot by following symlinks into the source tree. When set to True, such a program would escape the sandbox but will end up in the output tree where `node_modules` and other inputs required will be available. | Boolean | optional | `True` |
-| enable_runfiles | Whether runfiles are enabled in the current build configuration.
Typical usage of this rule is via a macro which automatically sets this attribute based on a `config_setting` rule. | Boolean | required | |
-| entry_point | The main script which is evaluated by node.js.
This is the module referenced by the `require.main` property in the runtime.
This must be a target that provides a single file or a `DirectoryPathInfo` from `@aspect_bazel_lib//lib::directory_path.bzl`.
See https://github.com/aspect-build/bazel-lib/blob/main/docs/directory_path.md for more info on creating a target that provides a `DirectoryPathInfo`. | Label | required | |
-| env | Environment variables of the action.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | Dictionary: String -> String | optional | `{}` |
-| expected_exit_code | The expected exit code.
Can be used to write tests that are expected to fail. | Integer | optional | `0` |
-| fixed_args | Fixed command line arguments to pass to the Node.js when this binary target is executed.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution.
Unlike the built-in `args`, which are only passed to the target when it is executed either by the `bazel run` command or as a test, `fixed_args` are baked into the generated launcher script so are always passed even when the binary target is run outside of Bazel directly from the launcher script.
`fixed_args` are passed before the ones specified in `args` and before ones that are specified on the `bazel run` or `bazel test` command line.
See https://bazel.build/reference/be/common-definitions#common-attributes-binaries for more info on the built-in `args` attribute. | List of strings | optional | `[]` |
-| include_declarations | When True, `declarations` and `transitive_declarations` from `JsInfo` providers in data targets are included in the runfiles of the target.
Defaults to false since declarations are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. | Boolean | optional | `False` |
-| include_npm | When True, npm is included in the runfiles of the target.
An npm binary is also added on the PATH so tools can spawn npm processes. This is a bash script on Linux and MacOS and a batch script on Windows.
A minimum of rules_nodejs version 5.7.0 is required which contains the Node.js toolchain changes to use npm. | Boolean | optional | `False` |
-| include_npm_linked_packages | When True, files in `npm_linked_packages` and `transitive_npm_linked_packages` from `JsInfo` providers in data targets are included in the runfiles of the target.
`transitive_files` from `NpmPackageStoreInfo` providers in data targets are also included in the runfiles of the target. | Boolean | optional | `True` |
-| include_transitive_sources | When True, `transitive_sources` from `JsInfo` providers in data targets are included in the runfiles of the target. | Boolean | optional | `True` |
-| log_level | Set the logging level.
Log from are written to stderr. They will be supressed on success when running as the tool of a js_run_binary when silent_on_success is True. In that case, they will be shown only on a build failure along with the stdout & stderr of the node tool being run.
Log levels: fatal, error, warn, info, debug | String | optional | `"error"` |
-| no_copy_to_bin | List of files to not copy to the Bazel output tree when `copy_data_to_bin` is True.
This is useful for exceptional cases where a `copy_to_bin` is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See `copy_data_to_bin` docstring for more info. | List of labels | optional | `[]` |
-| node_options | Options to pass to the node invocation on the command line.
https://nodejs.org/api/cli.html
These options are passed directly to the node invocation on the command line. Options passed here will take precendence over options passed via the NODE_OPTIONS environment variable. Options passed here are not added to the NODE_OPTIONS environment variable so will not be automatically picked up by child processes that inherit that enviroment variable. | List of strings | optional | `[]` |
-| node_toolchain | The Node.js toolchain to use for this target.
See https://bazelbuild.github.io/rules_nodejs/Toolchains.html
Typically this is left unset so that Bazel automatically selects the right Node.js toolchain for the target platform. See https://bazel.build/extending/toolchains#toolchain-resolution for more information. | Label | optional | `None` |
-| patch_node_fs | Patch the to Node.js `fs` API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, `js_binary` patches the Node.js sync and async `fs` API functions `lstat`, `readlink`, `realpath`, `readdir` and `opendir` so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. | Boolean | optional | `True` |
-| preserve_symlinks_main | When True, the --preserve-symlinks-main flag is passed to node.
This prevents node from following an ESM entry script out of runfiles and the sandbox. This can happen for `.mjs` ESM entry points where the fs node patches, which guard the runfiles and sandbox, are not applied. See https://github.com/aspect-build/rules_js/issues/362 for more information. Once #362 is resolved, the default for this attribute can be set to False.
This flag was added in Node.js v10.2.0 (released 2018-05-23). If your node toolchain is configured to use a Node.js version older than this you'll need to set this attribute to False.
See https://nodejs.org/api/cli.html#--preserve-symlinks-main for more information. | Boolean | optional | `True` |
-| unresolved_symlinks_enabled | Whether unresolved symlinks are enabled in the current build configuration.
These are enabled with the `--allow_unresolved_symlinks` flag (named `--experimental_allow_unresolved_symlinks in Bazel versions prior to 7.0).
Typical usage of this rule is via a macro which automatically sets this attribute based on a `config_setting` rule. See /js/private/BUILD.bazel in rules_js for an example. | Boolean | optional | `False` |
+| chdir | Working directory to run the binary or test in, relative to the workspace.
By default, js_binary runs in the root of the output tree.
To run in the directory containing the js_binary 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. In a BUILD file you could do something like this to point to the output path:
python js_binary( ... chdir = package_name(), # ../.. segments to re-relative paths from the chdir back to workspace; # add an additional 3 segments to account for running js_binary running # in the root of the output tree args = ["/".join([".."] * len(package_name().split("/"))) + "$(rootpath //path/to/some:file)"], )
| String | optional | "" |
+| copy_data_to_bin | When True, data files and the entry_point file are copied to the Bazel output tree before being passed as inputs to runfiles.
Defaults to True so that a js_binary with the default value is compatible with js_run_binary with use_execroot_entry_point set to True, the default there.
Setting this to False is more optimal in terms of inputs, but there is a yet unresolved issue of ESM imports skirting the node fs patches and escaping the sandbox: https://github.com/aspect-build/rules_js/issues/362. This is hit in some popular test runners such as mocha, which use native import() statements (https://github.com/aspect-build/rules_js/pull/353). When set to False, a program such as mocha that uses ESM imports may escape the execroot by following symlinks into the source tree. When set to True, such a program would escape the sandbox but will end up in the output tree where node_modules and other inputs required will be available. | Boolean | optional | True |
+| data | Runtime dependencies of the program.
The transitive closure of the data dependencies will be available in the .runfiles folder for this binary/test.
NB: data files are copied to the Bazel output tree before being passed as inputs to runfiles. See copy_data_to_bin docstring for more info. | List of labels | optional | [] |
+| enable_runfiles | Whether runfiles are enabled in the current build configuration.
Typical usage of this rule is via a macro which automatically sets this attribute based on a config_setting rule. | Boolean | required | |
+| entry_point | The main script which is evaluated by node.js.
This is the module referenced by the require.main property in the runtime.
This must be a target that provides a single file or a DirectoryPathInfo from @aspect_bazel_lib//lib::directory_path.bzl.
See https://github.com/aspect-build/bazel-lib/blob/main/docs/directory_path.md for more info on creating a target that provides a DirectoryPathInfo. | Label | required | |
+| env | Environment variables of the action.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | Dictionary: String -> String | optional | {} |
+| expected_exit_code | The expected exit code.
Can be used to write tests that are expected to fail. | Integer | optional | 0 |
+| fixed_args | Fixed command line arguments to pass to the Node.js when this binary target is executed.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution.
Unlike the built-in args, which are only passed to the target when it is executed either by the bazel run command or as a test, fixed_args are baked into the generated launcher script so are always passed even when the binary target is run outside of Bazel directly from the launcher script.
fixed_args are passed before the ones specified in args and before ones that are specified on the bazel run or bazel test command line.
See https://bazel.build/reference/be/common-definitions#common-attributes-binaries for more info on the built-in args attribute. | List of strings | optional | [] |
+| include_declarations | When True, declarations and transitive_declarations from JsInfo providers in data targets are included in the runfiles of the target.
Defaults to false since declarations are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. | Boolean | optional | False |
+| include_npm | When True, npm is included in the runfiles of the target.
An npm binary is also added on the PATH so tools can spawn npm processes. This is a bash script on Linux and MacOS and a batch script on Windows.
A minimum of rules_nodejs version 5.7.0 is required which contains the Node.js toolchain changes to use npm. | Boolean | optional | False |
+| include_npm_linked_packages | When True, files in npm_linked_packages and transitive_npm_linked_packages from JsInfo providers in data targets are included in the runfiles of the target.
transitive_files from NpmPackageStoreInfo providers in data targets are also included in the runfiles of the target. | Boolean | optional | True |
+| include_transitive_sources | When True, transitive_sources from JsInfo providers in data targets are included in the runfiles of the target. | Boolean | optional | True |
+| log_level | Set the logging level.
Log from are written to stderr. They will be supressed on success when running as the tool of a js_run_binary when silent_on_success is True. In that case, they will be shown only on a build failure along with the stdout & stderr of the node tool being run.
Log levels: fatal, error, warn, info, debug | String | optional | "error" |
+| no_copy_to_bin | List of files to not copy to the Bazel output tree when copy_data_to_bin is True.
This is useful for exceptional cases where a copy_to_bin is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See copy_data_to_bin docstring for more info. | List of labels | optional | [] |
+| node_options | Options to pass to the node invocation on the command line.
https://nodejs.org/api/cli.html
These options are passed directly to the node invocation on the command line. Options passed here will take precendence over options passed via the NODE_OPTIONS environment variable. Options passed here are not added to the NODE_OPTIONS environment variable so will not be automatically picked up by child processes that inherit that enviroment variable. | List of strings | optional | [] |
+| node_toolchain | The Node.js toolchain to use for this target.
See https://bazelbuild.github.io/rules_nodejs/Toolchains.html
Typically this is left unset so that Bazel automatically selects the right Node.js toolchain for the target platform. See https://bazel.build/extending/toolchains#toolchain-resolution for more information. | Label | optional | None |
+| patch_node_fs | Patch the to Node.js fs API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, js_binary patches the Node.js sync and async fs API functions lstat, readlink, realpath, readdir and opendir so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. | Boolean | optional | True |
+| preserve_symlinks_main | When True, the --preserve-symlinks-main flag is passed to node.
This prevents node from following an ESM entry script out of runfiles and the sandbox. This can happen for .mjs ESM entry points where the fs node patches, which guard the runfiles and sandbox, are not applied. See https://github.com/aspect-build/rules_js/issues/362 for more information. Once #362 is resolved, the default for this attribute can be set to False.
This flag was added in Node.js v10.2.0 (released 2018-05-23). If your node toolchain is configured to use a Node.js version older than this you'll need to set this attribute to False.
See https://nodejs.org/api/cli.html#--preserve-symlinks-main for more information. | Boolean | optional | True |
+| unresolved_symlinks_enabled | Whether unresolved symlinks are enabled in the current build configuration.
These are enabled with the --allow_unresolved_symlinks flag (named --experimental_allow_unresolved_symlinks in Bazel versions prior to 7.0).
Typical usage of this rule is via a macro which automatically sets this attribute based on a config_setting rule. See /js/private/BUILD.bazel in rules_js for an example. | Boolean | optional | False |
@@ -96,7 +98,7 @@ This rules requires that Bazel was run with
## js_test
-js_test(name, data, chdir, copy_data_to_bin, enable_runfiles, entry_point, env, expected_exit_code,
+js_test(name, chdir, copy_data_to_bin, data, enable_runfiles, entry_point, env, expected_exit_code,
fixed_args, include_declarations, include_npm, include_npm_linked_packages,
include_transitive_sources, log_level, no_copy_to_bin, node_options, node_toolchain,
patch_node_fs, preserve_symlinks_main, unresolved_symlinks_enabled)
@@ -130,25 +132,25 @@ the contract between Bazel and a test runner.
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
-| data | Runtime dependencies of the program.
The transitive closure of the `data` dependencies will be available in the .runfiles folder for this binary/test.
NB: `data` files are copied to the Bazel output tree before being passed as inputs to runfiles. See `copy_data_to_bin` docstring for more info. | List of labels | optional | `[]` |
-| chdir | Working directory to run the binary or test in, relative to the workspace.
By default, `js_binary` runs in the root of the output tree.
To run in the directory containing the `js_binary` 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. In a `BUILD` file you could do something like this to point to the output path:
js_binary(
...
chdir = package_name(),
# ../.. segments to re-relative paths from the chdir back to workspace;
# add an additional 3 segments to account for running js_binary running
# in the root of the output tree
args = ["/".join([".."] * len(package_name().split("/"))) + "$(rootpath //path/to/some:file)"],
)
| String | optional | `""` |
-| copy_data_to_bin | When True, `data` files and the `entry_point` file are copied to the Bazel output tree before being passed as inputs to runfiles.
Defaults to True so that a `js_binary` with the default value is compatible with `js_run_binary` with `use_execroot_entry_point` set to True, the default there.
Setting this to False is more optimal in terms of inputs, but there is a yet unresolved issue of ESM imports skirting the node fs patches and escaping the sandbox: https://github.com/aspect-build/rules_js/issues/362. This is hit in some popular test runners such as mocha, which use native `import()` statements (https://github.com/aspect-build/rules_js/pull/353). When set to False, a program such as mocha that uses ESM imports may escape the execroot by following symlinks into the source tree. When set to True, such a program would escape the sandbox but will end up in the output tree where `node_modules` and other inputs required will be available. | Boolean | optional | `True` |
-| enable_runfiles | Whether runfiles are enabled in the current build configuration.
Typical usage of this rule is via a macro which automatically sets this attribute based on a `config_setting` rule. | Boolean | required | |
-| entry_point | The main script which is evaluated by node.js.
This is the module referenced by the `require.main` property in the runtime.
This must be a target that provides a single file or a `DirectoryPathInfo` from `@aspect_bazel_lib//lib::directory_path.bzl`.
See https://github.com/aspect-build/bazel-lib/blob/main/docs/directory_path.md for more info on creating a target that provides a `DirectoryPathInfo`. | Label | required | |
-| env | Environment variables of the action.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | Dictionary: String -> String | optional | `{}` |
-| expected_exit_code | The expected exit code.
Can be used to write tests that are expected to fail. | Integer | optional | `0` |
-| fixed_args | Fixed command line arguments to pass to the Node.js when this binary target is executed.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution.
Unlike the built-in `args`, which are only passed to the target when it is executed either by the `bazel run` command or as a test, `fixed_args` are baked into the generated launcher script so are always passed even when the binary target is run outside of Bazel directly from the launcher script.
`fixed_args` are passed before the ones specified in `args` and before ones that are specified on the `bazel run` or `bazel test` command line.
See https://bazel.build/reference/be/common-definitions#common-attributes-binaries for more info on the built-in `args` attribute. | List of strings | optional | `[]` |
-| include_declarations | When True, `declarations` and `transitive_declarations` from `JsInfo` providers in data targets are included in the runfiles of the target.
Defaults to false since declarations are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. | Boolean | optional | `False` |
-| include_npm | When True, npm is included in the runfiles of the target.
An npm binary is also added on the PATH so tools can spawn npm processes. This is a bash script on Linux and MacOS and a batch script on Windows.
A minimum of rules_nodejs version 5.7.0 is required which contains the Node.js toolchain changes to use npm. | Boolean | optional | `False` |
-| include_npm_linked_packages | When True, files in `npm_linked_packages` and `transitive_npm_linked_packages` from `JsInfo` providers in data targets are included in the runfiles of the target.
`transitive_files` from `NpmPackageStoreInfo` providers in data targets are also included in the runfiles of the target. | Boolean | optional | `True` |
-| include_transitive_sources | When True, `transitive_sources` from `JsInfo` providers in data targets are included in the runfiles of the target. | Boolean | optional | `True` |
-| log_level | Set the logging level.
Log from are written to stderr. They will be supressed on success when running as the tool of a js_run_binary when silent_on_success is True. In that case, they will be shown only on a build failure along with the stdout & stderr of the node tool being run.
Log levels: fatal, error, warn, info, debug | String | optional | `"error"` |
-| no_copy_to_bin | List of files to not copy to the Bazel output tree when `copy_data_to_bin` is True.
This is useful for exceptional cases where a `copy_to_bin` is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See `copy_data_to_bin` docstring for more info. | List of labels | optional | `[]` |
-| node_options | Options to pass to the node invocation on the command line.
https://nodejs.org/api/cli.html
These options are passed directly to the node invocation on the command line. Options passed here will take precendence over options passed via the NODE_OPTIONS environment variable. Options passed here are not added to the NODE_OPTIONS environment variable so will not be automatically picked up by child processes that inherit that enviroment variable. | List of strings | optional | `[]` |
-| node_toolchain | The Node.js toolchain to use for this target.
See https://bazelbuild.github.io/rules_nodejs/Toolchains.html
Typically this is left unset so that Bazel automatically selects the right Node.js toolchain for the target platform. See https://bazel.build/extending/toolchains#toolchain-resolution for more information. | Label | optional | `None` |
-| patch_node_fs | Patch the to Node.js `fs` API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, `js_binary` patches the Node.js sync and async `fs` API functions `lstat`, `readlink`, `realpath`, `readdir` and `opendir` so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. | Boolean | optional | `True` |
-| preserve_symlinks_main | When True, the --preserve-symlinks-main flag is passed to node.
This prevents node from following an ESM entry script out of runfiles and the sandbox. This can happen for `.mjs` ESM entry points where the fs node patches, which guard the runfiles and sandbox, are not applied. See https://github.com/aspect-build/rules_js/issues/362 for more information. Once #362 is resolved, the default for this attribute can be set to False.
This flag was added in Node.js v10.2.0 (released 2018-05-23). If your node toolchain is configured to use a Node.js version older than this you'll need to set this attribute to False.
See https://nodejs.org/api/cli.html#--preserve-symlinks-main for more information. | Boolean | optional | `True` |
-| unresolved_symlinks_enabled | Whether unresolved symlinks are enabled in the current build configuration.
These are enabled with the `--allow_unresolved_symlinks` flag (named `--experimental_allow_unresolved_symlinks in Bazel versions prior to 7.0).
Typical usage of this rule is via a macro which automatically sets this attribute based on a `config_setting` rule. See /js/private/BUILD.bazel in rules_js for an example. | Boolean | optional | `False` |
+| chdir | Working directory to run the binary or test in, relative to the workspace.
By default, js_binary runs in the root of the output tree.
To run in the directory containing the js_binary 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. In a BUILD file you could do something like this to point to the output path:
python js_binary( ... chdir = package_name(), # ../.. segments to re-relative paths from the chdir back to workspace; # add an additional 3 segments to account for running js_binary running # in the root of the output tree args = ["/".join([".."] * len(package_name().split("/"))) + "$(rootpath //path/to/some:file)"], )
| String | optional | "" |
+| copy_data_to_bin | When True, data files and the entry_point file are copied to the Bazel output tree before being passed as inputs to runfiles.
Defaults to True so that a js_binary with the default value is compatible with js_run_binary with use_execroot_entry_point set to True, the default there.
Setting this to False is more optimal in terms of inputs, but there is a yet unresolved issue of ESM imports skirting the node fs patches and escaping the sandbox: https://github.com/aspect-build/rules_js/issues/362. This is hit in some popular test runners such as mocha, which use native import() statements (https://github.com/aspect-build/rules_js/pull/353). When set to False, a program such as mocha that uses ESM imports may escape the execroot by following symlinks into the source tree. When set to True, such a program would escape the sandbox but will end up in the output tree where node_modules and other inputs required will be available. | Boolean | optional | True |
+| data | Runtime dependencies of the program.
The transitive closure of the data dependencies will be available in the .runfiles folder for this binary/test.
NB: data files are copied to the Bazel output tree before being passed as inputs to runfiles. See copy_data_to_bin docstring for more info. | List of labels | optional | [] |
+| enable_runfiles | Whether runfiles are enabled in the current build configuration.
Typical usage of this rule is via a macro which automatically sets this attribute based on a config_setting rule. | Boolean | required | |
+| entry_point | The main script which is evaluated by node.js.
This is the module referenced by the require.main property in the runtime.
This must be a target that provides a single file or a DirectoryPathInfo from @aspect_bazel_lib//lib::directory_path.bzl.
See https://github.com/aspect-build/bazel-lib/blob/main/docs/directory_path.md for more info on creating a target that provides a DirectoryPathInfo. | Label | required | |
+| env | Environment variables of the action.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | Dictionary: String -> String | optional | {} |
+| expected_exit_code | The expected exit code.
Can be used to write tests that are expected to fail. | Integer | optional | 0 |
+| fixed_args | Fixed command line arguments to pass to the Node.js when this binary target is executed.
Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution.
Unlike the built-in args, which are only passed to the target when it is executed either by the bazel run command or as a test, fixed_args are baked into the generated launcher script so are always passed even when the binary target is run outside of Bazel directly from the launcher script.
fixed_args are passed before the ones specified in args and before ones that are specified on the bazel run or bazel test command line.
See https://bazel.build/reference/be/common-definitions#common-attributes-binaries for more info on the built-in args attribute. | List of strings | optional | [] |
+| include_declarations | When True, declarations and transitive_declarations from JsInfo providers in data targets are included in the runfiles of the target.
Defaults to false since declarations are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. | Boolean | optional | False |
+| include_npm | When True, npm is included in the runfiles of the target.
An npm binary is also added on the PATH so tools can spawn npm processes. This is a bash script on Linux and MacOS and a batch script on Windows.
A minimum of rules_nodejs version 5.7.0 is required which contains the Node.js toolchain changes to use npm. | Boolean | optional | False |
+| include_npm_linked_packages | When True, files in npm_linked_packages and transitive_npm_linked_packages from JsInfo providers in data targets are included in the runfiles of the target.
transitive_files from NpmPackageStoreInfo providers in data targets are also included in the runfiles of the target. | Boolean | optional | True |
+| include_transitive_sources | When True, transitive_sources from JsInfo providers in data targets are included in the runfiles of the target. | Boolean | optional | True |
+| log_level | Set the logging level.
Log from are written to stderr. They will be supressed on success when running as the tool of a js_run_binary when silent_on_success is True. In that case, they will be shown only on a build failure along with the stdout & stderr of the node tool being run.
Log levels: fatal, error, warn, info, debug | String | optional | "error" |
+| no_copy_to_bin | List of files to not copy to the Bazel output tree when copy_data_to_bin is True.
This is useful for exceptional cases where a copy_to_bin is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See copy_data_to_bin docstring for more info. | List of labels | optional | [] |
+| node_options | Options to pass to the node invocation on the command line.
https://nodejs.org/api/cli.html
These options are passed directly to the node invocation on the command line. Options passed here will take precendence over options passed via the NODE_OPTIONS environment variable. Options passed here are not added to the NODE_OPTIONS environment variable so will not be automatically picked up by child processes that inherit that enviroment variable. | List of strings | optional | [] |
+| node_toolchain | The Node.js toolchain to use for this target.
See https://bazelbuild.github.io/rules_nodejs/Toolchains.html
Typically this is left unset so that Bazel automatically selects the right Node.js toolchain for the target platform. See https://bazel.build/extending/toolchains#toolchain-resolution for more information. | Label | optional | None |
+| patch_node_fs | Patch the to Node.js fs API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, js_binary patches the Node.js sync and async fs API functions lstat, readlink, realpath, readdir and opendir so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. | Boolean | optional | True |
+| preserve_symlinks_main | When True, the --preserve-symlinks-main flag is passed to node.
This prevents node from following an ESM entry script out of runfiles and the sandbox. This can happen for .mjs ESM entry points where the fs node patches, which guard the runfiles and sandbox, are not applied. See https://github.com/aspect-build/rules_js/issues/362 for more information. Once #362 is resolved, the default for this attribute can be set to False.
This flag was added in Node.js v10.2.0 (released 2018-05-23). If your node toolchain is configured to use a Node.js version older than this you'll need to set this attribute to False.
See https://nodejs.org/api/cli.html#--preserve-symlinks-main for more information. | Boolean | optional | True |
+| unresolved_symlinks_enabled | Whether unresolved symlinks are enabled in the current build configuration.
These are enabled with the --allow_unresolved_symlinks flag (named --experimental_allow_unresolved_symlinks in Bazel versions prior to 7.0).
Typical usage of this rule is via a macro which automatically sets this attribute based on a config_setting rule. See /js/private/BUILD.bazel in rules_js for an example. | Boolean | optional | False |
@@ -169,8 +171,8 @@ js_binary_lib.create_launcher(ctxctx | -
| none |
| log_prefix_rule_set | -
| none |
| log_prefix_rule | -
| none |
-| fixed_args | -
| `[]` |
-| fixed_env | -
| `{}` |
+| fixed_args | -
| [] |
+| fixed_env | -
| {} |
diff --git a/docs/js_filegroup.md b/docs/js_filegroup.md
index 69aa99322..dff5a631b 100644
--- a/docs/js_filegroup.md
+++ b/docs/js_filegroup.md
@@ -7,23 +7,24 @@ Helper rule to gather files from JsInfo providers of targets and provide them as
## js_filegroup
-js_filegroup(name, srcs, include_declarations, include_npm_linked_packages,
- include_transitive_sources)
+js_filegroup(name, include_declarations, include_npm_linked_packages, include_transitive_sources,
+ srcs)
Gathers files from the JsInfo providers from targets in srcs and provides them as default outputs.
This helper rule is used by the `js_run_binary` macro.
+
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
-| srcs | List of targets to gather files from. | List of labels | optional | `[]` |
-| include_declarations | When True, `declarations` and `transitive_declarations` from `JsInfo` providers in srcs targets are included in the default outputs of the target.
Defaults to false since declarations are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. | Boolean | optional | `False` |
-| include_npm_linked_packages | When True, files in `npm_linked_packages` and `transitive_npm_linked_packages` from `JsInfo` providers in srcs targets are included in the default outputs of the target.
`transitive_files` from `NpmPackageStoreInfo` providers in data targets are also included in the default outputs of the target. | Boolean | optional | `True` |
-| include_transitive_sources | When True, `transitive_sources` from `JsInfo` providers in `srcs` targets are included in the default outputs of the target. | Boolean | optional | `True` |
+| include_declarations | When True, declarations and transitive_declarations from JsInfo providers in srcs targets are included in the default outputs of the target.
Defaults to false since declarations are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. | Boolean | optional | False |
+| include_npm_linked_packages | When True, files in npm_linked_packages and transitive_npm_linked_packages from JsInfo providers in srcs targets are included in the default outputs of the target.
transitive_files from NpmPackageStoreInfo providers in data targets are also included in the default outputs of the target. | Boolean | optional | True |
+| include_transitive_sources | When True, transitive_sources from JsInfo providers in srcs targets are included in the default outputs of the target. | Boolean | optional | True |
+| srcs | List of targets to gather files from. | List of labels | optional | [] |
diff --git a/docs/js_image_layer.md b/docs/js_image_layer.md
index f3fba2566..370981c1b 100644
--- a/docs/js_image_layer.md
+++ b/docs/js_image_layer.md
@@ -14,6 +14,7 @@ js_image_layer(
)
```
+
## js_image_layer
@@ -24,16 +25,16 @@ js_image_layer(name, name | A unique name for this target. | Name | required | |
| binary | Label to an js_binary target | Label | required | |
-| compression | Compression algorithm. Can be one of `gzip`, `none`. | String | optional | `"gzip"` |
-| platform | Platform to transition. | Label | optional | `None` |
-| root | Path where the files from js_binary will reside in. eg: /apps/app1 or /app | String | optional | `""` |
+| compression | Compression algorithm. Can be one of gzip, none. | String | optional | "gzip" |
+| platform | Platform to transition. | Label | optional | None |
+| root | Path where the files from js_binary will reside in. eg: /apps/app1 or /app | String | optional | "" |
diff --git a/docs/js_library.md b/docs/js_library.md
index 506aa4ffa..13d09c0fd 100644
--- a/docs/js_library.md
+++ b/docs/js_library.md
@@ -24,12 +24,13 @@ js_library(
| This is similar to [`py_library`](https://docs.bazel.build/versions/main/be/python.html#py_library) which depends on
| Python sources and provides a `PyInfo`.
+
## js_library
-js_library(name, deps, srcs, data, copy_data_to_bin, declarations, no_copy_to_bin)
+js_library(name, copy_data_to_bin, data, declarations, deps, no_copy_to_bin, srcs)
A library of JavaScript sources. Provides JsInfo, the primary provider used in rules_js
@@ -53,12 +54,12 @@ for more context on why we do this.
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
-| deps | Dependencies of this target.
This may include other js_library targets or other targets that provide JsInfo
The transitive npm dependencies, transitive sources & runfiles of targets in the `deps` attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which is output by or has a runtime dependency on this target.
If this list contains linked npm packages, npm package store targets or other targets that provide `JsInfo`, `NpmPackageStoreInfo` providers are gathered from `JsInfo`. This is done directly from the `npm_package_store_deps` field of these. For linked npm package targets, the underlying `npm_package_store` target(s) that back the links is used. Gathered `NpmPackageStoreInfo` providers are propagated to the direct dependencies of downstream linked `npm_package` targets.
NB: Linked npm package targets that are "dev" dependencies do not forward their underlying `npm_package_store` target(s) through `npm_package_store_deps` and will therefore not be propagated to the direct dependencies of downstream linked `npm_package` targets. npm packages that come in from `npm_translate_lock` are considered "dev" dependencies if they are have `dev: true` set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all `package.json` files within the pnpm workspace. This behavior is intentional to mimic how `devDependencies` work in published npm packages. | List of labels | optional | `[]` |
-| srcs | Source files that are included in this library.
This includes all your checked-in code and any generated source files.
The transitive npm dependencies, transitive sources & runfiles of targets in the `srcs` attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which is output by or has a runtime dependency on this target.
Source files that are JSON files, declaration files or directory artifacts will be automatically provided as "declarations" available to downstream rules for type checking. To explicitly provide source files as "declarations" available to downstream rules for type checking that do not match these criteria, move those files to the `declarations` attribute instead. | List of labels | optional | `[]` |
-| data | Runtime dependencies to include in binaries/tests that depend on this target.
The transitive npm dependencies, transitive sources, default outputs and runfiles of targets in the `data` attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which has a runtime dependency on this target.
If this list contains linked npm packages, npm package store targets or other targets that provide `JsInfo`, `NpmPackageStoreInfo` providers are gathered from `JsInfo`. This is done directly from the `npm_package_store_deps` field of these. For linked npm package targets, the underlying `npm_package_store` target(s) that back the links is used. Gathered `NpmPackageStoreInfo` providers are propagated to the direct dependencies of downstream linked `npm_package` targets.
NB: Linked npm package targets that are "dev" dependencies do not forward their underlying `npm_package_store` target(s) through `npm_package_store_deps` and will therefore not be propagated to the direct dependencies of downstream linked `npm_package` targets. npm packages that come in from `npm_translate_lock` are considered "dev" dependencies if they are have `dev: true` set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all `package.json` files within the pnpm workspace. This behavior is intentional to mimic how `devDependencies` work in published npm packages. | List of labels | optional | `[]` |
-| copy_data_to_bin | When True, `data` files are copied to the Bazel output tree before being passed as inputs to runfiles. | Boolean | optional | `True` |
-| declarations | Same as `srcs` except all files are also provided as "declarations" available to downstream rules for type checking.
For example, a js_library with only `.js` files that are intended to be imported as `.js` files by downstream type checking rules such as `ts_project` would list those files in `declarations`:
js_library(
name = "js_lib",
declarations = ["index.js"],
)
| List of labels | optional | `[]` |
-| no_copy_to_bin | List of files to not copy to the Bazel output tree when `copy_data_to_bin` is True.
This is useful for exceptional cases where a `copy_to_bin` is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See `copy_data_to_bin` docstring for more info. | List of labels | optional | `[]` |
+| copy_data_to_bin | When True, data files are copied to the Bazel output tree before being passed as inputs to runfiles. | Boolean | optional | True |
+| data | Runtime dependencies to include in binaries/tests that depend on this target.
The transitive npm dependencies, transitive sources, default outputs and runfiles of targets in the data attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which has a runtime dependency on this target.
If this list contains linked npm packages, npm package store targets or other targets that provide JsInfo, NpmPackageStoreInfo providers are gathered from JsInfo. This is done directly from the npm_package_store_deps field of these. For linked npm package targets, the underlying npm_package_store target(s) that back the links is used. Gathered NpmPackageStoreInfo providers are propagated to the direct dependencies of downstream linked npm_package targets.
NB: Linked npm package targets that are "dev" dependencies do not forward their underlying npm_package_store target(s) through npm_package_store_deps and will therefore not be propagated to the direct dependencies of downstream linked npm_package targets. npm packages that come in from npm_translate_lock are considered "dev" dependencies if they are have dev: true set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all package.json files within the pnpm workspace. This behavior is intentional to mimic how devDependencies work in published npm packages. | List of labels | optional | [] |
+| declarations | Same as srcs except all files are also provided as "declarations" available to downstream rules for type checking.
For example, a js_library with only .js files that are intended to be imported as .js files by downstream type checking rules such as ts_project would list those files in declarations:
js_library( name = "js_lib", declarations = ["index.js"], )
| List of labels | optional | [] |
+| deps | Dependencies of this target.
This may include other js_library targets or other targets that provide JsInfo
The transitive npm dependencies, transitive sources & runfiles of targets in the deps attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which is output by or has a runtime dependency on this target.
If this list contains linked npm packages, npm package store targets or other targets that provide JsInfo, NpmPackageStoreInfo providers are gathered from JsInfo. This is done directly from the npm_package_store_deps field of these. For linked npm package targets, the underlying npm_package_store target(s) that back the links is used. Gathered NpmPackageStoreInfo providers are propagated to the direct dependencies of downstream linked npm_package targets.
NB: Linked npm package targets that are "dev" dependencies do not forward their underlying npm_package_store target(s) through npm_package_store_deps and will therefore not be propagated to the direct dependencies of downstream linked npm_package targets. npm packages that come in from npm_translate_lock are considered "dev" dependencies if they are have dev: true set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all package.json files within the pnpm workspace. This behavior is intentional to mimic how devDependencies work in published npm packages. | List of labels | optional | [] |
+| no_copy_to_bin | List of files to not copy to the Bazel output tree when copy_data_to_bin is True.
This is useful for exceptional cases where a copy_to_bin is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See copy_data_to_bin docstring for more info. | List of labels | optional | [] |
+| srcs | Source files that are included in this library.
This includes all your checked-in code and any generated source files.
The transitive npm dependencies, transitive sources & runfiles of targets in the srcs attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which is output by or has a runtime dependency on this target.
Source files that are JSON files, declaration files or directory artifacts will be automatically provided as "declarations" available to downstream rules for type checking. To explicitly provide source files as "declarations" available to downstream rules for type checking that do not match these criteria, move those files to the declarations attribute instead. | List of labels | optional | [] |
diff --git a/docs/js_run_binary.md b/docs/js_run_binary.md
index cde424399..28d699d99 100644
--- a/docs/js_run_binary.md
+++ b/docs/js_run_binary.md
@@ -11,6 +11,7 @@ Load this with,
load("@aspect_rules_js//js:defs.bzl", "js_run_binary")
```
+
## js_run_binary
@@ -48,29 +49,29 @@ The following environment variables are made available to the Node.js runtime ba
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | Target name | none |
-| tool | The tool to run in the action.
Should be a `js_binary` rule. Use Aspect bazel-lib's run_binary (https://github.com/aspect-build/bazel-lib/blob/main/lib/run_binary.bzl) for other *_binary rule types. | none |
-| env | Environment variables of the action.
Subject to `$(location)` and make variable expansion. | `{}` |
-| srcs | Additional inputs of the action.
These labels are available for `$(location)` expansion in `args` and `env`. | `[]` |
-| outs | Output files generated by the action.
These labels are available for `$(location)` expansion in `args` and `env`. | `[]` |
-| out_dirs | Output directories generated by the action.
These labels are _not_ available for `$(location)` expansion in `args` and `env` since they are not pre-declared labels created via attr.output_list(). Output directories are declared instead by `ctx.actions.declare_directory`. | `[]` |
-| args | Command line arguments of the binary.
Subject to `$(location)` and make variable expansion. | `[]` |
-| chdir | Working directory to run the build action in.
This overrides the chdir value if set on the `js_binary` tool target.
By default, `js_binary` tools run in the root of the output tree. For more context on why, please read the aspect_rules_js README https://github.com/aspect-build/rules_js/tree/dbb5af0d2a9a2bb50e4cf4a96dbc582b27567155#running-nodejs-programs.
To run in the directory containing the js_run_binary in the output tree, 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. | `None` |
-| stdout | set to capture the stdout of the binary to a file, which can later be used as an input to another target subject to the same semantics as `outs` | `None` |
-| stderr | set to capture the stderr of the binary to a file, which can later be used as an input to another target subject to the same semantics as `outs` | `None` |
-| exit_code_out | set to capture the exit code of the binary to a file, which can later be used as an input to another target subject to the same semantics as `outs`. Note that setting this will force the binary to exit 0.
If the binary creates outputs and these are declared, they must still be created | `None` |
-| silent_on_success | produce no output on stdout nor stderr when program exits with status code 0.
This makes node binaries match the expected bazel paradigm. | `True` |
-| use_execroot_entry_point | Use the `entry_point` script of the `js_binary` `tool` that is in the execroot output tree instead of the copy that is in runfiles.
Runfiles of `tool` are all hoisted to `srcs` of the underlying `run_binary` so they are included as execroot inputs to the action.
Using the entry point script that is in the execroot output tree means that there will be no conflicting runfiles `node_modules` in the node_modules resolution path which can confuse npm packages such as next and react that don't like being resolved in multiple node_modules trees. This more closely emulates the environment that tools such as Next.js see when they are run outside of Bazel.
When True, the `js_binary` tool must have `copy_data_to_bin` set to True (the default) so that all data files needed by the binary are available in the execroot output tree. This requirement can be turned off with by setting `allow_execroot_entry_point_with_no_copy_data_to_bin` to True. | `True` |
-| copy_srcs_to_bin | When True, all srcs files are copied to the output tree that are not already there. | `True` |
-| include_transitive_sources | see `js_filegroup` documentation | `True` |
-| include_declarations | see `js_filegroup` documentation | `False` |
-| include_npm_linked_packages | see `js_filegroup` documentation | `True` |
-| log_level | Set the logging level of the `js_binary` tool.
This overrides the log level set on the `js_binary` tool target. | `None` |
-| mnemonic | A one-word description of the action, for example, CppCompile or GoLink. | `"JsRunBinary"` |
-| progress_message | Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | `None` |
-| execution_requirements | Information for scheduling the action.
For example,
execution_requirements = {
"no-cache": "1",
},
See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. | `None` |
-| stamp | Whether to include build status files as inputs to the tool. Possible values:
- `stamp = 0 (default)`: Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in `--stamp` builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed `stamp` attribute.) - `stamp = 1`: Always include build status files as inputs to the tool, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - `stamp = -1`: Inclusion of build status files as inputs is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change.
Default value is `0` since the majority of js_run_binary targets in a build graph typically do not use build status files and including them for all js_run_binary actions whenever `--stamp` is set would result in invalidating the entire graph and would prevent cache hits. Stamping is typically done in terminal targets when building release artifacts and stamp should typically be set explicitly in these targets to `-1` so it is enabled when the `--stamp` flag is set.
When stamping is enabled, an additional two environment variables will be set for the action: - `BAZEL_STABLE_STATUS_FILE` - `BAZEL_VOLATILE_STATUS_FILE`
These files can be read and parsed by the action, for example to pass some values to a bundler. | `0` |
-| patch_node_fs | Patch the to Node.js `fs` API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, `js_binary` patches the Node.js sync and async `fs` API functions `lstat`, `readlink`, `realpath`, `readdir` and `opendir` so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. | `True` |
-| allow_execroot_entry_point_with_no_copy_data_to_bin | Turn off validation that the `js_binary` tool has `copy_data_to_bin` set to True when `use_execroot_entry_point` is set to True.
See `use_execroot_entry_point` doc for more info. | `False` |
+| tool | The tool to run in the action.
Should be a js_binary rule. Use Aspect bazel-lib's run_binary (https://github.com/aspect-build/bazel-lib/blob/main/lib/run_binary.bzl) for other *_binary rule types. | none |
+| env | Environment variables of the action.
Subject to $(location) and make variable expansion. | {} |
+| srcs | Additional inputs of the action.
These labels are available for $(location) expansion in args and env. | [] |
+| outs | Output files generated by the action.
These labels are available for $(location) expansion in args and env. | [] |
+| out_dirs | Output directories generated by the action.
These labels are _not_ available for $(location) expansion in args and env since they are not pre-declared labels created via attr.output_list(). Output directories are declared instead by ctx.actions.declare_directory. | [] |
+| args | Command line arguments of the binary.
Subject to $(location) and make variable expansion. | [] |
+| chdir | Working directory to run the build action in.
This overrides the chdir value if set on the js_binary tool target.
By default, js_binary tools run in the root of the output tree. For more context on why, please read the aspect_rules_js README https://github.com/aspect-build/rules_js/tree/dbb5af0d2a9a2bb50e4cf4a96dbc582b27567155#running-nodejs-programs.
To run in the directory containing the js_run_binary in the output tree, 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. | None |
+| stdout | set to capture the stdout of the binary to a file, which can later be used as an input to another target subject to the same semantics as outs | None |
+| stderr | set to capture the stderr of the binary to a file, which can later be used as an input to another target subject to the same semantics as outs | None |
+| exit_code_out | set to capture the exit code of the binary to a file, which can later be used as an input to another target subject to the same semantics as outs. Note that setting this will force the binary to exit 0.
If the binary creates outputs and these are declared, they must still be created | None |
+| silent_on_success | produce no output on stdout nor stderr when program exits with status code 0.
This makes node binaries match the expected bazel paradigm. | True |
+| use_execroot_entry_point | Use the entry_point script of the js_binary tool that is in the execroot output tree instead of the copy that is in runfiles.
Runfiles of tool are all hoisted to srcs of the underlying run_binary so they are included as execroot inputs to the action.
Using the entry point script that is in the execroot output tree means that there will be no conflicting runfiles node_modules in the node_modules resolution path which can confuse npm packages such as next and react that don't like being resolved in multiple node_modules trees. This more closely emulates the environment that tools such as Next.js see when they are run outside of Bazel.
When True, the js_binary tool must have copy_data_to_bin set to True (the default) so that all data files needed by the binary are available in the execroot output tree. This requirement can be turned off with by setting allow_execroot_entry_point_with_no_copy_data_to_bin to True. | True |
+| copy_srcs_to_bin | When True, all srcs files are copied to the output tree that are not already there. | True |
+| include_transitive_sources | see js_filegroup documentation | True |
+| include_declarations | see js_filegroup documentation | False |
+| include_npm_linked_packages | see js_filegroup documentation | True |
+| log_level | Set the logging level of the js_binary tool.
This overrides the log level set on the js_binary tool target. | None |
+| mnemonic | A one-word description of the action, for example, CppCompile or GoLink. | "JsRunBinary" |
+| progress_message | Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | None |
+| execution_requirements | Information for scheduling the action.
For example,
execution_requirements = { "no-cache": "1", },
See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. | None |
+| stamp | Whether to include build status files as inputs to the tool. Possible values:
- stamp = 0 (default): Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in --stamp builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed stamp attribute.) - stamp = 1: Always include build status files as inputs to the tool, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - stamp = -1: Inclusion of build status files as inputs is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change.
Default value is 0 since the majority of js_run_binary targets in a build graph typically do not use build status files and including them for all js_run_binary actions whenever --stamp is set would result in invalidating the entire graph and would prevent cache hits. Stamping is typically done in terminal targets when building release artifacts and stamp should typically be set explicitly in these targets to -1 so it is enabled when the --stamp flag is set.
When stamping is enabled, an additional two environment variables will be set for the action: - BAZEL_STABLE_STATUS_FILE - BAZEL_VOLATILE_STATUS_FILE
These files can be read and parsed by the action, for example to pass some values to a bundler. | 0 |
+| patch_node_fs | Patch the to Node.js fs API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, js_binary patches the Node.js sync and async fs API functions lstat, readlink, realpath, readdir and opendir so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. | True |
+| allow_execroot_entry_point_with_no_copy_data_to_bin | Turn off validation that the js_binary tool has copy_data_to_bin set to True when use_execroot_entry_point is set to True.
See use_execroot_entry_point doc for more info. | False |
| kwargs | Additional arguments | none |
diff --git a/docs/js_run_devserver.md b/docs/js_run_devserver.md
index 207fb12bd..1d1e9516e 100644
--- a/docs/js_run_devserver.md
+++ b/docs/js_run_devserver.md
@@ -94,11 +94,11 @@ Only `data` files that change on incremental builds are synchronized when runnin
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | A unique name for this target. | none |
-| tool | The devserver binary target to run.
Only one of `command` or `tool` may be specified. | `None` |
-| command | The devserver command to run.
For example, this could be the bin entry of an npm package that is included in data such as `./node_modules/.bin/next`.
Using the bin entry of next, for example, resolves issues with Next.js and React being found in multiple node_modules trees when next is run as an encapsulated `js_binary` tool.
Only one of `command` or `tool` may be specified. | `None` |
-| grant_sandbox_write_permissions | If set, write permissions is set on all files copied to the custom sandbox.
This can be useful to support some devservers such as Next.js which may, under some circumstances, try to modify files when running.
See https://github.com/aspect-build/rules_js/issues/935 for more context. | `False` |
-| use_execroot_entry_point | Use the `entry_point` script of the `js_binary` `tool` that is in the execroot output tree instead of the copy that is in runfiles.
Using the entry point script that is in the execroot output tree means that there will be no conflicting runfiles `node_modules` in the node_modules resolution path which can confuse npm packages such as next and react that don't like being resolved in multiple node_modules trees. This more closely emulates the environment that tools such as Next.js see when they are run outside of Bazel.
When True, the `js_binary` tool must have `copy_data_to_bin` set to True (the default) so that all data files needed by the binary are available in the execroot output tree. This requirement can be turned off with by setting `allow_execroot_entry_point_with_no_copy_data_to_bin` to True. | `True` |
-| allow_execroot_entry_point_with_no_copy_data_to_bin | Turn off validation that the `js_binary` tool has `copy_data_to_bin` set to True when `use_execroot_entry_point` is set to True.
See `use_execroot_entry_point` doc for more info. | `False` |
-| kwargs | All other args from `js_binary` except for `entry_point` which is set implicitly.
`entry_point` is set implicitly by `js_run_devserver` and cannot be overridden.
See https://docs.aspect.build/rules/aspect_rules_js/docs/js_binary | none |
+| tool | The devserver binary target to run.
Only one of command or tool may be specified. | None |
+| command | The devserver command to run.
For example, this could be the bin entry of an npm package that is included in data such as ./node_modules/.bin/next.
Using the bin entry of next, for example, resolves issues with Next.js and React being found in multiple node_modules trees when next is run as an encapsulated js_binary tool.
Only one of command or tool may be specified. | None |
+| grant_sandbox_write_permissions | If set, write permissions is set on all files copied to the custom sandbox.
This can be useful to support some devservers such as Next.js which may, under some circumstances, try to modify files when running.
See https://github.com/aspect-build/rules_js/issues/935 for more context. | False |
+| use_execroot_entry_point | Use the entry_point script of the js_binary tool that is in the execroot output tree instead of the copy that is in runfiles.
Using the entry point script that is in the execroot output tree means that there will be no conflicting runfiles node_modules in the node_modules resolution path which can confuse npm packages such as next and react that don't like being resolved in multiple node_modules trees. This more closely emulates the environment that tools such as Next.js see when they are run outside of Bazel.
When True, the js_binary tool must have copy_data_to_bin set to True (the default) so that all data files needed by the binary are available in the execroot output tree. This requirement can be turned off with by setting allow_execroot_entry_point_with_no_copy_data_to_bin to True. | True |
+| allow_execroot_entry_point_with_no_copy_data_to_bin | Turn off validation that the js_binary tool has copy_data_to_bin set to True when use_execroot_entry_point is set to True.
See use_execroot_entry_point doc for more info. | False |
+| kwargs | All other args from js_binary except for entry_point which is set implicitly.
entry_point is set implicitly by js_run_devserver and cannot be overridden.
See https://docs.aspect.build/rules/aspect_rules_js/docs/js_binary | none |
diff --git a/docs/npm_import.md b/docs/npm_import.md
index 1a8aefe54..1067296c0 100644
--- a/docs/npm_import.md
+++ b/docs/npm_import.md
@@ -1,5 +1,6 @@
+
Repository rule to fetch npm packages.
Load this with,
@@ -17,6 +18,7 @@ and how to configure it.
See [`npm_translate_lock`](#npm_translate_lock) for the primary user-facing API to fetch npm packages
for a given lockfile.
+
## npm_import
@@ -51,9 +53,9 @@ npm_import(
)
```
-> This is similar to Bazel rules in other ecosystems named "_import" like
-> `apple_bundle_import`, `scala_import`, `java_import`, and `py_import`.
-> `go_repository` is also a model for this rule.
+> This is similar to Bazel rules in other ecosystems named "_import" like
+> `apple_bundle_import`, `scala_import`, `java_import`, and `py_import`.
+> `go_repository` is also a model for this rule.
The name of this repository should contain the version number, so that multiple versions of the same
package don't collide.
@@ -122,7 +124,7 @@ To change the proxy URL we use to fetch, configure the Bazel downloader:
1. Point bazel to the config with a line in .bazelrc like
common --experimental_downloader_config=.bazel_downloader_config
-Read more about the downloader config:
+Read more about the downloader config: <https://blog.aspect.dev/configuring-bazels-downloader>
[UrlRewriterConfig]: https://github.com/bazelbuild/bazel/blob/4.2.1/src/main/java/com/google/devtools/build/lib/bazel/repository/downloader/UrlRewriterConfig.java#L66
@@ -133,33 +135,33 @@ Read more about the downloader config: name | Name for this repository rule | none |
-| package | Name of the npm package, such as `acorn` or `@types/node` | none |
-| version | Version of the npm package, such as `8.4.0` | none |
-| deps | A dict other npm packages this one depends on where the key is the package name and value is the version | `{}` |
-| extra_build_content | Additional content to append on the generated BUILD file at the root of the created repository, either as a string or a list of lines similar to . | `""` |
-| transitive_closure | A dict all npm packages this one depends on directly or transitively where the key is the package name and value is a list of version(s) depended on in the closure. | `{}` |
-| root_package | The root package where the node_modules virtual store is linked to. Typically this is the package that the pnpm-lock.yaml file is located when using `npm_translate_lock`. | `""` |
-| link_workspace | The workspace name where links will be created for this package.
This is typically set in rule sets and libraries that are to be consumed as external repositories so links are created in the external repository and not the user workspace.
Can be left unspecified if the link workspace is the user workspace. | `""` |
-| link_packages | Dict of paths where links may be created at for this package to a list of link aliases to link as in each package. If aliases are an empty list this indicates to link as the package name.
Defaults to {} which indicates that links may be created in any package as specified by the `direct` attribute of the generated npm_link_package. | `{}` |
-| lifecycle_hooks | List of lifecycle hook `package.json` scripts to run for this package if they exist. | `[]` |
-| lifecycle_hooks_execution_requirements | Execution requirements when running the lifecycle hooks.
For example:
lifecycle_hooks_execution_requirements: ["no-sandbox', "requires-network"]
This defaults to ["no-sandbox"] to limit the overhead of sandbox creation and copying the output TreeArtifact out of the sandbox. | `["no-sandbox"]` |
-| lifecycle_hooks_env | Environment variables set for the lifecycle hooks action for this npm package if there is one.
Environment variables are defined by providing an array of "key=value" entries.
For example:
lifecycle_hooks_env: ["PREBULT_BINARY=https://downloadurl"],
| `[]` |
-| integrity | Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded.
This is the same as appears in the pnpm-lock.yaml, yarn.lock or package-lock.json file.
It is a security risk to omit the checksum as remote files can change.
At best omitting this field will make your build non-hermetic.
It is optional to make development easier but should be set before shipping. | `""` |
-| url | Optional url for this package. If unset, a default npm registry url is generated from the package name and version.
May start with `git+ssh://` or `git+https://` to indicate a git repository. For example,
git+ssh://git@github.com/org/repo.git
If url is configured as a git repository, the commit attribute must be set to the desired commit. | `""` |
-| commit | Specific commit to be checked out if url is a git repository. | `""` |
-| patch_args | Arguments to pass to the patch tool.
`-p1` will usually be needed for patches generated by git. | `["-p0"]` |
-| patches | Patch files to apply onto the downloaded npm package. | `[]` |
-| custom_postinstall | Custom string postinstall script to run on the installed npm package. Runs after any existing lifecycle hooks if `run_lifecycle_hooks` is True. | `""` |
-| npm_auth | Auth token to authenticate with npm. When using Bearer authentication. | `""` |
-| npm_auth_basic | Auth token to authenticate with npm. When using Basic authentication.
This is typically the base64 encoded string "username:password". | `""` |
-| npm_auth_username | Auth username to authenticate with npm. When using Basic authentication. | `""` |
-| npm_auth_password | Auth password to authenticate with npm. When using Basic authentication. | `""` |
-| bins | Dictionary of `node_modules/.bin` binary files to create mapped to their node entry points.
This is typically derived from the "bin" attribute in the package.json file of the npm package being linked.
For example:
bins = {
"foo": "./foo.js",
"bar": "./bar.js",
}
In the future, this field may be automatically populated by npm_translate_lock from information in the pnpm lock file. That feature is currently blocked on https://github.com/pnpm/pnpm/issues/5131. | `{}` |
-| dev | Whether this npm package is a dev dependency | `False` |
-| register_copy_directory_toolchains | if True, `@aspect_bazel_lib//lib:repositories.bzl` `register_copy_directory_toolchains()` is called if the toolchain is not already registered | `True` |
-| register_copy_to_directory_toolchains | if True, `@aspect_bazel_lib//lib:repositories.bzl` `register_copy_to_directory_toolchains()` is called if the toolchain is not already registered | `True` |
-| run_lifecycle_hooks | If True, runs `preinstall`, `install`, `postinstall` and 'prepare' lifecycle hooks declared in this package.
Deprecated. Use `lifecycle_hooks` instead. | `None` |
-| lifecycle_hooks_no_sandbox | If True, adds "no-sandbox" to `lifecycle_hooks_execution_requirements`.
Deprecated. Add "no-sandbox" to `lifecycle_hooks_execution_requirements` instead. | `None` |
+| package | Name of the npm package, such as acorn or @types/node | none |
+| version | Version of the npm package, such as 8.4.0 | none |
+| deps | A dict other npm packages this one depends on where the key is the package name and value is the version | {} |
+| extra_build_content | Additional content to append on the generated BUILD file at the root of the created repository, either as a string or a list of lines similar to <https://github.com/bazelbuild/bazel-skylib/blob/main/docs/write_file_doc.md>. | "" |
+| transitive_closure | A dict all npm packages this one depends on directly or transitively where the key is the package name and value is a list of version(s) depended on in the closure. | {} |
+| root_package | The root package where the node_modules virtual store is linked to. Typically this is the package that the pnpm-lock.yaml file is located when using npm_translate_lock. | "" |
+| link_workspace | The workspace name where links will be created for this package.
This is typically set in rule sets and libraries that are to be consumed as external repositories so links are created in the external repository and not the user workspace.
Can be left unspecified if the link workspace is the user workspace. | "" |
+| link_packages | Dict of paths where links may be created at for this package to a list of link aliases to link as in each package. If aliases are an empty list this indicates to link as the package name.
Defaults to {} which indicates that links may be created in any package as specified by the direct attribute of the generated npm_link_package. | {} |
+| lifecycle_hooks | List of lifecycle hook package.json scripts to run for this package if they exist. | [] |
+| lifecycle_hooks_execution_requirements | Execution requirements when running the lifecycle hooks.
For example:
lifecycle_hooks_execution_requirements: ["no-sandbox', "requires-network"]
This defaults to ["no-sandbox"] to limit the overhead of sandbox creation and copying the output TreeArtifact out of the sandbox. | ["no-sandbox"] |
+| lifecycle_hooks_env | Environment variables set for the lifecycle hooks action for this npm package if there is one.
Environment variables are defined by providing an array of "key=value" entries.
For example:
lifecycle_hooks_env: ["PREBULT_BINARY=https://downloadurl"],
| [] |
+| integrity | Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded.
This is the same as appears in the pnpm-lock.yaml, yarn.lock or package-lock.json file.
It is a security risk to omit the checksum as remote files can change.
At best omitting this field will make your build non-hermetic.
It is optional to make development easier but should be set before shipping. | "" |
+| url | Optional url for this package. If unset, a default npm registry url is generated from the package name and version.
May start with git+ssh:// or git+https:// to indicate a git repository. For example,
git+ssh://git@github.com/org/repo.git
If url is configured as a git repository, the commit attribute must be set to the desired commit. | "" |
+| commit | Specific commit to be checked out if url is a git repository. | "" |
+| patch_args | Arguments to pass to the patch tool.
-p1 will usually be needed for patches generated by git. | ["-p0"] |
+| patches | Patch files to apply onto the downloaded npm package. | [] |
+| custom_postinstall | Custom string postinstall script to run on the installed npm package. Runs after any existing lifecycle hooks if run_lifecycle_hooks is True. | "" |
+| npm_auth | Auth token to authenticate with npm. When using Bearer authentication. | "" |
+| npm_auth_basic | Auth token to authenticate with npm. When using Basic authentication.
This is typically the base64 encoded string "username:password". | "" |
+| npm_auth_username | Auth username to authenticate with npm. When using Basic authentication. | "" |
+| npm_auth_password | Auth password to authenticate with npm. When using Basic authentication. | "" |
+| bins | Dictionary of node_modules/.bin binary files to create mapped to their node entry points.
This is typically derived from the "bin" attribute in the package.json file of the npm package being linked.
For example:
bins = { "foo": "./foo.js", "bar": "./bar.js", }
In the future, this field may be automatically populated by npm_translate_lock from information in the pnpm lock file. That feature is currently blocked on https://github.com/pnpm/pnpm/issues/5131. | {} |
+| dev | Whether this npm package is a dev dependency | False |
+| register_copy_directory_toolchains | if True, @aspect_bazel_lib//lib:repositories.bzl register_copy_directory_toolchains() is called if the toolchain is not already registered | True |
+| register_copy_to_directory_toolchains | if True, @aspect_bazel_lib//lib:repositories.bzl register_copy_to_directory_toolchains() is called if the toolchain is not already registered | True |
+| run_lifecycle_hooks | If True, runs preinstall, install, postinstall and 'prepare' lifecycle hooks declared in this package.
Deprecated. Use lifecycle_hooks instead. | None |
+| lifecycle_hooks_no_sandbox | If True, adds "no-sandbox" to lifecycle_hooks_execution_requirements.
Deprecated. Add "no-sandbox" to lifecycle_hooks_execution_requirements instead. | None |
| kwargs | Internal use only | none |
diff --git a/docs/npm_link_all_packages.md b/docs/npm_link_all_packages.md
index 9d32d60e9..403057ee4 100644
--- a/docs/npm_link_all_packages.md
+++ b/docs/npm_link_all_packages.md
@@ -11,6 +11,7 @@ For example, if you run `npm_translate_lock(name = "npm")` then these rules can
load("@npm//:defs.bzl", "npm_link_targets", "npm_link_all_packages")
```
+
## npm_link_all_packages
@@ -39,8 +40,8 @@ If you use manually-written [`npm_import`](/docs/npm_import.md#npm_import) you c
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
-| name | name of catch all target to generate for all packages linked | `"node_modules"` |
-| imported_links | optional list link functions from manually imported packages that were fetched with npm_import rules. | `[]` |
+| name | name of catch all target to generate for all packages linked | "node_modules" |
+| imported_links | optional list link functions from manually imported packages that were fetched with npm_import rules. | [] |
@@ -58,8 +59,8 @@ Generated list of target names that are linked by npm_link_all_packages()
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
-| name | name of catch all target to generate for all packages linked | `"node_modules"` |
-| package | Bazel package to generate targets names for.
Set to an empty string "" to specify the root package.
If unspecified, the current package (`native.package_name()`) is used. | `None` |
+| name | name of catch all target to generate for all packages linked | "node_modules" |
+| package | Bazel package to generate targets names for.
Set to an empty string "" to specify the root package.
If unspecified, the current package (native.package_name()) is used. | None |
**RETURNS**
diff --git a/docs/npm_link_package.md b/docs/npm_link_package.md
index 3d55f27f9..1c0149d7d 100644
--- a/docs/npm_link_package.md
+++ b/docs/npm_link_package.md
@@ -15,7 +15,7 @@ npm_link_package(name, name | The name of the link target to create if `link` is True. For first-party deps linked across a workspace, the name must match in all packages being linked as it is used to derive the virtual store link target name. | none |
-| root_package | the root package where the node_modules virtual store is linked to | `""` |
-| link | whether or not to link in this package If false, only the npm_package_store target will be created _if_ this is called in the `root_package`. | `True` |
-| src | the npm_package target to link; may only to be specified when linking in the root package | `None` |
-| deps | list of npm_package_store; may only to be specified when linking in the root package | `{}` |
-| fail_if_no_link | whether or not to fail if this is called in a package that is not the root package and `link` is False | `True` |
-| auto_manual | whether or not to automatically add a manual tag to the generated targets Links tagged "manual" dy default is desirable so that they are not built by `bazel build ...` if they are unused downstream. For 3rd party deps, this is particularly important so that 3rd party deps are not fetched at all unless they are used. | `True` |
-| visibility | the visibility of the generated targets | `["//visibility:public"]` |
+| name | The name of the link target to create if link is True. For first-party deps linked across a workspace, the name must match in all packages being linked as it is used to derive the virtual store link target name. | none |
+| root_package | the root package where the node_modules virtual store is linked to | "" |
+| link | whether or not to link in this package If false, only the npm_package_store target will be created _if_ this is called in the root_package. | True |
+| src | the npm_package target to link; may only to be specified when linking in the root package | None |
+| deps | list of npm_package_store; may only to be specified when linking in the root package | {} |
+| fail_if_no_link | whether or not to fail if this is called in a package that is not the root package and link is False | True |
+| auto_manual | whether or not to automatically add a manual tag to the generated targets Links tagged "manual" dy default is desirable so that they are not built by bazel build ... if they are unused downstream. For 3rd party deps, this is particularly important so that 3rd party deps are not fetched at all unless they are used. | True |
+| visibility | the visibility of the generated targets | ["//visibility:public"] |
| kwargs | see attributes of npm_package_store rule | none |
**RETURNS**
diff --git a/docs/npm_package.md b/docs/npm_package.md
index 88c15b97a..ff101b579 100644
--- a/docs/npm_package.md
+++ b/docs/npm_package.md
@@ -1,5 +1,6 @@
+
Rules for linking npm dependencies and packaging and linking first-party deps.
Load these with,
@@ -8,6 +9,7 @@ Load these with,
load("@aspect_rules_js//npm:defs.bzl", "npm_package")
```
+
## npm_package
@@ -87,28 +89,28 @@ To stamp the current git tag as the "version" in the package.json file, see
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | Unique name for this target. | none |
-| srcs | Files and/or directories or targets that provide `DirectoryPathInfo` to copy into the output directory. | `[]` |
-| data | Runtime / linktime npm dependencies of this npm package.
`NpmPackageStoreInfo` providers are gathered from `JsInfo` of the targets specified. Targets can be linked npm packages, npm package store targets or other targets that provide `JsInfo`. This is done directly from the `npm_package_store_deps` field of these. For linked npm package targets, the underlying npm_package_store target(s) that back the links is used.
Gathered `NpmPackageStoreInfo` providers are used downstream as direct dependencies of this npm package when linking with `npm_link_package`. | `[]` |
-| args | Arguments that are passed down to `.publish` target and `npm publish` command. | `[]` |
-| out | Path of the output directory, relative to this package. | `None` |
-| package | The package name. If set, should match the `name` field in the `package.json` file for this package.
If set, the package name set here will be used for linking if a npm_link_package does not specify a package name. A npm_link_package that specifies a package name will override the value here when linking.
If unset, a npm_link_package that references this npm_package must define the package name must be for linking. | `""` |
-| version | The package version. If set, should match the `version` field in the `package.json` file for this package.
If set, a npm_link_package may omit the package version and the package version set here will be used for linking. A npm_link_package that specifies a package version will override the value here when linking.
If unset, a npm_link_package that references this npm_package must define the package version must be for linking. | `"0.0.0"` |
-| root_paths | List of paths (with glob support) that are roots in the output directory.
If any parent directory of a file being copied matches one of the root paths patterns specified, the output directory path will be the path relative to the root path instead of the path relative to the file's workspace. If there are multiple root paths that match, the longest match wins.
Matching is done on the parent directory of the output file path so a trailing '**' glob patterm will match only up to the last path segment of the dirname and will not include the basename. Only complete path segments are matched. Partial matches on the last segment of the root path are ignored.
Forward slashes (`/`) should be used as path separators.
A `"."` value expands to the target's package path (`ctx.label.package`).
Defaults to `["."]` which results in the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths.
Globs are supported (see rule docstring above). | `["."]` |
-| include_external_repositories | List of external repository names (with glob support) to include in the output directory.
Files from external repositories are only copied into the output directory if the external repository they come from matches one of the external repository patterns specified.
When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is _not_ included in that path.
For example, the following copies `@external_repo//path/to:file` to `path/to/file` within the output directory.
npp_package(
name = "dir",
include_external_repositories = ["external_*"],
srcs = ["@external_repo//path/to:file"],
)
Files that come from matching external are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. The external repository name of the file from an external repository is not included in the output directory path and is considered in subsequent filters and transformations.
Globs are supported (see rule docstring above). | `[]` |
-| include_srcs_packages | List of Bazel packages (with glob support) to include in output directory.
Files in srcs are only copied to the output directory if the Bazel package of the file matches one of the patterns specified.
Forward slashes (`/`) should be used as path separators. A first character of `"."` will be replaced by the target's package path.
Defaults to ["./**"] which includes sources target's package and subpackages.
Files that have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | `["./**"]` |
-| exclude_srcs_packages | List of Bazel packages (with glob support) to exclude from output directory.
Files in srcs are not copied to the output directory if the Bazel package of the file matches one of the patterns specified.
Forward slashes (`/`) should be used as path separators. A first character of `"."` will be replaced by the target's package path.
Defaults to ["**/node_modules/**"] which excludes all node_modules folders from the output directory.
Files that have do not have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | `[]` |
-| include_srcs_patterns | List of paths (with glob support) to include in output directory.
Files in srcs are only copied to the output directory if their output directory path, after applying `root_paths`, matches one of the patterns specified.
Forward slashes (`/`) should be used as path separators.
Defaults to `["**"]` which includes all sources.
Files that have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | `["**"]` |
-| exclude_srcs_patterns | List of paths (with glob support) to exclude from output directory.
Files in srcs are not copied to the output directory if their output directory path, after applying `root_paths`, matches one of the patterns specified.
Forward slashes (`/`) should be used as path separators.
Files that do not have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | `["**/node_modules/**"]` |
-| replace_prefixes | Map of paths prefixes (with glob support) to replace in the output directory path when copying files.
If the output directory path for a file starts with or fully matches a a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key. The final path segment matched can be a partial match of that segment and only the matching portion will be replaced. If there are multiple keys that match, the longest match wins.
Forward slashes (`/`) should be used as path separators.
Replace prefix transformation are the final step in the list of filters and transformations. The final output path of a file being copied into the output directory is determined at this step.
Globs are supported (see rule docstring above). | `{}` |
-| allow_overwrites | If True, allow files to be overwritten if the same output file is copied to twice.
The order of srcs matters as the last copy of a particular file will win when overwriting. Performance of `npm_package` will be slightly degraded when allow_overwrites is True since copies cannot be parallelized out as they are calculated. Instead all copy paths must be calculated before any copies can be started. | `False` |
-| include_sources | When True, `sources` from `JsInfo` providers in data targets are included in the list of available files to copy. | `True` |
-| include_transitive_sources | When True, `transitive_sources` from `JsInfo` providers in data targets are included in the list of available files to copy. | `True` |
-| include_declarations | When True, `declarations` from `JsInfo` providers in data targets are included in the list of available files to copy. | `True` |
-| include_transitive_declarations | When True, `transitive_declarations` from `JsInfo` providers in data targets are included in the list of available files to copy. | `True` |
-| include_runfiles | When True, default runfiles from `srcs` targets are included in the list of available files to copy.
This may be needed in a few cases:
- to work-around issues with rules that don't provide everything needed in sources, transitive_sources, declarations & transitive_declarations - to depend on the runfiles targets that don't use JsInfo
NB: The default value will be flipped to False in the next major release as runfiles are not needed in the general case and adding them to the list of files available to copy can add noticeable overhead to the analysis phase in a large repository with many npm_package targets. | `True` |
-| hardlink | Controls when to use hardlinks to files instead of making copies.
Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source.
Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files are not recommended since write permissions will be inadvertently removed from sources files.
- `auto`: hardlinks are used for generated files already in the output tree - `off`: all files are copied - `on`: hardlinks are used for all files (not recommended) | `"auto"` |
-| verbose | If true, prints out verbose logs to stdout | `False` |
-| kwargs | Additional attributes such as `tags` and `visibility` | none |
+| srcs | Files and/or directories or targets that provide DirectoryPathInfo to copy into the output directory. | [] |
+| data | Runtime / linktime npm dependencies of this npm package.
NpmPackageStoreInfo providers are gathered from JsInfo of the targets specified. Targets can be linked npm packages, npm package store targets or other targets that provide JsInfo. This is done directly from the npm_package_store_deps field of these. For linked npm package targets, the underlying npm_package_store target(s) that back the links is used.
Gathered NpmPackageStoreInfo providers are used downstream as direct dependencies of this npm package when linking with npm_link_package. | [] |
+| args | Arguments that are passed down to <name>.publish target and npm publish command. | [] |
+| out | Path of the output directory, relative to this package. | None |
+| package | The package name. If set, should match the name field in the package.json file for this package.
If set, the package name set here will be used for linking if a npm_link_package does not specify a package name. A npm_link_package that specifies a package name will override the value here when linking.
If unset, a npm_link_package that references this npm_package must define the package name must be for linking. | "" |
+| version | The package version. If set, should match the version field in the package.json file for this package.
If set, a npm_link_package may omit the package version and the package version set here will be used for linking. A npm_link_package that specifies a package version will override the value here when linking.
If unset, a npm_link_package that references this npm_package must define the package version must be for linking. | "0.0.0" |
+| root_paths | List of paths (with glob support) that are roots in the output directory.
If any parent directory of a file being copied matches one of the root paths patterns specified, the output directory path will be the path relative to the root path instead of the path relative to the file's workspace. If there are multiple root paths that match, the longest match wins.
Matching is done on the parent directory of the output file path so a trailing '**' glob patterm will match only up to the last path segment of the dirname and will not include the basename. Only complete path segments are matched. Partial matches on the last segment of the root path are ignored.
Forward slashes (/) should be used as path separators.
A "." value expands to the target's package path (ctx.label.package).
Defaults to ["."] which results in the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths.
Globs are supported (see rule docstring above). | ["."] |
+| include_external_repositories | List of external repository names (with glob support) to include in the output directory.
Files from external repositories are only copied into the output directory if the external repository they come from matches one of the external repository patterns specified.
When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is _not_ included in that path.
For example, the following copies @external_repo//path/to:file to path/to/file within the output directory.
npp_package( name = "dir", include_external_repositories = ["external_*"], srcs = ["@external_repo//path/to:file"], )
Files that come from matching external are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. The external repository name of the file from an external repository is not included in the output directory path and is considered in subsequent filters and transformations.
Globs are supported (see rule docstring above). | [] |
+| include_srcs_packages | List of Bazel packages (with glob support) to include in output directory.
Files in srcs are only copied to the output directory if the Bazel package of the file matches one of the patterns specified.
Forward slashes (/) should be used as path separators. A first character of "." will be replaced by the target's package path.
Defaults to ["./**"] which includes sources target's package and subpackages.
Files that have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | ["./**"] |
+| exclude_srcs_packages | List of Bazel packages (with glob support) to exclude from output directory.
Files in srcs are not copied to the output directory if the Bazel package of the file matches one of the patterns specified.
Forward slashes (/) should be used as path separators. A first character of "." will be replaced by the target's package path.
Defaults to ["**/node_modules/**"] which excludes all node_modules folders from the output directory.
Files that have do not have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | [] |
+| include_srcs_patterns | List of paths (with glob support) to include in output directory.
Files in srcs are only copied to the output directory if their output directory path, after applying root_paths, matches one of the patterns specified.
Forward slashes (/) should be used as path separators.
Defaults to ["**"] which includes all sources.
Files that have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | ["**"] |
+| exclude_srcs_patterns | List of paths (with glob support) to exclude from output directory.
Files in srcs are not copied to the output directory if their output directory path, after applying root_paths, matches one of the patterns specified.
Forward slashes (/) should be used as path separators.
Files that do not have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.
Globs are supported (see rule docstring above). | ["**/node_modules/**"] |
+| replace_prefixes | Map of paths prefixes (with glob support) to replace in the output directory path when copying files.
If the output directory path for a file starts with or fully matches a a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key. The final path segment matched can be a partial match of that segment and only the matching portion will be replaced. If there are multiple keys that match, the longest match wins.
Forward slashes (/) should be used as path separators.
Replace prefix transformation are the final step in the list of filters and transformations. The final output path of a file being copied into the output directory is determined at this step.
Globs are supported (see rule docstring above). | {} |
+| allow_overwrites | If True, allow files to be overwritten if the same output file is copied to twice.
The order of srcs matters as the last copy of a particular file will win when overwriting. Performance of npm_package will be slightly degraded when allow_overwrites is True since copies cannot be parallelized out as they are calculated. Instead all copy paths must be calculated before any copies can be started. | False |
+| include_sources | When True, sources from JsInfo providers in data targets are included in the list of available files to copy. | True |
+| include_transitive_sources | When True, transitive_sources from JsInfo providers in data targets are included in the list of available files to copy. | True |
+| include_declarations | When True, declarations from JsInfo providers in data targets are included in the list of available files to copy. | True |
+| include_transitive_declarations | When True, transitive_declarations from JsInfo providers in data targets are included in the list of available files to copy. | True |
+| include_runfiles | When True, default runfiles from srcs targets are included in the list of available files to copy.
This may be needed in a few cases:
- to work-around issues with rules that don't provide everything needed in sources, transitive_sources, declarations & transitive_declarations - to depend on the runfiles targets that don't use JsInfo
NB: The default value will be flipped to False in the next major release as runfiles are not needed in the general case and adding them to the list of files available to copy can add noticeable overhead to the analysis phase in a large repository with many npm_package targets. | True |
+| hardlink | Controls when to use hardlinks to files instead of making copies.
Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source.
Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files are not recommended since write permissions will be inadvertently removed from sources files.
- auto: hardlinks are used for generated files already in the output tree - off: all files are copied - on: hardlinks are used for all files (not recommended) | "auto" |
+| verbose | If true, prints out verbose logs to stdout | False |
+| kwargs | Additional attributes such as tags and visibility | none |
@@ -158,7 +160,7 @@ register_jq_toolchains()
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
-| name | name of the resulting `jq` target, must be "package" | none |
+| name | name of the resulting jq target, must be "package" | none |
| stamp_var | a key from the bazel-out/stable-status.txt or bazel-out/volatile-status.txt files | none |
| kwargs | additional attributes passed to the jq rule, see https://docs.aspect.build/rules/aspect_bazel_lib/docs/jq | none |
diff --git a/docs/npm_translate_lock.md b/docs/npm_translate_lock.md
index f2c6801b8..c1b719b84 100644
--- a/docs/npm_translate_lock.md
+++ b/docs/npm_translate_lock.md
@@ -11,7 +11,7 @@ load("@aspect_rules_js//npm:repositories.bzl", "npm_translate_lock")
These use Bazel's downloader to fetch the packages.
You can use this to redirect all fetches through a store like Artifactory.
-See for more info about how it works
+See <https://blog.aspect.dev/configuring-bazels-downloader> for more info about how it works
and how to configure it.
[`npm_translate_lock`](#npm_translate_lock) is the primary user-facing API.
@@ -26,6 +26,7 @@ If you don't have an existing lock file, you can run `npx pnpm install --lockfil
Advanced users may want to directly fetch a package from npm rather than start from a lockfile,
[`npm_import`](./npm_import) does this.
+
## list_patches
@@ -47,9 +48,9 @@ file stays up to date.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | Name of the target | none |
-| out | Name of file to write to the source tree. If unspecified, `name` is used | `None` |
-| include_patterns | Patterns to pass to a glob of patch files | `["*.diff", "*.patch"]` |
-| exclude_patterns | Patterns to ignore in a glob of patch files | `[]` |
+| out | Name of file to write to the source tree. If unspecified, name is used | None |
+| include_patterns | Patterns to pass to a glob of patch files | ["*.diff", "*.patch"] |
+| exclude_patterns | Patterns to ignore in a glob of patch files | [] |
@@ -95,40 +96,40 @@ For more about how to use npm_translate_lock, read [pnpm and rules_js](/docs/pnp
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | The repository rule name | none |
-| pnpm_lock | The `pnpm-lock.yaml` file. | `None` |
-| npm_package_lock | The `package-lock.json` file written by `npm install`.
Only one of `npm_package_lock` or `yarn_lock` may be set. | `None` |
-| yarn_lock | The `yarn.lock` file written by `yarn install`.
Only one of `npm_package_lock` or `yarn_lock` may be set. | `None` |
-| update_pnpm_lock | When True, the pnpm lock file will be updated automatically when any of its inputs have changed since the last update.
Defaults to True when one of `npm_package_lock` or `yarn_lock` are set. Otherwise it defaults to False.
Read more: [using update_pnpm_lock](/docs/pnpm.md#update_pnpm_lock) | `None` |
-| update_pnpm_lock_node_toolchain_prefix | the prefix of the node toolchain to use when generating the pnpm lockfile. | `"nodejs"` |
-| preupdate | Node.js scripts to run in this repository rule before auto-updating the pnpm lock file.
Scripts are run sequentially in the order they are listed. The working directory is set to the root of the external repository. Make sure all files required by preupdate scripts are added to the `data` attribute.
A preupdate script could, for example, transform `resolutions` in the root `package.json` file from a format that yarn understands such as `@foo/**/bar` to the equivalent `@foo/*>bar` that pnpm understands so that `resolutions` are compatible with pnpm when running `pnpm import` to update the pnpm lock file.
Only needed when `update_pnpm_lock` is True. Read more: [using update_pnpm_lock](/docs/pnpm.md#update_pnpm_lock) | `[]` |
-| npmrc | The `.npmrc` file, if any, to use.
When set, the `.npmrc` file specified is parsed and npm auth tokens and basic authentication configuration specified in the file are passed to the Bazel downloader for authentication with private npm registries.
In a future release, pnpm settings such as public-hoist-patterns will be used. | `None` |
-| use_home_npmrc | Use the `$HOME/.npmrc` file (or `$USERPROFILE/.npmrc` when on Windows) if it exists.
Settings from home `.npmrc` are merged with settings loaded from the `.npmrc` file specified in the `npmrc` attribute, if any. Where there are conflicting settings, the home `.npmrc` values will take precedence.
WARNING: The repository rule will not be invalidated by changes to the home `.npmrc` file since there is no way to specify this file as an input to the repository rule. If changes are made to the home `.npmrc` you can force the repository rule to re-run and pick up the changes by running: `bazel run @{name}//:sync` where `name` is the name of the `npm_translate_lock` you want to re-run.
Because of the repository rule invalidation issue, using the home `.npmrc` is not recommended. `.npmrc` settings should generally go in the `npmrc` in your repository so they are shared by all developers. The home `.npmrc` should be reserved for authentication settings for private npm repositories. | `None` |
-| data | Data files required by this repository rule when auto-updating the pnpm lock file.
Only needed when `update_pnpm_lock` is True. Read more: [using update_pnpm_lock](/docs/pnpm.md#update_pnpm_lock) | `[]` |
-| patches | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a label list of patches to apply to the downloaded npm package. Multiple matches are additive.
These patches are applied after any patches in [pnpm.patchedDependencies](https://pnpm.io/next/package_json#pnpmpatcheddependencies).
Read more: [patching](/docs/pnpm.md#patching) | `{}` |
-| patch_args | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a label list arguments to pass to the patch tool. The most specific match wins.
Read more: [patching](/docs/pnpm.md#patching) | `{"*": ["-p0"]}` |
-| custom_postinstalls | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a custom postinstall script to apply to the downloaded npm package after its lifecycle scripts runs. If the version is left out of the package name, the script will run on every version of the npm package. If a custom postinstall scripts exists for a package as well as for a specific version, the script for the versioned package will be appended with `&&` to the non-versioned package script.
For example,
custom_postinstalls = {
"@foo/bar": "echo something > somewhere.txt",
"fum@0.0.1": "echo something_else > somewhere_else.txt",
},
Custom postinstalls are additive and joined with ` && ` when there are multiple matches for a package. More specific matches are appended to previous matches. | `{}` |
-| prod | If True, only install `dependencies` but not `devDependencies`. | `False` |
-| public_hoist_packages | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a list of Bazel packages in which to hoist the package to the top-level of the node_modules tree when linking.
This is similar to setting https://pnpm.io/npmrc#public-hoist-pattern in an .npmrc file outside of Bazel, however, wild-cards are not yet supported and npm_translate_lock will fail if there are multiple versions of a package that are to be hoisted.
public_hoist_packages = {
"@foo/bar": [""] # link to the root package in the WORKSPACE
"fum@0.0.1": ["some/sub/package"]
},
List of public hoist packages are additive when there are multiple matches for a package. More specific matches are appended to previous matches. | `{}` |
-| dev | If True, only install `devDependencies` | `False` |
-| no_optional | If True, `optionalDependencies` are not installed.
Currently `npm_translate_lock` behaves differently from pnpm in that is downloads all `optionaDependencies` while pnpm doesn't download `optionalDependencies` that are not needed for the platform pnpm is run on. See https://github.com/pnpm/pnpm/pull/3672 for more context. | `False` |
-| run_lifecycle_hooks | Sets a default value for `lifecycle_hooks` if `*` not already set. Set this to `False` to disable lifecycle hooks. | `True` |
-| lifecycle_hooks | A dict of package names to list of lifecycle hooks to run for that package.
By default the `preinstall`, `install` and `postinstall` hooks are run if they exist. This attribute allows the default to be overridden for packages to run `prepare`.
List of hooks are not additive. The most specific match wins.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | `{}` |
-| lifecycle_hooks_envs | Environment variables set for the lifecycle hooks actions on npm packages. The environment variables can be defined per package by package name or globally using "*". Variables are declared as key/value pairs of the form "key=value". Multiple matches are additive.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | `{}` |
-| lifecycle_hooks_exclude | A list of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to not run any lifecycle hooks on.
Equivalent to adding `: []` to `lifecycle_hooks`.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | `[]` |
-| lifecycle_hooks_execution_requirements | Execution requirements applied to the preinstall, install and postinstall lifecycle hooks on npm packages.
The execution requirements can be defined per package by package name or globally using "*".
Execution requirements are not additive. The most specific match wins.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | `{}` |
-| lifecycle_hooks_no_sandbox | If True, a "no-sandbox" execution requirement is added to all lifecycle hooks unless overridden by `lifecycle_hooks_execution_requirements`.
Equivalent to adding `"*": ["no-sandbox"]` to `lifecycle_hooks_execution_requirements`.
This defaults to True to limit the overhead of sandbox creation and copying the output TreeArtifacts out of the sandbox.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | `True` |
-| bins | Binary files to create in `node_modules/.bin` for packages in this lock file.
For a given package, this is typically derived from the "bin" attribute in the package.json file of that package.
For example:
bins = {
"@foo/bar": {
"foo": "./foo.js",
"bar": "./bar.js"
},
}
Dicts of bins not additive. The most specific match wins.
In the future, this field may be automatically populated from information in the pnpm lock file. That feature is currently blocked on https://github.com/pnpm/pnpm/issues/5131. | `{}` |
-| verify_node_modules_ignored | node_modules folders in the source tree should be ignored by Bazel.
This points to a `.bazelignore` file to verify that all nested node_modules directories pnpm will create are listed.
See https://github.com/bazelbuild/bazel/issues/8106 | `None` |
-| verify_patches | Label to a patch list file.
Use this in together with the `list_patches` macro to guarantee that all patches in a patch folder are included in the `patches` attribute.
For example:
verify_patches = "//patches:patches.list",
In your patches folder add a BUILD.bazel file containing. load("@aspect_rules_js//npm:repositories.bzl", "list_patches")
list_patches(
name = "patches",
out = "patches.list",
)
Once you have created this file, you need to create an empty `patches.list` file before generating the first list. You can do this by running touch patches/patches.list
Finally, write the patches file at least once to make sure all patches are listed. This can be done by running `bazel run //patches:patches_update`.
See the `list_patches` documentation for further info. NOTE: if you would like to customize the patches directory location, you can set a flag in the `.npmrc`. Here is an example of what this might look like # Set the directory for pnpm when patching
# https://github.com/pnpm/pnpm/issues/6508#issuecomment-1537242124
patches-dir=bazel/js/patches
If you do this, you will have to update the `verify_patches` path to be this path instead of `//patches` like above. | `None` |
-| quiet | Set to False to print info logs and output stdout & stderr of pnpm lock update actions to the console. | `True` |
-| external_repository_action_cache | The location of the external repository action cache to write to when `update_pnpm_lock` = True. | `".aspect/rules/external_repository_action_cache"` |
-| link_workspace | The workspace name where links will be created for the packages in this lock file.
This is typically set in rule sets and libraries that vendor the starlark generated by npm_translate_lock so the link_workspace passed to npm_import is set correctly so that links are created in the external repository and not the user workspace.
Can be left unspecified if the link workspace is the user workspace. | `None` |
-| pnpm_version | pnpm version to use when generating the @pnpm repository. Set to None to not create this repository. | `"8.7.6"` |
-| register_copy_directory_toolchains | if True, `@aspect_bazel_lib//lib:repositories.bzl` `register_copy_directory_toolchains()` is called if the toolchain is not already registered | `True` |
-| register_copy_to_directory_toolchains | if True, `@aspect_bazel_lib//lib:repositories.bzl` `register_copy_to_directory_toolchains()` is called if the toolchain is not already registered | `True` |
-| npm_package_target_name | The name of linked `npm_package` targets. When `npm_package` targets are linked as pnpm workspace packages, the name of the target must align with this value.
The `{dirname}` placeholder is replaced with the directory name of the target.
By default the directory name of the target is used.
Default: `{dirname}` | `"{dirname}"` |
-| package_json | Deprecated.
Add all `package.json` files that are part of the workspace to `data` instead. | `None` |
-| warn_on_unqualified_tarball_url | Deprecated. Will be removed in next major release. | `None` |
+| pnpm_lock | The pnpm-lock.yaml file. | None |
+| npm_package_lock | The package-lock.json file written by npm install.
Only one of npm_package_lock or yarn_lock may be set. | None |
+| yarn_lock | The yarn.lock file written by yarn install.
Only one of npm_package_lock or yarn_lock may be set. | None |
+| update_pnpm_lock | When True, the pnpm lock file will be updated automatically when any of its inputs have changed since the last update.
Defaults to True when one of npm_package_lock or yarn_lock are set. Otherwise it defaults to False.
Read more: [using update_pnpm_lock](/docs/pnpm.md#update_pnpm_lock) | None |
+| update_pnpm_lock_node_toolchain_prefix | the prefix of the node toolchain to use when generating the pnpm lockfile. | "nodejs" |
+| preupdate | Node.js scripts to run in this repository rule before auto-updating the pnpm lock file.
Scripts are run sequentially in the order they are listed. The working directory is set to the root of the external repository. Make sure all files required by preupdate scripts are added to the data attribute.
A preupdate script could, for example, transform resolutions in the root package.json file from a format that yarn understands such as @foo/**/bar to the equivalent @foo/*>bar that pnpm understands so that resolutions are compatible with pnpm when running pnpm import to update the pnpm lock file.
Only needed when update_pnpm_lock is True. Read more: [using update_pnpm_lock](/docs/pnpm.md#update_pnpm_lock) | [] |
+| npmrc | The .npmrc file, if any, to use.
When set, the .npmrc file specified is parsed and npm auth tokens and basic authentication configuration specified in the file are passed to the Bazel downloader for authentication with private npm registries.
In a future release, pnpm settings such as public-hoist-patterns will be used. | None |
+| use_home_npmrc | Use the $HOME/.npmrc file (or $USERPROFILE/.npmrc when on Windows) if it exists.
Settings from home .npmrc are merged with settings loaded from the .npmrc file specified in the npmrc attribute, if any. Where there are conflicting settings, the home .npmrc values will take precedence.
WARNING: The repository rule will not be invalidated by changes to the home .npmrc file since there is no way to specify this file as an input to the repository rule. If changes are made to the home .npmrc you can force the repository rule to re-run and pick up the changes by running: bazel run @{name}//:sync where name is the name of the npm_translate_lock you want to re-run.
Because of the repository rule invalidation issue, using the home .npmrc is not recommended. .npmrc settings should generally go in the npmrc in your repository so they are shared by all developers. The home .npmrc should be reserved for authentication settings for private npm repositories. | None |
+| data | Data files required by this repository rule when auto-updating the pnpm lock file.
Only needed when update_pnpm_lock is True. Read more: [using update_pnpm_lock](/docs/pnpm.md#update_pnpm_lock) | [] |
+| patches | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a label list of patches to apply to the downloaded npm package. Multiple matches are additive.
These patches are applied after any patches in [pnpm.patchedDependencies](https://pnpm.io/next/package_json#pnpmpatcheddependencies).
Read more: [patching](/docs/pnpm.md#patching) | {} |
+| patch_args | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a label list arguments to pass to the patch tool. The most specific match wins.
Read more: [patching](/docs/pnpm.md#patching) | {"*": ["-p0"]} |
+| custom_postinstalls | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a custom postinstall script to apply to the downloaded npm package after its lifecycle scripts runs. If the version is left out of the package name, the script will run on every version of the npm package. If a custom postinstall scripts exists for a package as well as for a specific version, the script for the versioned package will be appended with && to the non-versioned package script.
For example,
custom_postinstalls = { "@foo/bar": "echo something > somewhere.txt", "fum@0.0.1": "echo something_else > somewhere_else.txt", },
Custom postinstalls are additive and joined with && when there are multiple matches for a package. More specific matches are appended to previous matches. | {} |
+| prod | If True, only install dependencies but not devDependencies. | False |
+| public_hoist_packages | A map of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to a list of Bazel packages in which to hoist the package to the top-level of the node_modules tree when linking.
This is similar to setting https://pnpm.io/npmrc#public-hoist-pattern in an .npmrc file outside of Bazel, however, wild-cards are not yet supported and npm_translate_lock will fail if there are multiple versions of a package that are to be hoisted.
public_hoist_packages = { "@foo/bar": [""] # link to the root package in the WORKSPACE "fum@0.0.1": ["some/sub/package"] },
List of public hoist packages are additive when there are multiple matches for a package. More specific matches are appended to previous matches. | {} |
+| dev | If True, only install devDependencies | False |
+| no_optional | If True, optionalDependencies are not installed.
Currently npm_translate_lock behaves differently from pnpm in that is downloads all optionaDependencies while pnpm doesn't download optionalDependencies that are not needed for the platform pnpm is run on. See https://github.com/pnpm/pnpm/pull/3672 for more context. | False |
+| run_lifecycle_hooks | Sets a default value for lifecycle_hooks if * not already set. Set this to False to disable lifecycle hooks. | True |
+| lifecycle_hooks | A dict of package names to list of lifecycle hooks to run for that package.
By default the preinstall, install and postinstall hooks are run if they exist. This attribute allows the default to be overridden for packages to run prepare.
List of hooks are not additive. The most specific match wins.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | {} |
+| lifecycle_hooks_envs | Environment variables set for the lifecycle hooks actions on npm packages. The environment variables can be defined per package by package name or globally using "*". Variables are declared as key/value pairs of the form "key=value". Multiple matches are additive.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | {} |
+| lifecycle_hooks_exclude | A list of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to not run any lifecycle hooks on.
Equivalent to adding <value>: [] to lifecycle_hooks.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | [] |
+| lifecycle_hooks_execution_requirements | Execution requirements applied to the preinstall, install and postinstall lifecycle hooks on npm packages.
The execution requirements can be defined per package by package name or globally using "*".
Execution requirements are not additive. The most specific match wins.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | {} |
+| lifecycle_hooks_no_sandbox | If True, a "no-sandbox" execution requirement is added to all lifecycle hooks unless overridden by lifecycle_hooks_execution_requirements.
Equivalent to adding "*": ["no-sandbox"] to lifecycle_hooks_execution_requirements.
This defaults to True to limit the overhead of sandbox creation and copying the output TreeArtifacts out of the sandbox.
Read more: [lifecycles](/docs/pnpm.md#lifecycles) | True |
+| bins | Binary files to create in node_modules/.bin for packages in this lock file.
For a given package, this is typically derived from the "bin" attribute in the package.json file of that package.
For example:
bins = { "@foo/bar": { "foo": "./foo.js", "bar": "./bar.js" }, }
Dicts of bins not additive. The most specific match wins.
In the future, this field may be automatically populated from information in the pnpm lock file. That feature is currently blocked on https://github.com/pnpm/pnpm/issues/5131. | {} |
+| verify_node_modules_ignored | node_modules folders in the source tree should be ignored by Bazel.
This points to a .bazelignore file to verify that all nested node_modules directories pnpm will create are listed.
See https://github.com/bazelbuild/bazel/issues/8106 | None |
+| verify_patches | Label to a patch list file.
Use this in together with the list_patches macro to guarantee that all patches in a patch folder are included in the patches attribute.
For example:
verify_patches = "//patches:patches.list",
In your patches folder add a BUILD.bazel file containing. load("@aspect_rules_js//npm:repositories.bzl", "list_patches")
list_patches( name = "patches", out = "patches.list", )
Once you have created this file, you need to create an empty patches.list file before generating the first list. You can do this by running touch patches/patches.list
Finally, write the patches file at least once to make sure all patches are listed. This can be done by running bazel run //patches:patches_update.
See the list_patches documentation for further info. NOTE: if you would like to customize the patches directory location, you can set a flag in the .npmrc. Here is an example of what this might look like # Set the directory for pnpm when patching # https://github.com/pnpm/pnpm/issues/6508#issuecomment-1537242124 patches-dir=bazel/js/patches
If you do this, you will have to update the verify_patches path to be this path instead of //patches like above. | None |
+| quiet | Set to False to print info logs and output stdout & stderr of pnpm lock update actions to the console. | True |
+| external_repository_action_cache | The location of the external repository action cache to write to when update_pnpm_lock = True. | ".aspect/rules/external_repository_action_cache" |
+| link_workspace | The workspace name where links will be created for the packages in this lock file.
This is typically set in rule sets and libraries that vendor the starlark generated by npm_translate_lock so the link_workspace passed to npm_import is set correctly so that links are created in the external repository and not the user workspace.
Can be left unspecified if the link workspace is the user workspace. | None |
+| pnpm_version | pnpm version to use when generating the @pnpm repository. Set to None to not create this repository. | "8.7.6" |
+| register_copy_directory_toolchains | if True, @aspect_bazel_lib//lib:repositories.bzl register_copy_directory_toolchains() is called if the toolchain is not already registered | True |
+| register_copy_to_directory_toolchains | if True, @aspect_bazel_lib//lib:repositories.bzl register_copy_to_directory_toolchains() is called if the toolchain is not already registered | True |
+| npm_package_target_name | The name of linked npm_package targets. When npm_package targets are linked as pnpm workspace packages, the name of the target must align with this value.
The {dirname} placeholder is replaced with the directory name of the target.
By default the directory name of the target is used.
Default: {dirname} | "{dirname}" |
+| package_json | Deprecated.
Add all package.json files that are part of the workspace to data instead. | None |
+| warn_on_unqualified_tarball_url | Deprecated. Will be removed in next major release. | None |
| kwargs | Internal use only | none |
diff --git a/examples/js_library/two/tsc-docs.md b/examples/js_library/two/tsc-docs.md
index 2814eaa81..a44682939 100644
--- a/examples/js_library/two/tsc-docs.md
+++ b/examples/js_library/two/tsc-docs.md
@@ -4,6 +4,7 @@ Simple macro exposing the typescript tsc binary.
Most users should use ts_project from aspect-build/rules_ts instead.
+
## tsc
@@ -20,7 +21,7 @@ tsc(name, args, name | -
| none |
-| args | -
| `["-p", "tsconfig.json"]` |
+| args | -
| ["-p", "tsconfig.json"] |
| kwargs | -
| none |
diff --git a/examples/macro/mocha-docs.md b/examples/macro/mocha-docs.md
index 48e83bb61..6519a0b47 100644
--- a/examples/macro/mocha-docs.md
+++ b/examples/macro/mocha-docs.md
@@ -19,9 +19,9 @@ mocha_test(name, srcs<
| :------------- | :------------- | :------------- |
| name | -
| none |
| srcs | -
| none |
-| args | -
| `[]` |
-| data | -
| `[]` |
-| env | -
| `{}` |
+| args | -
| [] |
+| data | -
| [] |
+| env | -
| {} |
| kwargs | -
| none |
diff --git a/js/dev_repositories.bzl b/js/dev_repositories.bzl
index 5dd03a696..139c22ab8 100644
--- a/js/dev_repositories.bzl
+++ b/js/dev_repositories.bzl
@@ -35,8 +35,8 @@ def rules_js_dev_dependencies():
http_archive(
name = "io_bazel_stardoc",
- sha256 = "62bd2e60216b7a6fec3ac79341aa201e0956477e7c8f6ccc286f279ad1d96432",
- urls = ["https://github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz"],
+ sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+ urls = ["https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz"],
)
http_archive(