build: introduce NodeJS loader for rules_js Node execution (angular#61865)

devversion · pkozlowski-opensource · commit d86d11d4c142 · 2025-06-05T12:04:51.000+02:00
For the `rules_js` migration, we are facing the problem where our current Angular code is shipped as ESM, but we aren't fully there yet with fully compliant strict ESM during development. That is because we lack explicit import extensions, and it's also a different story how this would work in Google3, if we were to add them. In addition, we cross-import from our packages using npm module names. This works well for TS, for ESBuild because those can respect path mappings— but at runtime, when executing native `jasmine_test`'s— such mappings aren't respected. The options here are: - avoid module imports in the repo (impossible; undesired) - use pre-bundling of all NodeJS execution involving npm package code (slower, extra build action cost) - wire up a simple NodeJS loader (supported via official APIs) to simply account for our cases (preferred and similar to what we experimented with for the last year(s); and worked well) This commit implements the last option and allows for an easy migration to `rules_js`, and also is pretty reasonable. Long-term we can resolve the extension problem if we e.g. migrate to real explicit extensions + a proper TS module resolution like e.g. `nodenext`. PR Close angular#61865
diff --git a/.aspect/rules/external_repository_action_cache/npm_translate_lock_MzA5NzUwNzMx b/.aspect/rules/external_repository_action_cache/npm_translate_lock_MzA5NzUwNzMx
@@ -6,7 +6,7 @@
 adev/shared-docs/pipeline/api-gen/package.json=939673974
 integration/package.json=-239561259
 modules/package.json=-1315257891
-package.json=1012566638
+package.json=-1124738082
 packages/animations/package.json=-678724831
 packages/common/package.json=1729763064
 packages/compiler-cli/linker/babel/test/package.json=939673974
@@ -21,7 +21,7 @@ packages/platform-browser/package.json=-1163479450
 packages/router/package.json=860819913
 packages/upgrade/package.json=16347051
 packages/zone.js/package.json=-1577512523
-pnpm-lock.yaml=-1427965318
+pnpm-lock.yaml=1622469731
 pnpm-workspace.yaml=1973735808
 tools/bazel/rules_angular_store/package.json=-239561259
-yarn.lock=-1301634010
+yarn.lock=916728416
diff --git a/package.json b/package.json
@@ -207,6 +207,7 @@
     "emoji-regex": "^10.3.0",
     "fflate": "^0.8.2",
     "firebase-tools": "^14.0.0",
+    "get-tsconfig": "^4.10.1",
     "gulp": "^5.0.0",
     "gulp-conventional-changelog": "^5.0.0",
     "html-entities": "^2.5.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/tools/bazel/js_binary.bzl b/tools/bazel/js_binary.bzl
@@ -0,0 +1,20 @@
+"""
+    Extension of native `js_binary` to install a NodeJS resolution hook
+    that will help with automatically adding missing ESM extension and
+    mapping `@angular/<..>` to the local first-party package directory.
+"""
+
+load("@aspect_rules_js//js:defs.bzl", _js_binary = "js_binary")
+
+def js_binary(name, chdir = None, data = [], **kwargs):
+    if chdir != None:
+        to_root = ["/".join([".."] * len(chdir.split("/")))]
+    else:
+        to_root = "./"
+
+    _js_binary(
+        name = name,
+        data = data + ["//tools/bazel/node_loader", "//packages:tsconfig_build"],
+        node_options = ["--import", "%s/tools/bazel/node_loader/index.mjs" % to_root],
+        **kwargs
+    )
diff --git a/tools/bazel/node_loader/BUILD.bazel b/tools/bazel/node_loader/BUILD.bazel
@@ -0,0 +1,8 @@
+load("@aspect_rules_js//js:defs.bzl", "js_library")
+
+js_library(
+    name = "node_loader",
+    srcs = glob(["*.mjs"]),
+    visibility = ["//visibility:public"],
+    deps = ["//:node_modules/get-tsconfig"],
+)
diff --git a/tools/bazel/node_loader/hooks.mjs b/tools/bazel/node_loader/hooks.mjs
@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+/**
+ * @fileoverview
+ *
+ * Module loader that augments NodeJS's execution to:
+ *
+ * - support native execution of Angular JavaScript output
+ *   that isn't strict ESM at this point (lack of explicit extensions).
+ * - support path mappings at runtime. This allows us to natively execute ESM
+ *   without having to pre-bundle for testing, or use the slow full npm linked packages
+ */
+
+import {parseTsconfig, createPathsMatcher} from 'get-tsconfig';
+
+import path from 'node:path';
+
+const explicitExtensionRe = /\.[mc]?js$/;
+const nonModuleImportRe = /^[.\/]/;
+
+const runfilesRoot = process.env.JS_BINARY__RUNFILES;
+
+const tsconfigPath = path.join(runfilesRoot, 'angular/packages/tsconfig-build.json');
+const tsconfig = parseTsconfig(tsconfigPath);
+const pathMappingMatcher = createPathsMatcher({config: tsconfig, path: tsconfigPath});
+
+/** @type {import('module').ResolveHook} */
+export const resolve = async (specifier, context, nextResolve) => {
+  // True when it's a non-module import without explicit extensions.
+  const isNonModuleExtensionlessImport =
+    nonModuleImportRe.test(specifier) && !explicitExtensionRe.test(specifier);
+  const pathMappings = !nonModuleImportRe.test(specifier) ? pathMappingMatcher(specifier) : [];
+
+  // If it's neither path mapped, nor an extension-less import that may be fixed up, exit early.
+  if (!isNonModuleExtensionlessImport && pathMappings.length === 0) {
+    return nextResolve(specifier, context);
+  }
+
+  if (pathMappings.length > 0) {
+    for (const mapping of pathMappings) {
+      const res = await catchError(() => resolve(mapping, context, nextResolve));
+      if (res !== null) {
+        return res;
+      }
+    }
+  } else {
+    const fixedResult =
+      (await catchError(() => nextResolve(`${specifier}.js`, context))) ||
+      (await catchError(() => nextResolve(`${specifier}/index.js`, context)));
+
+    if (fixedResult !== null) {
+      return fixedResult;
+    }
+  }
+
+  return await nextResolve(specifier, context);
+};
+
+async function catchError(fn) {
+  try {
+    return await fn();
+  } catch {
+    return null;
+  }
+}
diff --git a/tools/bazel/node_loader/index.mjs b/tools/bazel/node_loader/index.mjs
@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {register} from 'node:module';
+
+register('./hooks.mjs', {parentURL: import.meta.url});
diff --git a/yarn.lock b/yarn.lock
@@ -9571,7 +9571,7 @@ get-symbol-description@^1.1.0:
     es-errors "^1.3.0"
     get-intrinsic "^1.2.6"
 
-get-tsconfig@^4.7.5:
+get-tsconfig@^4.10.1, get-tsconfig@^4.7.5:
   version "4.10.1"
   resolved "https://registry.yarnpkg.com/get-tsconfig/-/get-tsconfig-4.10.1.tgz#d34c1c01f47d65a606c37aa7a177bc3e56ab4b2e"
   integrity sha512-auHyJ4AgMz7vgS8Hp3N6HXSmlMdUyhSUrfBF16w153rxtLIEOE+HGqaBppczZvnHLqQJfiHotCYpNhl0lUROFQ==
