@aspect_rules_js//contrib/nextjs:defs.bzl

Utilities for building Next.js applications with Bazel and rules_js.

All invocations of Next.js are done through a next_js_binary target passed into the macros.
This is normally generated once alongside the package.json containing the next dependency:

load("@npm//:next/package_json.bzl", next_bin = "bin")

next_bin.next_binary(
    name = "next_js_binary",
    visibility = ["//visibility:public"],
)

The next binary is then passed into the macros, for example:

nextjs_build(
    name = "next",
    config = "next.config.mjs",
    srcs = glob(["src/**"]),
    next_js_binary = "//:next_js_binary",
)

Macros

There are two sets of macros for building Next.js applications: standard and standalone.

Standard

nextjs(): wrap the build+dev+start targets
nextjs_build(): the Next.js build command
nextjs_dev(): the Next.js dev command
nextjs_start(): the Next.js start command,
accepting a Next.js build artifact to start

Standalone

For standalone applications:

nextjs_standalone_build(): the Next.js build command,
configured for a standalone application within bazel
nextjs_standalone_server(): constructs a standalone Next.js server js_binary following the
standalone directory structure guidelines

Functions & Macros

nextjs

Generates Next.js build, dev & start targets.

{name} - a Next.js production bundle
{name}.dev - a Next.js devserver
{name}.start - a Next.js prodserver

Use this macro in the BUILD file at the root of a next app where the next.config.mjs
file is located.

For example, a target such as //app:next in app/BUILD.bazel

next(
    name = "next",
    config = "next.config.mjs",
    srcs = glob(["src/**"]),
    data = [
        "//:node_modules/next",
        "//:node_modules/react-dom",
        "//:node_modules/react",
        "package.json",
    ],
    next_js_binary = "//:next_js_binary",
)

will create the targets:

//app:next
//app:next.dev
//app:next.start

To build the above next app, equivalent to running next build outside Bazel:

bazel build //app:next

To run the development server in watch mode with
ibazel, equivalent to running
next dev outside Bazel:

ibazel run //app:next.dev

To run the production server in watch mode with
ibazel, equivalent to running
next start outside Bazel:

ibazel run //app:next.start

Parameters

`*name`	the name of the build target
`*srcs`	Source files to include in build & dev targets. Typically these are source files or transpiled source files in Next.js source folders such as `pages`, `public` & `styles`.
`*next_js_binary`	The next `js_binary` target to use for running Next.js Typically this is a js_binary target created using `bin` loaded from the `package_json.bzl` file of the npm package. See main docstring above for example usage.
`config`	the Next.js config file. Typically `next.config.mjs`. Default: `"next.config.mjs"`
`data`	Data files to include in all targets. These are typically npm packages required for the build & configuration files such as package.json and next.config.js. Default: `[]`
`serve_data`	Data files to include in devserver targets Default: `[]`
`kwargs`	Other attributes passed to all targets such as `tags`.

nextjs_build

Build the Next.js production artifact.

See https://nextjs.org/docs/pages/api-reference/cli/next#build

Parameters

`*name`	the name of the build target
`*config`	the Next.js config file
`*srcs`	the sources to include in the build, including any transitive deps
`*next_js_binary`	The next `js_binary` target to use for running Next.js Typically this is a js_binary target created using `bin` loaded from the `package_json.bzl` file of the npm package. See main docstring above for example usage.
`data`	the data files to include in the build Default: `[]`
`kwargs`	Other attributes passed to all targets such as `tags`, env

nextjs_start

Run the Next.js production server for an app.

See https://nextjs.org/docs/pages/api-reference/cli/next#next-start-options

Parameters

`*name`	the name of the build target
`*config`	the Next.js config file
`*app`	the pre-compiled Next.js application, typically the output of `nextjs_build`
`*next_js_binary`	The next `js_binary` target to use for running Next.js Typically this is a js_binary target created using `bin` loaded from the `package_json.bzl` file of the npm package. See main docstring above for example usage.
`data`	additional server data Default: `[]`
`kwargs`	Other attributes passed to all targets such as `tags`, env

nextjs_dev

Run the Next.js development server.

See https://nextjs.org/docs/pages/api-reference/cli/next#next-dev-options

Parameters

`*name`	the name of the build target
`*config`	the Next.js config file
`*srcs`	the sources to include in the build, including any transitive deps
`*data`	additional devserver runtime data
`*next_js_binary`	The next `js_binary` target to use for running Next.js Typically this is a js_binary target created using `bin` loaded from the `package_json.bzl` file of the npm package. See main docstring above for example usage.
`kwargs`	Other attributes passed to all targets such as `tags`, env

nextjs_standalone_build

Compile a standalone Next.js application.

See https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files

NOTE: a next.config.mjs is generated, wrapping the passed config, to overcome Next.js limitation with bazel,
rules_js and pnpm (with hoist=false, as required by rules_js).

Due to the generated next.config.mjs file the nextjs_standalone_build(config) must have a unique name
or file path that does not conflict with standard Next.js config files.

Issues worked around by the generated config include:

Parameters

`*name`	the name of the build target
`*config`	the Next.js config file
`*srcs`	the sources to include in the build, including any transitive deps
`*next_js_binary`	the Next.js binary to use for building
`data`	the data files to include in the build Default: `[]`
`kwargs`	Other attributes passed to all targets such as `tags`, env

nextjs_standalone_server

Configures the output of a standalone Next.js application to be a standalone server binary.

See the Next.js standalone server documentation
for details on the standalone server directory structure.

