feat(js): add esm support for esbuild and running serve with the node executor (#31965)

This PR enables the Node.js executor to run ESM-only packages (like
`node-fetch`@3) alongside CommonJS modules.

### Changes:

- ESM loader: Implemented custom ESM resolver to handle Nx workspace
library mappings in ESM contexts
- Dynamic execution: Node executor now switches between CommonJS and ESM
loaders based on the detected module format
- esbuild updates: Enhanced esbuild executor to properly handle ESM
output formats and creating a proper `package.json`

closes: #10296

---------

Co-authored-by: nx-cloud[bot] <71083854+nx-cloud[bot]@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

Author: 3 people

e2e/js/src/js-esm-support.test.ts

@@ -92,10 +92,12 @@ export async function* esbuildExecutor(
 
     const cpjOptions: CopyPackageJsonOptions = {
       ...options,
+      format: options.format,
       // TODO(jack): make types generate with esbuild
       skipTypings: true,
       generateLockfile: true,
-      outputFileExtensionForCjs: getOutExtension('cjs', options),
+      outputFileExtensionForCjs: getOutExtension('cjs', options, context),
+      outputFileExtensionForEsm: getOutExtension('esm', options, context),
       excludeLibsInPackageJson: !options.thirdParty,
       // TODO(jack): Remove the need to pass updateBuildableProjectDepsInPackageJson option when overrideDependencies or extraDependencies are passed.
       // Add this back to fix a regression.

e2e/node/src/node-esm-support.test.ts

@@ -23,7 +23,7 @@ export function buildEsbuildOptions(
   options: NormalizedEsBuildExecutorOptions,
   context: ExecutorContext
 ): esbuild.BuildOptions {
-  const outExtension = getOutExtension(format, options);
+  const outExtension = getOutExtension(format, options, context);
 
   const esbuildOptions: esbuild.BuildOptions = {
     ...options.userDefinedBuildOptions,
@@ -74,7 +74,7 @@ export function buildEsbuildOptions(
     esbuildOptions.entryPoints = entryPoints;
   } else if (options.platform === 'node' && format === 'cjs') {
     // When target platform Node and target format is CJS, then also transpile workspace libs used by the app.
-    // Provide a `require` override in the main entry file so workspace libs can be loaded when running the app.
+    // Provide a loader override in the main entry file so workspace libs can be loaded when running the app.
     const paths = options.isTsSolutionSetup
       ? createPathsFromTsConfigReferences(context)
       : getTsConfigCompilerPaths(context);
@@ -91,7 +91,13 @@ export function buildEsbuildOptions(
 
     esbuildOptions.entryPoints = [
       // Write a main entry file that registers workspace libs and then calls the user-defined main.
-      writeTmpEntryWithRequireOverrides(paths, outExtension, options, context),
+      writeTmpEntryWithRequireOverrides(
+        paths,
+        outExtension,
+        options,
+        context,
+        format
+      ),
       ...entryPointsFromProjects.map((f) => {
         /**
          * Maintain same directory structure as the workspace, so that other workspace libs may be used by the project.
@@ -255,12 +261,14 @@ function getProjectEntryPoint(projectPkgJson: any, projectPath: string) {
 
 export function getOutExtension(
   format: 'cjs' | 'esm',
-  options: Pick<NormalizedEsBuildExecutorOptions, 'userDefinedBuildOptions'>
+  options: Pick<NormalizedEsBuildExecutorOptions, 'userDefinedBuildOptions'>,
+  context?: ExecutorContext
 ): '.cjs' | '.mjs' | '.js' {
   const userDefinedExt = options.userDefinedBuildOptions?.outExtension?.['.js'];
   // Allow users to change the output extensions from default CJS and ESM extensions.
   // CJS -> .js
   // ESM -> .mjs
+
   return userDefinedExt === '.js' && format === 'cjs'
     ? '.js'
     : userDefinedExt === '.mjs' && format === 'esm'
@@ -275,7 +283,7 @@ export function getOutfile(
   options: NormalizedEsBuildExecutorOptions,
   context: ExecutorContext
 ) {
-  const ext = getOutExtension(format, options);
+  const ext = getOutExtension(format, options, context);
   const candidate = joinPathFragments(
     context.target.options.outputPath,
     options.outputFileName
@@ -288,7 +296,8 @@ function writeTmpEntryWithRequireOverrides(
   paths: Record<string, string[]>,
   outExtension: '.cjs' | '.js' | '.mjs',
   options: NormalizedEsBuildExecutorOptions,
-  context: ExecutorContext
+  context: ExecutorContext,
+  format: 'cjs' | 'esm' = 'cjs'
 ): { in: string; out: string } {
   const project = context.projectGraph?.nodes[context.projectName];
   // Write a temp main entry source that registers workspace libs.
@@ -309,7 +318,7 @@ function writeTmpEntryWithRequireOverrides(
 
   writeFileSync(
     mainWithRequireOverridesInPath,
-    getRegisterFileContent(project, paths, mainFile, outExtension)
+    getRegisterFileContent(project, paths, mainFile, outExtension, format)
   );
 
   let mainWithRequireOverridesOutPath: string;
@@ -335,7 +344,8 @@ export function getRegisterFileContent(
   project: ProjectGraphProjectNode,
   paths: Record<string, string[]>,
   mainFile: string,
-  outExtension = '.js'
+  outExtension = '.js',
+  format: 'cjs' | 'esm' = 'cjs'
 ) {
   mainFile = normalizePath(mainFile);
 
@@ -364,7 +374,58 @@ export function getRegisterFileContent(
     return acc;
   }, []);
 
-  return `
+  if (format === 'esm') {
+    return `
+/**
+ * IMPORTANT: Do not modify this file.
+ * This file allows the app to run without bundling in workspace libraries.
+ * Must be contained in the ".nx" folder inside the output path.
+ */
+import { pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const distPath = __dirname;
+const manifest = ${JSON.stringify(manifest)};
+
+// Resolver for workspace libs
+const originalResolve = import.meta.resolve;
+if (originalResolve) {
+  import.meta.resolve = function(specifier, parent) {
+    const matchingEntry = manifest.find(
+      (entry) => specifier === entry.module || specifier.startsWith(entry.module + '/')
+    );
+    
+    if (matchingEntry) {
+      if (matchingEntry.exactMatch) {
+        const candidate = join(distPath, matchingEntry.exactMatch);
+        if (existsSync(candidate)) {
+          return pathToFileURL(candidate).href;
+        }
+      } else {
+        const re = new RegExp(matchingEntry.module.replace(/\\*$/, "(?<rest>.*)"));
+        const match = specifier.match(re);
+        if (match?.groups) {
+          const candidate = join(distPath, matchingEntry.pattern.replace("*", ""), match.groups.rest);
+          if (existsSync(candidate)) {
+            return pathToFileURL(candidate).href;
+          }
+        }
+      }
+    }
+    
+    return originalResolve.call(this, specifier, parent);
+  };
+}
+
+// Call the user-defined main.
+await import(pathToFileURL(join(distPath, '${mainFile}')).href);
+`;
+  } else {
+    return `
 /**
  * IMPORTANT: Do not modify this file.
  * This file allows the app to run without bundling in workspace libraries.
@@ -420,6 +481,7 @@ function isFile(s) {
 // Call the user-defined main.
 module.exports = require('${mainFile}');
 `;
+  }
 }
 
 function getPrefixLength(pattern: string): number {
@@ -438,8 +500,13 @@ function getPrefixLength(pattern: string): number {
 function getTsConfigCompilerPaths(context: ExecutorContext): {
   [key: string]: string[];
 } {
+  const rootTsConfigPath = getRootTsConfigPath(context);
+  if (!rootTsConfigPath) {
+    return {};
+  }
+
   const tsconfigPaths = require('tsconfig-paths');
-  const tsConfigResult = tsconfigPaths.loadConfig(getRootTsConfigPath(context));
+  const tsConfigResult = tsconfigPaths.loadConfig(rootTsConfigPath);
   if (tsConfigResult.resultType !== 'success') {
     throw new Error('Cannot load tsconfig file');
   }
@@ -454,7 +521,5 @@ function getRootTsConfigPath(context: ExecutorContext): string | null {
     }
   }
 
-  throw new Error(
-    'Could not find a root tsconfig.json or tsconfig.base.json file.'
-  );
+  return null;
 }