feat: add flag controlling the default for use_execroot_entry_point

This change introduces the flag
`--@aspect_rules_js//js:use_execroot_entry_point`, which controls the default
behavior of the `use_execroot_entry_point` option on `js_run_binary` and
`js_run_devserver`.

We could like to recommend moving away from enabling
`use_execroot_entry_point`, and this flag provides an easy way to do that at a
global level, while still making it possible to override that on specific
targets if necessary.

I also added CI test runs with
`--@aspect_rules_js//js:use_execroot_entry_point=False` so that we have good
test coverage of both modes. This required explicitly setting
`use_execroot_entry_point` on some targets that only work with one more or the
other.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: acozzette

.aspect/workflows/config.yaml

@@ -94,6 +94,8 @@ workspaces:
                   without: true
             - bazel-9:
                   without: true
+            - bazel-9-no-execroot-entry-point:
+                  without: true
     e2e/pnpm_lockfiles:
         icon: pnpm
         tasks: *e2e_tasks
@@ -117,7 +119,17 @@ workspaces:
         tasks: *e2e_tasks
     e2e/repo_mapping:
         icon: js
-        tasks: *e2e_tasks
+        tasks:
+            - test:
+                  queue: aspect-medium
+            - format:
+                  without: true
+            - buildifier:
+                  without: true
+            # aspect_rules_js is given a different name in this repo, so we
+            # cannot use a flag beginning with --@aspect_rules_js//.
+            - bazel-9-no-execroot-entry-point:
+                  without: true
     e2e/output_paths:
         icon: js
         tasks: *e2e_tasks
@@ -167,6 +179,13 @@ tasks:
               # TODO: change this back to 9.x once this bug is fixed:
               # https://github.com/bazelbuild/bazel/issues/29393
               USE_BAZEL_VERSION: '9.0.2'
+    - test:
+          name: Bazel 9 (no execroot entry point)
+          id: bazel-9-no-execroot-entry-point
+          bazel:
+              flags: ['--test_tag_filters=-skip-on-bazel9', '--@aspect_rules_js//js:use_execroot_entry_point=False']
+          env:
+              USE_BAZEL_VERSION: '9.0.2'
     - format:
           queue: aspect-medium
     - buildifier:

contrib/nextjs/defs.bzl

@@ -202,6 +202,7 @@ def nextjs_build(name, config, srcs, next_js_binary, data = [], **kwargs):
         chdir = native.package_name(),
         mnemonic = "NextJs",
         progress_message = "Compile Next.js app %{label}",
+        use_execroot_entry_point = True,
         **kwargs
     )
 
@@ -327,6 +328,7 @@ def nextjs_standalone_build(name, config, srcs, next_js_binary, data = [], **kwa
         chdir = native.package_name(),
         mnemonic = "NextJs",
         progress_message = "Compile Next.js standalone app %{label}",
+        use_execroot_entry_point = True,
         **kwargs
     )
 

js/BUILD.bazel