This function is normally used in conjunction with nextjs_standalone_build to create a standalone
Next.js application. The standalone server is a js_binary target that can be run with bazel run
or deployed in a container image etc.

Parameters

`*name`	the name of the binary target
`*app`	the standalone app directory, typically the output of `nextjs_standalone_build`
`pkg`	the directory server.js is in within the standalone/ directory. This is normally the application path relative to the pnpm-lock.yaml. Default: native.package_name() (for a pnpm-lock.yaml in the root of the workspace) Default: `None`
`data`	runtime data required to run the standalone server. Normally requires `[":node_modules/next", ":node_modules/react"]` which are not included in the Next.js standalone output. Default: `[]`
`kwargs`	additional `js_binary` attributes

@aspect_rules_js//examples/js_library/two:tsc.bzl

Simple macro exposing the typescript tsc binary.

Most users should use ts_project from aspect-build/rules_ts instead.

Functions & Macros

tsc

Parameters

`*name`
`args`	Default: `["-p", "tsconfig.json"]`
`kwargs`

@aspect_rules_js//examples/macro:mocha.bzl

Example macro wrapping the mocha CLI

Functions & Macros

mocha_test

Parameters

`*name`
`*srcs`
`args`	Default: `[]`
`data`	Default: `[]`
`env`	Default: `{}`
`kwargs`

@aspect_rules_js//js:defs.bzl

Rules for running JavaScript programs

Functions & Macros

js_binary

Parameters

kwargs

js_test

Parameters

kwargs

js_run_devserver

Runs a devserver via binary target or command.

A simple http-server, for example, can be setup as follows,

load("@aspect_rules_js//js:defs.bzl", "js_run_devserver")
load("@npm//:http-server/package_json.bzl", http_server_bin = "bin")

http_server_bin.http_server_binary(
    name = "http_server",
)

js_run_devserver(
    name = "serve",
    args = ["."],
    data = ["index.html"],
    tool = ":http_server",
)

A Next.js devserver can be setup as follows,

js_run_devserver(
    name = "dev",
    args = ["dev"],
    command = "./node_modules/.bin/next",
    data = [
        "next.config.js",
        "package.json",
        ":node_modules/next",
        ":node_modules/react",
        ":node_modules/react-dom",
        ":node_modules/typescript",
        "//pages",
        "//public",
        "//styles",
    ],
)

where the ./node_modules/.bin/next bin entry of Next.js is configured in
npm_translate_lock as such,

npm_translate_lock(
    name = "npm",
    bins = {
        # derived from "bin" attribute in node_modules/next/package.json
        "next": {
            "next": "./dist/bin/next",
        },
    },
    pnpm_lock = "//:pnpm-lock.yaml",
)

and run in watch mode using ibazel with
ibazel run //:dev.

The devserver specified by either tool or command is run in a custom sandbox that is more
compatible with devserver watch modes in Node.js tools such as Webpack and Next.js.

The custom sandbox is populated with the default outputs of all targets in data
as well as transitive sources & npm links.

As an optimization, package store files are explicitly excluded from the sandbox since the npm
links will point to the package store in the execroot and Node.js will follow those links as it
does within the execroot. As a result, rules_js npm package link targets such as
//:node_modules/next are handled efficiently. Since these targets are symlinks in the output
tree, they are recreated as symlinks in the custom sandbox and do not incur a full copy of the
underlying npm packages.

Supports running with ibazel.
Only data files that change on incremental builds are synchronized when running with ibazel.

Note that the use of alias targets is not supported by ibazel: https://github.com/bazelbuild/bazel-watcher/issues/100

Parameters

`*name`	A unique name for this target.
`tool`	The devserver binary target to run. Only one of `command` or `tool` may be specified. Default: `None`
`command`	The devserver command to run. For example, this could be the bin entry of an npm package that is included in data such as `./node_modules/.bin/next`. Using the bin entry of next, for example, resolves issues with Next.js and React being found in multiple node_modules trees when next is run as an encapsulated `js_binary` tool. Only one of `command` or `tool` may be specified. Default: `None`
`grant_sandbox_write_permissions`	If set, write permissions is set on all files copied to the custom sandbox. This can be useful to support some devservers such as Next.js which may, under some circumstances, try to modify files when running. See https://github.com/aspect-build/rules_js/issues/935 for more context. Default: `False`
`use_execroot_entry_point`	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. 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. Default: `True`
`allow_execroot_entry_point_with_no_copy_data_to_bin`	Turn off validation that the `js_binary` tool has `copy_data_to_bin` set to True when `use_execroot_entry_point` is set to True. See `use_execroot_entry_point` doc for more info. Default: `False`
`kwargs`	All other args from `js_binary` except for `entry_point` which is set implicitly. `entry_point` is set implicitly by `js_run_devserver` and cannot be overridden. See https://docs.aspect.build/rules/aspect_rules_js/docs/js_binary

js_run_binary

Wrapper around @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 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 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 repository name; equivalent to ctx.workspace_name of the js_run_binary target's rule context

Parameters

