js_run_devserver

Implementation details for js_run_devserver rule

Macros and Functions

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, virtual store files are explicitly excluded from the sandbox since the npm links will point to the virtual 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.

name

Required.

A unique name for this target.

tool

Optional. Default: None

The devserver binary target to run.

Only one of command or tool may be specified.

command

Optional. Default: None

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.

grant_sandbox_write_permissions

Optional. Default: False

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.

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.

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.

allow_execroot_entry_point_with_no_copy_data_to_bin

Optional. Default: False

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.

kwargs

Optional.

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