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 rules_js 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 = "",
)

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.

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.

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.

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.

node_options

Options to pass to the node.

https://nodejs.org/api/cli.html


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

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.

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.

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.

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.

node_options

Options to pass to the node.

https://nodejs.org/api/cli.html


Macros and Functions

envs_for_log_level

Returns a list environment variables to set for a given log level

Example usage (generated)

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

envs_for_log_level(
    # The log level string value
    log_level = None,
)

log_level

The log level string value


js_binary_lib.create_launcher

Example usage (generated)

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

js_binary_lib.create_launcher(
    ctx = None,
    log_prefix_rule_set = None,
    log_prefix_rule = None,
)

ctx

log_prefix_rule_set

log_prefix_rule

fixed_args


js_binary_lib.implementation

Example usage (generated)

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

js_binary_lib.implementation(
    ctx = None,
)

ctx