`*name`	Target name
`*tool`	The tool to run in the action. Should be a `js_binary` rule. Use Aspect bazel-lib's run_binary (https://github.com/bazel-contrib/bazel-lib/blob/main/lib/run_binary.bzl) for other *_binary rule types.
`env`	Environment variables of the action. Subject to `$(location)` and make variable expansion. Default: `{}`
`srcs`	Additional inputs of the action. These labels are available for `$(location)` expansion in `args` and `env`. Default: `[]`
`outs`	Output files generated by the action. These labels are available for `$(location)` expansion in `args` and `env`. Default: `[]`
`out_dirs`	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`. Default: `[]`
`args`	Command line arguments of the binary. Subject to `$(location)` and make variable expansion. Default: `[]`
`chdir`	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. Default: `None`
`stdout`	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. Default: `None`
`stderr`	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. Default: `None`
`exit_code_out`	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. Default: `None`
`silent_on_success`	produce no output on stdout nor stderr when program exits with status code 0. This makes node binaries match the expected bazel paradigm. Default: `True`
`use_execroot_entry_point`	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. Default: `True`
`copy_srcs_to_bin`	When True, all srcs files are copied to the output tree that are not already there. Default: `True`
`include_sources`	see `js_info_files` documentation Default: `True`
`include_types`	see `js_info_files` documentation Default: `False`
`include_transitive_sources`	see `js_info_files` documentation Default: `True`
`include_transitive_types`	see `js_info_files` documentation Default: `False`
`include_npm_sources`	see `js_info_files` documentation Default: `True`
`log_level`	Set the logging level of the `js_binary` tool. This overrides the log level set on the `js_binary` tool target. Default: `None`
`mnemonic`	A one-word description of the action, for example, CppCompile or GoLink. Default: `"JsRunBinary"`
`progress_message`	Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. Default: `None`
`execution_requirements`	Information for scheduling the action. For example, `execution_requirements = { "no-cache": "1", },` See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. Default: `None`
`stamp`	Whether to include build status files as inputs to the tool. Possible values: `stamp = 0 (default)`: Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in `--stamp` builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed `stamp` attribute.) `stamp = 1`: Always include build status files as inputs to the tool, even in --nostamp builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. `stamp = -1`: Inclusion of build status files as inputs is controlled by the --[no]stamp flag. Stamped targets are not rebuilt unless their dependencies change. Default value is `0` since the majority of js_run_binary targets in a build graph typically do not use build status files and including them for all js_run_binary actions whenever `--stamp` is set would result in invalidating the entire graph and would prevent cache hits. Stamping is typically done in terminal targets when building release artifacts and stamp should typically be set explicitly in these targets to `-1` so it is enabled when the `--stamp` flag is set. When stamping is enabled, an additional two environment variables will be set for the action: - `BAZEL_STABLE_STATUS_FILE` - `BAZEL_VOLATILE_STATUS_FILE` These files can be read and parsed by the action, for example to pass some values to a bundler. Default: `0`
`patch_node_fs`	Patch the to Node.js `fs` API (https://nodejs.org/api/fs.html) for this node program to prevent the program from following symlinks out of the execroot, runfiles and the sandbox. When enabled, `js_binary` patches the Node.js sync and async `fs` API functions `lstat`, `readlink`, `realpath`, `readdir` and `opendir` so that the node program being run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox, these patches prevent the program being run from resolving symlinks out of the sandbox. When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior. Default: `True`
`allow_execroot_entry_point_with_no_copy_data_to_bin`	Turn off validation that the `js_binary` tool has `copy_data_to_bin` set to True when `use_execroot_entry_point` is set to True. See `use_execroot_entry_point` doc for more info. Default: `False`
`use_default_shell_env`	Passed to the underlying ctx.actions.run. May introduce non-determinism when True; use with care! See e.g. https://github.com/bazelbuild/bazel/issues/4912 Refer to https://bazel.build/rules/lib/builtins/actions#run for more details. Default: `False`
`kwargs`	Additional arguments

Rules

js_library

A library of JavaScript sources. Provides JsInfo, the primary provider used in rules_js
and derivative rule sets.

Declaration files are handled separately from sources since they are generally not needed at
runtime and build rules, such as ts_project, are optimal in their build graph if they only depend
on types from deps since these they don't need the JavaScript source files from deps to
typecheck.

Linked npm dependences are also handled separately from sources since not all rules require them and it
is optimal for these rules to not depend on them in the build graph.

NB: js_library copies all source files to the output tree before providing them in JsInfo. See
https://github.com/aspect-build/rules_js/tree/dbb5af0d2a9a2bb50e4cf4a96dbc582b27567155/docs#javascript
for more context on why we do this.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`srcs`	`list of labels`	Source files that are included in this library. This includes all your checked-in code and any generated source files. The transitive npm dependencies, transitive sources & runfiles of targets in the `srcs` attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which is output by or has a runtime dependency on this target. Source files that are JSON files, declaration files or directory artifacts will be automatically provided as "types" available to downstream rules for type checking. To explicitly provide source files as "types" available to downstream rules for type checking that do not match these criteria, move those files to the `types` attribute instead. Default: `[]`
`types`	`list of labels`	Same as `srcs` except all files are also provided as "types" available to downstream rules for type checking. For example, a js_library with only `.js` files that are intended to be imported as `.js` files by downstream type checking rules such as `ts_project` would list those files in `types`: `js_library( name = "js_lib", types = ["index.js"], )` Default: `[]`
`deps`	`list of labels`	Dependencies of this target. This may include other js_library targets or other targets that provide JsInfo The transitive npm dependencies, transitive sources & runfiles of targets in the `deps` attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which is output by or has a runtime dependency on this target. If this list contains linked npm packages, npm package store targets or other targets that provide `JsInfo`, `NpmPackageStoreInfo` providers are gathered from `JsInfo`. This is done directly from the `npm_package_store_infos` field of these. For linked npm package targets, the underlying `npm_package_store` target(s) that back the links are used. Gathered `NpmPackageStoreInfo` providers are propagated to the direct dependencies of downstream linked targets. NB: Linked npm package targets that are "dev" dependencies do not forward their underlying `npm_package_store` target(s) through `npm_package_store_infos` and will therefore not be propagated to the direct dependencies of downstream linked targets. npm packages that come in from `npm_translate_lock` are considered "dev" dependencies if they are have `dev: true` set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all `package.json` files within the pnpm workspace. This behavior is intentional to mimic how `devDependencies` work in published npm packages. Default: `[]`
`data`	`list of labels`	Runtime dependencies to include in binaries/tests that depend on this target. The transitive npm dependencies, transitive sources, default outputs and runfiles of targets in the `data` attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which has a runtime dependency on this target. If this list contains linked npm packages, npm package store targets or other targets that provide `JsInfo`, `NpmPackageStoreInfo` providers are gathered from `JsInfo`. This is done directly from the `npm_package_store_infos` field of these. For linked npm package targets, the underlying `npm_package_store` target(s) that back the links are used. Gathered `NpmPackageStoreInfo` providers are propagated to the direct dependencies of downstream linked targets. NB: Linked npm package targets that are "dev" dependencies do not forward their underlying `npm_package_store` target(s) through `npm_package_store_infos` and will therefore not be propagated to the direct dependencies of downstream linked targets. npm packages that come in from `npm_translate_lock` are considered "dev" dependencies if they are have `dev: true` set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all `package.json` files within the pnpm workspace. This behavior is intentional to mimic how `devDependencies` work in published npm packages. Default: `[]`
`no_copy_to_bin`	`list of labels`	List of files to not copy to the Bazel output tree when `copy_data_to_bin` is True. This is useful for exceptional cases where a `copy_to_bin` is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See `copy_data_to_bin` docstring for more info. Default: `[]`
`copy_data_to_bin`	`boolean`	When True, `data` files are copied to the Bazel output tree before being passed as inputs to runfiles. Default: `True`

js_info_files

Gathers files from the JsInfo providers from targets in srcs and provides them as default outputs.

This helper rule is used by the js_run_binary macro.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`srcs`	`list of labels`	List of targets to gather files from. Default: `[]`
`include_sources`	`boolean`	When True, `sources` from `JsInfo` providers in `srcs` targets are included in the default outputs of the target. Default: `True`
`include_transitive_sources`	`boolean`	When True, `transitive_sources` from `JsInfo` providers in `srcs` targets are included in the default outputs of the target. Default: `True`
`include_types`	`boolean`	When True, `types` from `JsInfo` providers in `srcs` targets are included in the default outputs of the target. Defaults to False since types are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. NB: These are types from direct `srcs` dependencies only. You may also need to set `include_transitive_types` to True. Default: `False`
`include_transitive_types`	`boolean`	When True, `transitive_types` from `JsInfo` providers in `srcs` targets are included in the default outputs of the target. Defaults to False since types are generally not needed at runtime and introducing them could slow down developer round trip time due to having to generate typings on source file changes. Default: `False`
`include_npm_sources`	`boolean`	When True, files in `npm_sources` from `JsInfo` providers in `srcs` targets are included in the default outputs of the target. `transitive_files` from `NpmPackageStoreInfo` providers in `srcs` targets are also included in the default outputs of the target. Default: `True`

js_image_layer

Create container image layers from js_binary targets.

By design, js_image_layer doesn't have any preference over which rule assembles the container image.
This means the downstream rule (oci_image from rules_oci
or container_image from rules_docker) must
set a proper workdir and cmd to for the container work.

A proper cmd usually looks like /[ js_image_layer 'root' ]/[ package name of js_image_layer 'binary' target ]/[ name of js_image_layer 'binary' target ],
unless you have a custom launcher script that invokes the entry_point of the js_binary in a different path.

On the other hand, workdir has to be set to the "runfiles tree root" which would be exactly cmd but with .runfiles/[ name of the workspace ] suffix.
When using bzlmod then name of the local workspace is always _main. If workdir is not set correctly, some attributes such as chdir might not work properly.

js_image_layer creates up to 5 layers depending on what files are included in the runfiles of the provided
binary target.

node layer contains the Node.js toolchain
package_store_3p layer contains all 3p npm deps in the node_modules/.aspect_rules_js package store
package_store_1p layer contains all 1p npm deps in the node_modules/.aspect_rules_js package store
node_modules layer contains all node_modules/* symlinks which point into the package store
app layer contains all files that don't fall into any of the above layers

If no files are found in the runfiles of the binary target for one of the layers above, that
layer is not generated. All generated layer tarballs are provided as DefaultInfo files.

The rules_js node_modules/.aspect_rules_js package store follows the same pattern as the pnpm
node_modules/.pnpm virtual store. For more information see https://pnpm.io/symlinked-node-modules-structure.

js_image_layer also provides an OutputGroupInfo with outputs for each of the layers above which
can be used to reference an individual layer with using filegroup with output_group. For example,

js_image_layer(
    name = "layers",
    binary = ":bin",
    root = "/app",
)

filegroup(
    name = "app_tar",
    srcs = [":layers"],
    output_group = "app",
)

WARNING: The structure of the generated layers are not subject to semver guarantees and may change without a notice.
However, it is guaranteed to work when all generated layers are provided together in the order specified above.

js_image_layer supports transitioning to specific platform to allow building multi-platform container images.

A partial example using rules_oci with transition to linux/amd64 platform.

load("@aspect_rules_js//js:defs.bzl", "js_binary", "js_image_layer")
load("@rules_oci//oci:defs.bzl", "oci_image")

js_binary(
    name = "bin",
    entry_point = "main.js",
)

platform(
    name = "amd64_linux",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
)

js_image_layer(
    name = "layers",
    binary = ":bin",
    platform = ":amd64_linux",
    root = "/app",
)

oci_image(
    name = "image",
    cmd = ["/app/bin"],
    entrypoint = ["bash"],
    tars = [
        ":layers"
    ],
    workdir = "/app/bin.runfiles/_main",
)

A partial example using rules_oci to create multi-platform images.

load("@aspect_rules_js//js:defs.bzl", "js_binary", "js_image_layer")
load("@rules_oci//oci:defs.bzl", "oci_image", "oci_image_index")

js_binary(
    name = "bin",
    entry_point = "main.js",
)

[
    platform(
        name = "linux_{}".format(arch),
        constraint_values = [
            "@platforms//os:linux",
            "@platforms//cpu:{}".format(arch if arch != "amd64" else "x86_64"),
        ],
    )

    js_image_layer(
        name = "{}_layers".format(arch),
        binary = ":bin",
        platform = ":linux_{arch}",
        root = "/app",
    )

    oci_image(
        name = "{}_image".format(arch),
        cmd = ["/app/bin"],
        entrypoint = ["bash"],
        tars = [
            ":{}_layers".format(arch)
        ],
        workdir = "/app/bin.runfiles/_main",
    )

    for arch in ["amd64", "arm64"]
]

oci_image_index(
    name = "image",
    images = [
        ":arm64_image",
        ":amd64_image"
    ]
)

Performance

For better performance, it is recommended to split the large parts of a js_binary to have a separate layer.

The matching order for layer groups is as follows:

layer_groups are checked in order first
If no match is found for layer_groups, the default layer groups are checked.
Any remaining files are placed into the app layer.

The default layer groups are as follows and always created.

{
    "node": "/js/private/node-patches/|/bin/nodejs/",
    "package_store_1p": "\.aspect_rules_js/.*@0\.0\.0/node_modules",
    "package_store_3p": "\.aspect_rules_js/.*/node_modules",
    "node_modules": "/node_modules/",
    "app": "", # empty means just match anything.
}

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*binary`	`label`	Label to an js_binary target
`root`	`string`	Path where the files from js_binary will reside in. eg: /apps/app1 or /app Default: `""`
`owner`	`string`	Owner of the entries, in `GID:UID` format. By default `0:0` (root, root) is used. Default: `"0:0"`
`directory_mode`	`string`	Mode of the directories, in `octal` format. By default `0755` is used. Default: `"0755"`
`file_mode`	`string`	Mode of the files, in `octal` format. By default `0555` is used. Default: `"0555"`
`compression`	`string`	Compression algorithm. See https://github.com/bazel-contrib/bazel-lib/blob/bdc6ade0ba1ebe88d822bcdf4d4aaa2ce7e2cd37/lib/private/tar.bzl#L29-L39 Default: `"gzip"`
`platform`	`label`	Platform to transition. Default: `None`
`preserve_symlinks`	`string`	Preserve symlinks for entries matching the pattern. By default symlinks within the `node_modules` is preserved. Default: `"./node_modules/."`
`layer_groups`	`dictionary: String → String`	Layer groups to create. These are utilized to categorize files into distinct layers, determined by their respective paths. The expected format for each entry is "<key>": "<value>", where <key> MUST be a valid Bazel and JavaScript identifier (alphanumeric characters), and <value> MAY be either an empty string (signifying a universal match) or a valid regular expression. Default: `{}`