@@ -1,6 +1,20 @@
 "Public API"
 
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
+
+# This flag controls the default behavior of the use_execroot_entry_point flag
+# on js_run_binary.
+bool_flag(
+    name = "use_execroot_entry_point",
+    build_setting_default = True,
+    visibility = ["//visibility:public"],
+)
+
+config_setting(
+    name = "_use_execroot_entry_point_true",
+    flag_values = {"use_execroot_entry_point": "True"},
+)
 
 bzl_library(
     name = "defs",

js/private/js_run_binary.bzl

@@ -30,7 +30,7 @@ def js_run_binary(
         stderr = None,
         exit_code_out = None,
         silent_on_success = True,
-        use_execroot_entry_point = True,
+        use_execroot_entry_point = None,
         copy_srcs_to_bin = True,
         include_sources = True,
         include_types = False,
@@ -149,6 +149,9 @@ def js_run_binary(
             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.
 
+            If `None` (the default), the behavior is controlled by the `//js:use_execroot_entry_point` build flag,
+            which defaults to `True`.
+
         copy_srcs_to_bin: When True, all srcs files are copied to the output tree that are not already there.
 
         include_sources: see `js_info_files` documentation
@@ -356,10 +359,10 @@ See https://github.com/aspect-build/rules_js/tree/main/docs#using-binaries-publi
             name = bazel_lib_utils.to_label(name),
         ))
 
-    # Configure run from execroot
-    if use_execroot_entry_point:
-        fixed_env["JS_BINARY__USE_EXECROOT_ENTRY_POINT"] = "1"
-
+    # Configure run from execroot.
+    # When use_execroot_entry_point is None, behavior is controlled by the //js:use_execroot_entry_point flag.
+    execroot_extra_srcs = []
+    if use_execroot_entry_point != False:
         # hoist all runfiles to srcs when running from execroot
         js_runfiles_lib_name = "{}_runfiles_lib".format(name)
         _js_library(
@@ -380,16 +383,33 @@ See https://github.com/aspect-build/rules_js/tree/main/docs#using-binaries-publi
             # Always propagate the testonly attribute
             testonly = kwargs.get("testonly", False),
         )
-        extra_srcs.append(":{}".format(js_runfiles_name))
+
+        if use_execroot_entry_point == True:
+            fixed_env["JS_BINARY__USE_EXECROOT_ENTRY_POINT"] = "1"
+            execroot_extra_srcs = [":{}".format(js_runfiles_name)]
+        else:
+            # None: use the flag to decide at analysis time
+            execroot_extra_srcs = select({
+                Label("//js:_use_execroot_entry_point_true"): [":{}".format(js_runfiles_name)],
+                "//conditions:default": [],
+            })
 
     if allow_execroot_entry_point_with_no_copy_data_to_bin:
         fixed_env["JS_BINARY__ALLOW_EXECROOT_ENTRY_POINT_WITH_NO_COPY_DATA_TO_BIN"] = "1"
 
+    # When use_execroot_entry_point is None, the env var is resolved at analysis time via the flag.
+    # We use a select() only for the conditional portion and merge with | outside of it, so that
+    # a user-supplied env that is itself a select() remains valid on the right-hand side.
+    execroot_env = select({
+        Label("//js:_use_execroot_entry_point_true"): {"JS_BINARY__USE_EXECROOT_ENTRY_POINT": "1"},
+        "//conditions:default": {},
+    }) if use_execroot_entry_point == None else {}
+
     _run_binary(
         name = name,
         tool = tool,
-        env = fixed_env | env,
-        srcs = srcs + extra_srcs,
+        env = fixed_env | execroot_env | env,
+        srcs = srcs + extra_srcs + execroot_extra_srcs,
         outs = outs + extra_outs,
         out_dirs = out_dirs,
         args = args,

js/private/js_run_devserver.bzl

@@ -135,7 +135,7 @@ def js_run_devserver(
         tool = None,
         command = None,
         grant_sandbox_write_permissions = False,
-        use_execroot_entry_point = True,
+        use_execroot_entry_point = None,
         allow_execroot_entry_point_with_no_copy_data_to_bin = False,
         **kwargs):
     """Runs a devserver via binary target or command.
@@ -253,6 +253,9 @@ def js_run_devserver(
             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.
 
+            If `None` (the default), the behavior is controlled by the `//js:use_execroot_entry_point` build flag,
+            which defaults to `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.
 
@@ -267,6 +270,12 @@ def js_run_devserver(
     if kwargs.get("entry_point", None):
         fail("`entry_point` is set implicitly by `js_run_devserver` and cannot be overridden.")
 
+    if use_execroot_entry_point == None:
+        use_execroot_entry_point = select({
+            Label("//js:_use_execroot_entry_point_true"): True,
+            "//conditions:default": False,
+        })
+
     # Allow the js_run_devserver rule to execute to be overridden for tests
     rule_to_execute = kwargs.pop("rule_to_execute", _js_run_devserver)
 

js/private/test/data/BUILD.bazel

@@ -153,6 +153,7 @@ js_test(
 # TEST: js_test(data = js_run_binary(srcs)) ---------------
 js_run_binary(
     name = "run-write-srcs",
+    srcs = ["data.json"],
     outs = ["rb0.json"],
     args = [
         "rb0.json",
@@ -178,6 +179,7 @@ js_test(
 # TEST: js_test(data = js_run_binary(srcs = js_library(srcs))) ----------------
 js_run_binary(
     name = "run-write-js_library-srcs",
+    srcs = ["data.json"],
     outs = ["rb1.json"],
     args = [
         "rb1.json",
@@ -210,6 +212,7 @@ js_binary(
 
 js_run_binary(
     name = "run-write-js_library-data",
+    srcs = ["data.json"],
     outs = ["rb2.json"],
     args = [
         "rb2.json",
@@ -235,6 +238,7 @@ js_test(
 # TEST: js_test(data = js_run_binary(srcs = genrule())) -----------------------
 js_run_binary(
     name = "run-write-generated",
+    srcs = ["data-generated.json"],
     outs = ["rb3.json"],
     args = [
         "rb3.json",
@@ -260,6 +264,7 @@ js_test(
 # TEST: js_test(data = js_run_binary(srcs = genrule(srcs = filegroup))) -------
 js_run_binary(
     name = "run-write-generated-copied",
+    srcs = ["data-copied.json"],
     outs = ["rb4.json"],
     args = [
         "rb4.json",

js/private/test/js_run_binary/BUILD.bazel

@@ -0,0 +1,86 @@
+load("@bazel_lib//lib:testing.bzl", "assert_contains")
+load("@bazel_lib//lib:transitions.bzl", "platform_transition_filegroup")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("//js:defs.bzl", "js_binary", "js_run_binary")
+
+# Verify that dependencies passed via the srcs parameter are always built for
+# the target platform, unlike the tool parameter and its dependencies.
+# We use a select() on the OS to produce a platform-specific file, then
+# transition to three different target platforms and assert the contents match.
+write_file(
+    name = "gen_os_name",
+    out = "os_name.txt",
+    content = select({
+        "@platforms//os:linux": ["linux"],
+        "@platforms//os:macos": ["macos"],
+        "@platforms//os:windows": ["windows"],
+        "//conditions:default": ["other"],
+    }),
+    tags = ["manual"],
+)
+
+platform(
+    name = "linux",
+    constraint_values = ["@platforms//os:linux"],
+)
+
+platform(
+    name = "macos",
+    constraint_values = ["@platforms//os:macos"],
+)
+
+platform(
+    name = "windows",
+    constraint_values = ["@platforms//os:windows"],
+)
+
+js_binary(
+    name = "read_file",
+    entry_point = "read_file.mjs",
+)
+
+js_run_binary(
+    name = "gen_target_os",
+    srcs = [":os_name.txt"],
+    args = ["$(rootpath :os_name.txt)"],
+    stdout = "target_os.txt",
+    tags = ["manual"],
+    tool = ":read_file",
+    use_execroot_entry_point = False,
+)
+
+platform_transition_filegroup(
+    name = "target_os_linux",
+    srcs = [":gen_target_os"],
+    target_platform = ":linux",
+)
+
+platform_transition_filegroup(
+    name = "target_os_macos",
+    srcs = [":gen_target_os"],
+    target_platform = ":macos",
+)
+
+platform_transition_filegroup(
+    name = "target_os_windows",
+    srcs = [":gen_target_os"],
+    target_platform = ":windows",
+)
+
+assert_contains(
+    name = "linux_target_platform_test",
+    actual = ":target_os_linux",
+    expected = "linux",
+)
+
+assert_contains(
+    name = "macos_target_platform_test",
+    actual = ":target_os_macos",
+    expected = "macos",
+)
+
+assert_contains(
+    name = "windows_target_platform_test",
+    actual = ":target_os_windows",
+    expected = "windows",
+)

js/private/test/js_run_binary/read_file.mjs

@@ -0,0 +1,4 @@
+import fs from 'fs'
+
+const content = fs.readFileSync(process.argv[2], 'utf8').trim()
+process.stdout.write(content + '\n')

js/private/test/js_run_devserver/BUILD.bazel

@@ -28,6 +28,7 @@ js_run_devserver_test(
         "no-remote-exec",
     ],
     tool = ":jasmine",
+    use_execroot_entry_point = True,
 )
 
 jasmine_bin.jasmine_binary(