feat(commonjs): add 'externalBuiltinsRequire' option to stub node: builtins proxy for edge runtimes; keep default as 'create-require' (#1924)

Author: CharlieHelps

packages/commonjs/README.md

@@ -183,6 +183,33 @@ When this option is set to `false`, the generated code will either directly thro
 
 Setting this option to `true` will instead leave the `require` call in the code or use it as a fallback for `dynamicRequireTargets`.
 
+### `externalBuiltinsRequire`
+
+Type: `'create-require' | 'stub'`  
+Default: `'create-require'`
+
+Controls how external Node built-ins (e.g. `require('node:fs')`) that are required from wrapped CommonJS modules are handled.
+
+- `'create-require'` (default): lazily resolve the built-in at runtime using `module.createRequire(import.meta.url)`. This matches Node behaviour and avoids hoisting, but introduces a hard dependency on `node:module` in the generated output.
+- `'stub'`: emit a tiny proxy that exports a throwing `__require()` without importing from `node:module`. This avoids the `node:module` import so bundles can parse/run in edge runtimes when those code paths are never executed. If the path is executed at runtime, it will throw with a clear error message.
+
+Example (avoid `node:module` for edge targets):
+
+```js
+import commonjs from '@rollup/plugin-commonjs';
+
+export default {
+  input: 'src/index.js',
+  output: { format: 'es' },
+  plugins: [
+    commonjs({
+      strictRequires: true,
+      externalBuiltinsRequire: 'stub'
+    })
+  ]
+};
+```
+
 ### `esmExternals`
 
 Type: `boolean | string[] | ((id: string) => boolean)`

packages/commonjs/src/index.js

@@ -44,6 +44,8 @@ export default function commonjs(options = {}) {
     defaultIsModuleExports: defaultIsModuleExportsOption,
     esmExternals
   } = options;
+  const externalBuiltinsRequireStrategy =
+    options.externalBuiltinsRequire === 'stub' ? 'stub' : 'create-require';
   const extensions = options.extensions || ['.js'];
   const filter = createFilter(options.include, options.exclude);
   const isPossibleCjsId = (id) => {
@@ -264,7 +266,7 @@ export default function commonjs(options = {}) {
       if (isWrappedId(id, EXTERNAL_SUFFIX)) {
         const actualId = unwrapId(id, EXTERNAL_SUFFIX);
         if (actualId.startsWith('node:')) {
-          return getExternalBuiltinRequireProxy(actualId);
+          return getExternalBuiltinRequireProxy(actualId, externalBuiltinsRequireStrategy);
         }
         return getUnknownRequireProxy(
           actualId,

packages/commonjs/src/proxies.js

@@ -90,8 +90,24 @@ export function getEsImportProxy(id, defaultIsModuleExports, moduleSideEffects)
 // hoist an ESM import of the built-in (which would eagerly load it). Instead,
 // expose a lazy `__require()` that resolves the built-in at runtime via
 // `createRequire(import.meta.url)`.
-export function getExternalBuiltinRequireProxy(id) {
+/**
+ * Generate the proxy module used for external Node built-ins that are
+ * `require()`d from wrapped CommonJS modules.
+ *
+ * Strategy:
+ * - 'create-require' (default): import `createRequire` from 'node:module' and
+ *   lazily resolve the built-in at runtime. This keeps Node behaviour and
+ *   avoids hoisting, but hard-depends on Node's `module` API.
+ * - 'stub': emit a tiny proxy that exports a throwing `__require()` without
+ *   importing from 'node:module'. This makes output parse/run in edge
+ *   runtimes when the path is dead, and fails loudly if executed.
+ */
+export function getExternalBuiltinRequireProxy(id, strategy = 'create-require') {
   const stringifiedId = JSON.stringify(id);
+  if (strategy === 'stub') {
+    const msg = `Node built-in ${stringifiedId} is not available in this environment`;
+    return `export function __require() { throw new Error(${JSON.stringify(msg)}); }`;
+  }
   return (
     `import { createRequire } from 'node:module';\n` +
     `const require = createRequire(import.meta.url);\n` +

packages/commonjs/test/fixtures/function/module-side-effects-external-node-builtin-wrapped-stub/_config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  description:
+    "uses 'stub' proxy for external node: builtins when configured, avoiding node:module import",
+  pluginOptions: {
+    strictRequires: true,
+    externalBuiltinsRequire: 'stub'
+  },
+  context: {
+    __filename: __filename
+  }
+};

packages/commonjs/test/fixtures/function/module-side-effects-external-node-builtin-wrapped-stub/main.js

@@ -0,0 +1,8 @@
+// Top-level require of a Node builtin ensures the transform computes
+// wrappedModuleSideEffects for an external wrapped dependency.
+function unused() {
+  // External Node builtin require; not executed at runtime
+  require('node:crypto');
+}
+
+module.exports = 1;

packages/commonjs/test/snapshots/function.js.md

@@ -6731,6 +6731,35 @@ Generated by [AVA](https://avajs.dev).
       `,
     }
 
+## module-side-effects-external-node-builtin-wrapped-stub
+
+> Snapshot 1
+
+    {
+      'main.js': `'use strict';␊
+      ␊
+      function getDefaultExportFromCjs (x) {␊
+      	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;␊
+      }␊
+      ␊
+      var main$1;␊
+      var hasRequiredMain;␊
+      ␊
+      function requireMain () {␊
+      	if (hasRequiredMain) return main$1;␊
+      	hasRequiredMain = 1;␊
+      ␊
+      	main$1 = 1;␊
+      	return main$1;␊
+      }␊
+      ␊
+      var mainExports = requireMain();␊
+      var main = /*@__PURE__*/getDefaultExportFromCjs(mainExports);␊
+      ␊
+      module.exports = main;␊
+      `,
+    }
+
 ## module-side-effects-import-wrapped
 
 > Snapshot 1

packages/commonjs/test/snapshots/function.js.snap

@@ -225,6 +225,18 @@ interface RollupCommonJSOptions {
    * home directory name. By default, it uses the current working directory.
    */
   dynamicRequireRoot?: string;
+
+  /**
+   * Controls how `require('node:*')` dependencies of wrapped CommonJS modules are
+   * handled. The default uses Node's `module.createRequire` lazily to resolve the
+   * built-in at runtime. Set to `'stub'` to avoid importing from `node:module` and
+   * instead emit a tiny proxy whose `__require()` throws at runtime. This can be
+   * useful for edge runtimes that do not support Node built-ins when those code paths
+   * are never executed.
+   *
+   * @default 'create-require'
+   */
+  externalBuiltinsRequire?: 'create-require' | 'stub';
 }
 
 /**