@aspect_rules_js//js:libs.bzl

Starlark libraries for building derivative rules

Functions & Macros

js_binary_lib.create_launcher

Parameters

`*ctx`
`*log_prefix_rule_set`
`*log_prefix_rule`
`fixed_args`	Default: `[]`
`fixed_env`	Default: `{}`

js_binary_lib.implementation

Parameters

*ctx

js_library_lib.implementation

Parameters

*ctx

js_lib_helpers.envs_for_log_level

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

Parameters

*log_level

The log level string value

js_lib_helpers.gather_files_from_js_infos

Gathers files from JsInfo providers.

Parameters

`*targets`	list of target to gather from
`*include_sources`	see js_info_files documentation
`*include_types`	see js_info_files documentation
`*include_transitive_sources`	see js_info_files documentation
`*include_transitive_types`	see js_info_files documentation
`*include_npm_sources`	see js_info_files documentation

js_lib_helpers.gather_npm_package_store_infos

Gathers NpmPackageStoreInfo providers from the list of targets

Parameters

*targets

the list of targets to gather from

js_lib_helpers.gather_npm_sources

Gathers npm sources from a list of srcs and deps targets

Parameters

`*srcs`	source targets; these typically come from the `srcs` and/or `data` attributes of a rule
`*deps`	dep targets; these typically come from the `deps` attribute of a rule

