module: include module information in require(esm) warning

joyeecheung · marco-ippolito · commit 8192dd6cf3e3 · 2025-02-11T11:56:48.000+01:00
When emitting the experimental warning for `require(esm)`, include information about the parent module and the module being require()-d to help users locate and update them. PR-URL: #55397 Backport-PR-URL: #56927 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Refs: #52697
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
@@ -1340,11 +1340,31 @@ function loadESMFromCJS(mod, filename) {
     // ESM won't be accessible via process.mainModule.
     setOwnProperty(process, 'mainModule', undefined);
   } else {
-    emitExperimentalWarning('Support for loading ES Module in require()');
+    const parent = mod[kModuleParent];
+    let messagePrefix;
+    if (parent) {
+      // In the case of the module calling `require()`, it's more useful to know its absolute path.
+      let from = parent.filename || parent.id;
+      // In the case of the module being require()d, it's more useful to know the id passed into require().
+      const to = mod.id || mod.filename;
+      if (from === 'internal/preload') {
+        from = '--require';
+      } else if (from === '<repl>') {
+        from = 'The REPL';
+      } else if (from === '.') {
+        from = 'The entry point';
+      } else {
+        from &&= `CommonJS module ${from}`;
+      }
+      if (from && to) {
+        messagePrefix = `${from} is loading ES Module ${to} using require().\n`;
+      }
+    }
+    emitExperimentalWarning('Support for loading ES Module in require()', messagePrefix);
     const {
       wrap,
       namespace,
-    } = cascadedLoader.importSyncForRequire(mod, filename, source, isMain, mod[kModuleParent]);
+    } = cascadedLoader.importSyncForRequire(mod, filename, source, isMain, parent);
     // Tooling in the ecosystem have been using the __esModule property to recognize
     // transpiled ESM in consuming code. For example, a 'log' package written in ESM:
     //
diff --git a/lib/internal/util.js b/lib/internal/util.js
@@ -255,10 +255,13 @@ function slowCases(enc) {
   }
 }
 
-function emitExperimentalWarning(feature) {
+function emitExperimentalWarning(feature, messagePrefix) {
   if (experimentalWarnings.has(feature)) return;
-  const msg = `${feature} is an experimental feature and might change at any time`;
   experimentalWarnings.add(feature);
+  let msg = `${feature} is an experimental feature and might change at any time`;
+  if (messagePrefix) {
+    msg = messagePrefix + msg;
+  }
   process.emitWarning(msg, 'ExperimentalWarning');
 }
 
diff --git a/test/es-module/test-require-module-preload.js b/test/es-module/test-require-module-preload.js
@@ -4,11 +4,9 @@ require('../common');
 const { spawnSyncAndAssert } = require('../common/child_process');
 const { fixturesDir } = require('../common/fixtures');
 
-const warningRE = /ExperimentalWarning: Support for loading ES Module in require/;
 function testPreload(preloadFlag) {
   // The warning is only emitted when ESM is loaded by --require.
-  const stderr = preloadFlag !== '--import' ? warningRE : undefined;
-
+  const isRequire = preloadFlag === '--require';
   // Test named exports.
   {
     spawnSyncAndAssert(
@@ -24,7 +22,8 @@ function testPreload(preloadFlag) {
       },
       {
         stdout: 'A',
-        stderr,
+        stderr: isRequire ?
+          /ExperimentalWarning: --require is loading ES Module .*module-named-exports\.mjs using require/ : undefined,
         trim: true,
       }
     );
@@ -44,7 +43,8 @@ function testPreload(preloadFlag) {
         cwd: fixturesDir
       },
       {
-        stderr,
+        stderr: isRequire ?
+          /ExperimentalWarning: --require is loading ES Module .*import-esm\.mjs using require/ : undefined,
         stdout: /^world\s+A$/,
         trim: true,
       }
@@ -66,7 +66,8 @@ function testPreload(preloadFlag) {
       },
       {
         stdout: /^ok\s+A$/,
-        stderr,
+        stderr: isRequire ?
+          /ExperimentalWarning: --require is loading ES Module .*cjs-exports\.mjs using require/ : undefined,
         trim: true,
       }
     );
@@ -89,7 +90,8 @@ function testPreload(preloadFlag) {
       },
       {
         stdout: /^world\s+A$/,
-        stderr,
+        stderr: isRequire ?
+          /ExperimentalWarning: --require is loading ES Module .*require-cjs\.mjs using require/ : undefined,
         trim: true,
       }
     );
@@ -115,7 +117,7 @@ testPreload('--import');
     },
     {
       stdout: /^package-type-module\s+A$/,
-      stderr: warningRE,
+      stderr: /ExperimentalWarning: --require is loading ES Module .*package-type-module[\\/]index\.js using require/,
       trim: true,
     }
   );
