js_binary.md

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")

js_binary

js_binary(name, chdir, data, enable_runfiles, entry_point, env, expected_exit_code, node_options,
          verbose)

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 rules_js linker design doc

This rules requires that Bazel was run with --enable_runfiles.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
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	""
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.	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) and make variable expansion.	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
node_options	Options to pass to the node. https://nodejs.org/api/cli.html	List of strings	optional	[]
verbose	Produce verbose output.	Boolean	optional	False

js_test

js_test(name, chdir, data, enable_runfiles, entry_point, env, expected_exit_code, node_options,
        verbose)

Identical to js_binary, but usable under bazel test.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
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	""
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.	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) and make variable expansion.	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
node_options	Options to pass to the node. https://nodejs.org/api/cli.html	List of strings	optional	[]
verbose	Produce verbose output.	Boolean	optional	False

js_binary_lib.create_launcher

js_binary_lib.create_launcher(ctx, log_prefix_rule_set, log_prefix_rule, fixed_args)

PARAMETERS

Name	Description	Default Value
ctx	-	none
log_prefix_rule_set	-	none
log_prefix_rule	-	none
fixed_args	-	[]

js_binary_lib.implementation

js_binary_lib.implementation(ctx)

PARAMETERS

Name	Description	Default Value
ctx	-	none