js_lib_helpers.gather_runfiles

Creates a runfiles object containing files in sources, default outputs from data and transitive runfiles from data & deps.

As a defense in depth against data & deps targets not supplying all required runfiles, also
gathers the transitive sources & transitive npm sources from the JsInfo providers of
data & deps targets.

See https://bazel.build/extending/rules#runfiles for more info on providing runfiles in build rules.

Parameters

`*ctx`	the rule context
`sources`	depset which should be included in runfiles Default: `None`
`data`	list of data targets; default outputs and transitive runfiles are gather from these targets See https://bazel.build/reference/be/common-definitions#typical.data and https://bazel.build/concepts/dependencies#data-dependencies for more info and guidance on common usage of the `data` attribute in build rules. Default: `[]`
`deps`	list of dependency targets; only transitive runfiles are gather from these targets Default: `[]`
`data_files`	a list of data files which should be included in runfiles Data files that are source files are copied to the Bazel output tree when `copy_data_files_to_bin` is set to `True`. Default: `[]`
`copy_data_files_to_bin`	When True, `data` files that are source files and are copied to the Bazel output tree before being passed to returned runfiles. Default: `False`
`no_copy_to_bin`	List of files to not copy to the Bazel output tree when `copy_data_to_bin` is True. This is useful for exceptional cases where a `copy_data_files_to_bin` is not possible or not suitable for an input file such as a file in an external repository. In most cases, this option is not needed. See `copy_data_files_to_bin` docstring for more info. Default: `[]`