diff --git a/test/es-module/test-require-module.js b/test/es-module/test-require-module.js
@@ -3,9 +3,13 @@
 
 const common = require('../common');
 const assert = require('assert');
+const path = require('path');
 
+// Only the first load will trigger the warning.
 common.expectWarning(
   'ExperimentalWarning',
+  `CommonJS module ${__filename} is loading ES Module ` +
+  `${path.resolve(__dirname, '../fixtures/es-module-loaders/module-named-exports.mjs')} using require().\n` +
   'Support for loading ES Module in require() is an experimental feature ' +
   'and might change at any time'
 );

Original file line number	Diff line number	Diff line change
`@@ -255,10 +255,13 @@ function slowCases(enc) {`
`255`	`255`	`}`
`256`	`256`	`}`
`257`	`257`
`258`		`-function emitExperimentalWarning(feature) {`
	`258`	`+function emitExperimentalWarning(feature, messagePrefix) {`
`259`	`259`	`if (experimentalWarnings.has(feature)) return;`
`260`		- const msg = `${feature} is an experimental feature and might change at any time`;
`261`	`260`	`experimentalWarnings.add(feature);`
	`261`	+ let msg = `${feature} is an experimental feature and might change at any time`;
	`262`	`+ if (messagePrefix) {`
	`263`	`+ msg = messagePrefix + msg;`
	`264`	`+ }`
`262`	`265`	`process.emitWarning(msg, 'ExperimentalWarning');`
`263`	`266`	`}`
`264`	`267`
Original file line number	Diff line number	Diff line change
`@@ -4,11 +4,9 @@ require('../common');`
`4`	`4`	`const { spawnSyncAndAssert } = require('../common/child_process');`
`5`	`5`	`const { fixturesDir } = require('../common/fixtures');`
`6`	`6`
`7`		`-const warningRE = /ExperimentalWarning: Support for loading ES Module in require/;`
`8`	`7`	`function testPreload(preloadFlag) {`
`9`	`8`	`// The warning is only emitted when ESM is loaded by --require.`
`10`		`- const stderr = preloadFlag !== '--import' ? warningRE : undefined;`
`11`		`-`
	`9`	`+ const isRequire = preloadFlag === '--require';`
`12`	`10`	`// Test named exports.`
`13`	`11`	`{`
`14`	`12`	`spawnSyncAndAssert(`
`@@ -24,7 +22,8 @@ function testPreload(preloadFlag) {`
`24`	`22`	`},`
`25`	`23`	`{`
`26`	`24`	`stdout: 'A',`
`27`		`- stderr,`
	`25`	`+ stderr: isRequire ?`
	`26`	`+ /ExperimentalWarning: --require is loading ES Module .*module-named-exports\.mjs using require/ : undefined,`
`28`	`27`	`trim: true,`
`29`	`28`	`}`
`30`	`29`	`);`
`@@ -44,7 +43,8 @@ function testPreload(preloadFlag) {`
`44`	`43`	`cwd: fixturesDir`
`45`	`44`	`},`
`46`	`45`	`{`
`47`		`- stderr,`
	`46`	`+ stderr: isRequire ?`
	`47`	`+ /ExperimentalWarning: --require is loading ES Module .*import-esm\.mjs using require/ : undefined,`
`48`	`48`	`stdout: /^world\s+A$/,`
`49`	`49`	`trim: true,`
`50`	`50`	`}`
`@@ -66,7 +66,8 @@ function testPreload(preloadFlag) {`
`66`	`66`	`},`
`67`	`67`	`{`
`68`	`68`	`stdout: /^ok\s+A$/,`
`69`		`- stderr,`
	`69`	`+ stderr: isRequire ?`
	`70`	`+ /ExperimentalWarning: --require is loading ES Module .*cjs-exports\.mjs using require/ : undefined,`
`70`	`71`	`trim: true,`
`71`	`72`	`}`
`72`	`73`	`);`
`@@ -89,7 +90,8 @@ function testPreload(preloadFlag) {`
`89`	`90`	`},`
`90`	`91`	`{`
`91`	`92`	`stdout: /^world\s+A$/,`
`92`		`- stderr,`
	`93`	`+ stderr: isRequire ?`
	`94`	`+ /ExperimentalWarning: --require is loading ES Module .*require-cjs\.mjs using require/ : undefined,`
`93`	`95`	`trim: true,`
`94`	`96`	`}`
`95`	`97`	`);`
`@@ -115,7 +117,7 @@ testPreload('--import');`
`115`	`117`	`},`
`116`	`118`	`{`
`117`	`119`	`stdout: /^package-type-module\s+A$/,`
`118`		`- stderr: warningRE,`
	`120`	`+ stderr: /ExperimentalWarning: --require is loading ES Module .*package-type-module[\\/]index\.js using require/,`
`119`	`121`	`trim: true,`
`120`	`122`	`}`
`121`	`123`	`);`