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/private:js_binary.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.

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/private:js_binary.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.

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


Macros and Functions

js_binary_lib.js_binary_impl

Example usage (generated)

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

js_binary_lib.js_binary_impl(
    ctx = None,
)

ctx