js_lib_helpers.gather_transitive_sources

Gathers transitive sources from a list of direct sources and targets

Parameters

`*sources`	list of direct sources which should be included in `transitive_sources`
`*targets`	list of targets to gather `transitive_sources` from `JsInfo`

js_lib_helpers.gather_transitive_types

Gathers transitive types from a list of direct types and targets

Parameters

`*types`	list of direct sources which should be included in `transitive_types`
`*targets`	list of targets to gather `transitive_types` from `JsInfo`

@aspect_rules_js//js:providers.bzl

Providers for building derivative rules

Functions & Macros

js_info

Construct a JsInfo.

Parameters

`*target`	See JsInfo documentation
`sources`	See JsInfo documentation Default: `None`
`types`	See JsInfo documentation Default: `None`
`transitive_sources`	See JsInfo documentation Default: `None`
`transitive_types`	See JsInfo documentation Default: `None`
`npm_sources`	See JsInfo documentation Default: `None`
`npm_package_store_infos`	See JsInfo documentation Default: `None`

Providers

JsInfo

Encapsulates information provided by rules in rules_js and derivative rule sets

Fields

`target`	The label of target that created this JsInfo
`sources`	A depset of source files produced by the target
`types`	A depset of typings files produced by the target
`transitive_sources`	A depset of source files produced by the target and the target's transitive deps
`transitive_types`	A depset of declaration files produced by the target and the target's transitive deps
`npm_sources`	A depset of files in npm package dependencies of the target and the target's transitive deps
`npm_package_store_infos`	A depset of NpmPackageStoreInfo providers from non-dev npm dependencies of the target and the target's transitive dependencies to use as direct dependencies when linking downstream npm_package targets with npm_link_package

@aspect_rules_js//npm:defs.bzl

Rules for fetching and linking npm dependencies and packaging and linking first-party deps

Functions & Macros

npm_package

A macro that packages sources into a directory (a tree artifact) and provides an NpmPackageInfo.

This target can be used as the src attribute to npm_link_package.

With publishable = True the macro also produces a target [name].publish, that can be run to publish to an npm registry.
Under the hood, this target runs npm publish. You can pass arguments to npm by escaping them from Bazel using a double-hyphen,
for example: bazel run //path/to:my_package.publish -- --tag=next

Files and directories can be arranged as needed in the output directory using
the root_paths, include_srcs_patterns, exclude_srcs_patterns and replace_prefixes attributes.

Filters and transformations are applied in the following order:

include_external_repositories
include_srcs_packages
exclude_srcs_packages
root_paths
include_srcs_patterns
exclude_srcs_patterns
replace_prefixes

For more information each filters / transformations applied, see
the documentation for the specific filter / transformation attribute.

Glob patterns are supported. Standard wildcards (globbing patterns) plus the ** doublestar (aka. super-asterisk)
are supported with the underlying globbing library, https://github.com/bmatcuk/doublestar. This is the same
globbing library used by gazelle. See https://github.com/bmatcuk/doublestar#patterns
for more information on supported globbing patterns.

