Version: 2.0.x

js_run_binary

Runs a js_binary as a build action.

This macro wraps Aspect bazel-lib's run_binary (https://github.com/aspect-build/bazel-lib/blob/main/lib/run_binary.bzl) and adds attributes and features specific to rules_js's js_binary.

Load this with,

load("@aspect_rules_js//js:defs.bzl", "js_run_binary")

Macros and Functions

js_run_binary

Wrapper around @aspect_bazel_lib run_binary that adds convenience attributes for using a js_binary tool.

This rule does not require Bash native.genrule.

The following environment variables are made available to the Node.js runtime based on available Bazel Make variables:

BAZEL_BINDIR: the WORKSPACE-relative bazel bin directory; equivalent to the $(BINDIR) Make variable of the js_run_binary target
BAZEL_COMPILATION_MODE: One of fastbuild, dbg, or opt as set by --compilation_mode; equivalent to $(COMPILATION_MODE) Make variable of the js_run_binary target
BAZEL_TARGET_CPU: the target cpu architecture; equivalent to $(TARGET_CPU) Make variable of the js_run_binary target

The following environment variables are made available to the Node.js runtime based on the rule context:

BAZEL_BUILD_FILE_PATH: the WORKSPACE-relative path to the BUILD file of the bazel target being run; equivalent to ctx.build_file_path of the js_run_binary target's rule context
BAZEL_PACKAGE: the package of the bazel target being run; equivalent to ctx.label.package of the js_run_binary target's rule context
BAZEL_TARGET_NAME: the full label of the bazel target being run; a stringified version of ctx.label of the js_run_binary target's rule context
BAZEL_TARGET: the name of the bazel target being run; equivalent to ctx.label.name of the js_run_binary target's rule context
BAZEL_WORKSPACE: the bazel workspace name; equivalent to ctx.workspace_name of the js_run_binary target's rule context

Example usage (generated):

load("@aspect_rules_js//js:defs.bzl", "js_run_binary")

js_run_binary(
    # Target name
    name = "",
    # The tool to run in the action
    tool = None,
)

name

Required.

Target name

tool

Required.

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.

env

Optional. Default: {}

Environment variables of the action.

Subject to $(location) and make variable expansion.

srcs

Optional. Default: []

Additional inputs of the action.

These labels are available for $(location) expansion in args and env.

outs

Optional. Default: []

Output files generated by the action.

These labels are available for $(location) expansion in args and env.

out_dirs

Optional. Default: []

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

Optional. Default: []

Command line arguments of the binary.

Subject to $(location) and make variable expansion.

chdir

Optional. Default: None

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.

stdout

Optional. Default: None

Output file to capture the stdout of the binary.

This can later be used as an input to another target subject to the same semantics as outs.

If the binary creates outputs and these are declared, they must still be created.

stderr

Optional. Default: None

Output file to capture the stderr of the binary to.

This can later be used as an input to another target subject to the same semantics as outs.

If the binary creates outputs and these are declared, they must still be created.

exit_code_out

Optional. Default: None

Output file to capture the exit code of the binary to.

This 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.

silent_on_success

Optional. Default: True

produce no output on stdout nor stderr when program exits with status code 0.

This makes node binaries match the expected bazel paradigm.

use_execroot_entry_point

Optional. Default: True

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.

copy_srcs_to_bin

Optional. Default: True

When True, all srcs files are copied to the output tree that are not already there.