Rules for running JavaScript programs under Bazel, as tools or with bazel run
or bazel test
.
Load these with
load("@aspect_rules_js//js:defs.bzl", "js_binary", "js_test")
Rules
js_binary
Execute a program in the node.js runtime.
The version of node is determined by Bazel's toolchain selection. In the WORKSPACE you used
nodejs_register_toolchains
to provide options to Bazel. Then Bazel selects from these options
based on the requested target platform. Use the
--toolchain_resolution_debug
Bazel option to see more detail about the selection.
For node_modules resolution support and to prevent node programs for following symlinks back to the user source tree when outside of the sandbox, this rule always copies the entry_point to the output tree (if it is not already there) and run the programs from the entry points's runfiles location.
Data files that are not already in the output tree are also copied there so that node programs can find them when outside of the sandbox and so that they don't follow symlinks back to the user source tree.
TODO: link to rule_js node_package linker design doc
This rules requires that Bazel was run with
--enable_runfiles
.
Example usage (generated)
load("@aspect_rules_js//js:defs.bzl", "js_binary")
js_binary(
# A unique name for this target.
name = "",
# Whether runfiles are enabled in the current build configuration
enable_runfiles = false,
# The main script which is evaluated by node.js
entry_point = "",
# Whether the build is being performed on a Windows host platform
is_windows = false,
)
name
A unique name for this target.
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)"],
)
data
Runtime dependencies of the program.
The transitive closure of the data
dependencies will be available in
the .runfiles folder for this binary/test.
You can use the @bazel/runfiles
npm library to access these files
at runtime.
npm packages are also linked into the .runfiles/node_modules
folder
so they may be resolved directly from runfiles.
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.
entry_point
The main script which is evaluated by node.js
This is the module referenced by the require.main
property in the runtime.
env
Environment variables of the action.
Subject to $(location)
and make variable expansion.
expected_exit_code
The expected exit code.
Can be used to write tests that are expected to fail.
is_windows
Whether the build is being performed on a Windows host platform.
Typical usage of this rule is via a macro which automatically sets this
attribute based on a select()
on @bazel_tools//src/conditions:host_windows
.
node_options
Options to pass to the node.
js_test
Identical to js_binary, but usable under bazel test
.
Example usage (generated)
load("@aspect_rules_js//js:defs.bzl", "js_test")
js_test(
# A unique name for this target.
name = "",
# Whether runfiles are enabled in the current build configuration
enable_runfiles = false,
# The main script which is evaluated by node.js
entry_point = "",
# Whether the build is being performed on a Windows host platform
is_windows = false,
)
name
A unique name for this target.
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)"],
)
data
Runtime dependencies of the program.
The transitive closure of the data
dependencies will be available in
the .runfiles folder for this binary/test.
You can use the @bazel/runfiles
npm library to access these files
at runtime.
npm packages are also linked into the .runfiles/node_modules
folder
so they may be resolved directly from runfiles.
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.
entry_point
The main script which is evaluated by node.js
This is the module referenced by the require.main
property in the runtime.
env
Environment variables of the action.
Subject to $(location)
and make variable expansion.
expected_exit_code
The expected exit code.
Can be used to write tests that are expected to fail.
is_windows
Whether the build is being performed on a Windows host platform.
Typical usage of this rule is via a macro which automatically sets this
attribute based on a select()
on @bazel_tools//src/conditions:host_windows
.
node_options
Options to pass to the node.
Macros and Functions
js_binary_lib.js_binary_impl
Example usage (generated)
load("@aspect_rules_js//js:defs.bzl", "js_binary_lib")
js_binary_lib.js_binary_impl(
ctx = None,
)