npm_package makes use of copy_to_directory
(https://docs.aspect.build/rules/bazel_lib/docs/copy_to_directory) under the hood,
adopting its API and its copy action using composition. However, unlike copy_to_directory,
npm_package includes direct and transitive sources and types files from JsInfo providers in srcs
by default. The behavior of including sources and types from JsInfo can be configured
using the include_sources, include_transitive_sources, include_types, include_transitive_types.

The two include*_types options may cause type-check actions to run, which slows down your
development round-trip.

As of rules_js 2.0, the recommended solution for avoiding eager type-checking when linking
1p deps is to link js_library or any JsInfo producing targets directly without the
indirection of going through an npm_package target (see https://github.com/aspect-build/rules_js/pull/1646
for more details).

npm_package can also include npm packages sources and default runfiles from srcs which copy_to_directory does not.
These behaviors can be configured with the include_npm_sourfes and include_runfiles attributes
respectively.

The default include_srcs_packages, [".", "./**"], prevents files from outside of the target's
package and subpackages from being included.

The default exclude_srcs_patterns, of ["node_modules/**", "**/node_modules/**"], prevents
node_modules files from being included.

To stamp the current git tag as the "version" in the package.json file, see
stamped_package_json

Parameters

`*name`	Unique name for this target.
`srcs`	Files and/or directories or targets that provide `DirectoryPathInfo` to copy into the output directory. Default: `[]`
`data`	Runtime / linktime npm dependencies of this npm package. `NpmPackageStoreInfo` providers are gathered from `JsInfo` of the targets specified. Targets can be linked npm packages, npm package store targets or other targets that provide `JsInfo`. This is done directly from the `npm_package_store_infos` field of these. For linked npm package targets, the underlying npm_package_store target(s) that back the links is used. Gathered `NpmPackageStoreInfo` providers are used downstream as direct dependencies of this npm package when linking with `npm_link_package`. Default: `[]`
`args`	Arguments that are passed down to `<name>.publish` target and `npm publish` command. Default: `[]`
`out`	Path of the output directory, relative to this package. Default: `None`
`package`	The package name. If set, should match the `name` field in the `package.json` file for this package. If set, the package name set here will be used for linking if a npm_link_package does not specify a package name. A npm_link_package that specifies a package name will override the value here when linking. If unset, a npm_link_package that references this npm_package must define the package name must be for linking. Default: `""`
`version`	The package version. If set, should match the `version` field in the `package.json` file for this package. If set, a npm_link_package may omit the package version and the package version set here will be used for linking. A npm_link_package that specifies a package version will override the value here when linking. If unset, a npm_link_package that references this npm_package must define the package version must be for linking. Default: `"0.0.0"`
`root_paths`	List of paths (with glob support) that are roots in the output directory. If any parent directory of a file being copied matches one of the root paths patterns specified, the output directory path will be the path relative to the root path instead of the path relative to the file's workspace. If there are multiple root paths that match, the longest match wins. Matching is done on the parent directory of the output file path so a trailing '**' glob patterm will match only up to the last path segment of the dirname and will not include the basename. Only complete path segments are matched. Partial matches on the last segment of the root path are ignored. Forward slashes (`/`) should be used as path separators. A `"."` value expands to the target's package path (`ctx.label.package`). Defaults to `["."]` which results in the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths. Globs are supported (see rule docstring above). Default: `["."]`
`include_external_repositories`	List of external repository names (with glob support) to include in the output directory. Files from external repositories are only copied into the output directory if the external repository they come from matches one of the external repository patterns specified. When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is not included in that path. For example, the following copies `@external_repo//path/to:file` to `path/to/file` within the output directory. `npm_package( name = "dir", include_external_repositories = ["external_*"], srcs = ["@external_repo//path/to:file"], )` Files that come from matching external are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. The external repository name of the file from an external repository is not included in the output directory path and is considered in subsequent filters and transformations. Globs are supported (see rule docstring above). Default: `[]`
`include_srcs_packages`	List of Bazel packages (with glob support) to include in output directory. Files in srcs are only copied to the output directory if the Bazel package of the file matches one of the patterns specified. Forward slashes (`/`) should be used as path separators. A first character of `"."` will be replaced by the target's package path. Defaults to ["./"] which includes sources target's package and subpackages. Files that have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. Globs are supported (see rule docstring above). Default: `["./"]`
`exclude_srcs_packages`	List of Bazel packages (with glob support) to exclude from output directory. Files in srcs are not copied to the output directory if the Bazel package of the file matches one of the patterns specified. Forward slashes (`/`) should be used as path separators. A first character of `"."` will be replaced by the target's package path. Defaults to ["/node_modules/"] which excludes all node_modules folders from the output directory. Files that have do not have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. Globs are supported (see rule docstring above). Default: `[]`
`include_srcs_patterns`	List of paths (with glob support) to include in output directory. Files in srcs are only copied to the output directory if their output directory path, after applying `root_paths`, matches one of the patterns specified. Forward slashes (`/`) should be used as path separators. Defaults to `[""]` which includes all sources. Files that have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. Globs are supported (see rule docstring above). Default: `[""]`
`exclude_srcs_patterns`	List of paths (with glob support) to exclude from output directory. Files in srcs are not copied to the output directory if their output directory path, after applying `root_paths`, matches one of the patterns specified. Forward slashes (`/`) should be used as path separators. Files that do not have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. Globs are supported (see rule docstring above). Default: `["/node_modules/"]`
`replace_prefixes`	Map of paths prefixes (with glob support) to replace in the output directory path when copying files. If the output directory path for a file starts with or fully matches a a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key. The final path segment matched can be a partial match of that segment and only the matching portion will be replaced. If there are multiple keys that match, the longest match wins. Forward slashes (`/`) should be used as path separators. Replace prefix transformation are the final step in the list of filters and transformations. The final output path of a file being copied into the output directory is determined at this step. Globs are supported (see rule docstring above). Default: `{}`
`allow_overwrites`	If True, allow files to be overwritten if the same output file is copied to twice. The order of srcs matters as the last copy of a particular file will win when overwriting. Performance of `npm_package` will be slightly degraded when allow_overwrites is True since copies cannot be parallelized out as they are calculated. Instead all copy paths must be calculated before any copies can be started. Default: `False`
`include_sources`	When True, `sources` from `JsInfo` providers in `srcs` targets are included in the list of available files to copy. Default: `True`
`include_types`	When True, `types` from `JsInfo` providers in `srcs` targets are included in the list of available files to copy. Default: `True`
`include_transitive_sources`	When True, `transitive_sources` from `JsInfo` providers in `srcs` targets are included in the list of available files to copy. Default: `True`
`include_transitive_types`	When True, `transitive_types` from `JsInfo` providers in `srcs` targets are included in the list of available files to copy. Default: `True`
`include_npm_sources`	When True, `npm_sources` from `JsInfo` providers in `srcs` targets are included in the list of available files to copy. Default: `False`
`include_runfiles`	When True, default runfiles from `srcs` targets are included in the list of available files to copy. This may be needed in a few cases: to work-around issues with rules that don't provide everything needed in sources, transitive_sources, types & transitive_types to depend on the runfiles targets that don't use JsInfo NB: The default value will be flipped to False in the next major release as runfiles are not needed in the general case and adding them to the list of files available to copy can add noticeable overhead to the analysis phase in a large repository with many npm_package targets. Default: `False`
`hardlink`	Controls when to use hardlinks to files instead of making copies. Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source. Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files are not recommended since write permissions will be inadvertently removed from sources files. `auto`: hardlinks are used for generated files already in the output tree `off`: all files are copied `on`: hardlinks are used for all files (not recommended) Default: `"auto"`
`publishable`	When True, enable generation of `{name}.publish` target Default: `False`
`verbose`	If true, prints out verbose logs to stdout Default: `False`
`kwargs`	Additional attributes such as `tags` and `visibility`

npm_link_package

"Create a package store entry with the provided source and link to node_modules.

This is a convenience macro that creates both an npm_package_store and a a single npm_link_package_store
to link the package into node_modules/<package>.

A {name}/dir filegroup is also generated that refers to a directory artifact can be used to access
the package directory for creating entry points or accessing files in the package.

Parameters

`*name`	The name of the link target to create if `link` is True. For first-party deps linked across a workspace, the name must match in all packages being linked as it is used to derive the package store link target name.
`*src`	the target to link; may only to be specified when linking in the root package
`deps`	list of npm_package_store; may only to be specified when linking in the root package Default: `{}`
`auto_manual`	whether or not to automatically add a manual tag to the generated targets Links tagged "manual" dy default is desirable so that they are not built by `bazel build ...` if they are unused downstream. For 3rd party deps, this is particularly important so that 3rd party deps are not fetched at all unless they are used. Default: `True`
`visibility`	the visibility of the link target Default: `["//visibility:public"]`
`kwargs`	see attributes of npm_package_store rule

stamped_package_json

Convenience wrapper to set the "version" property in package.json with the git tag.

In unstamped builds (typically those without --stamp) the version will be set to 0.0.0.
This ensures that actions which use the package.json file can get cache hits.

For more information on stamping, read https://docs.aspect.build/rules/bazel_lib/docs/stamping.

Parameters

`*name`	name of the resulting `jq` target, must be "package"
`*stamp_var`	a key from the bazel-out/stable-status.txt or bazel-out/volatile-status.txt files
`kwargs`	additional attributes passed to the jq rule, see https://docs.aspect.build/rules/bazel_lib/docs/jq

@aspect_rules_js//npm:libs.bzl

Starlark libraries for building derivative rules

Functions & Macros

npm_package_lib.implementation

Parameters

*ctx

@aspect_rules_js//npm:providers.bzl

Providers for building derivative rules

Providers

NpmPackageInfo

Provides the sources of an npm package along with the package name and version

Fields

`package`	name of this npm package
`version`	version of this npm package
`src`	the sources of this npm package; either a tarball file, a TreeArtifact or a source directory
`npm_package_store_infos`	A depset of NpmPackageStoreInfo providers from npm dependencies of the package and the packages's transitive deps to use as direct dependencies when linking with npm_link_package

NpmPackageStoreInfo

Provides information about an npm package within the package store of a pnpm-style
symlinked node_modules tree.

See https://pnpm.io/symlinked-node-modules-structure for more information about
symlinked node_modules trees.

Fields

`key`	a unique package store key
`root_package`	package that this npm package store is linked at
`package`	name of this npm package
`version`	version of this npm package
`ref_deps`	dictionary of dependency npm_package_store ref targets
`package_store_directory`	the TreeArtifact of this npm package's package store location
`files`	depset of files that are part of the npm package
`transitive_files`	depset of the files that are part of the npm package and its transitive deps

@aspect_rules_js//npm:repositories.bzl

Repository rules to fetch third-party npm packages

Functions & Macros

list_patches

Write a file containing a list of all patches in the current folder to the source tree.

Use this together with the verify_patches attribute of npm_translate_lock to verify
that all patches in a patch folder are included. This macro stamps a test to ensure the
file stays up to date.

Parameters

`*name`	Name of the target
`out`	Name of file to write to the source tree. If unspecified, `name` is used Default: `None`
`include_patterns`	Patterns to pass to a glob of patch files Default: `[".diff", ".patch"]`
`exclude_package_contents`	Patterns to ignore in a glob of patch files Default: `[]`

pnpm_repository

Import https://npmjs.com/package/pnpm and provide a js_binary to run the tool.

Useful as a way to run exactly the same pnpm as Bazel does, for example with:
bazel run -- @pnpm//:pnpm --dir $PWD

Parameters

`*name`	name of the resulting external repository
`*pnpm_version`	version of pnpm, see https://www.npmjs.com/package/pnpm?activeTab=versions May also be a tuple of (version, integrity) where the integrity value may be fetched like: `curl --silent https://registry.npmjs.org/pnpm \| jq '.versions["8.6.11"].dist.integrity'`
`*include_npm`	if True, include the npm package along with pnpm binary
`*integrity`	integrity hash for the pnpm version (optional)

npm_import

Parameters

`*name`
`*package`
`*integrity`
`*version`
`kwargs`

@aspect_rules_js//platforms/pnpm:index.bzl

Private pnpm related platform info.