feat(runtime): add webpack require and bundler-ignore accessors

.changeset/twelve-forks-whisper.md

@@ -0,0 +1,7 @@
+---
+'@module-federation/webpack-bundler-runtime': patch
+'@module-federation/runtime-core': patch
+'@module-federation/utilities': patch
+---
+
+Add runtime-safe access helpers for webpack require and ignored dynamic imports, and migrate core runtime loaders to use these helpers so intermediate bundling steps are less likely to rewrite runtime globals.

packages/runtime-core/src/utils/load.ts

@@ -20,6 +20,14 @@ import {
 declare const ENV_TARGET: 'web' | 'node';
 const importCallback = '.then(callbacks[0]).catch(callbacks[1])';
 
+function importWithBundlerIgnore<T = unknown>(modulePath: string): Promise<T> {
+  return import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    modulePath
+  ) as Promise<T>;
+}
+
 async function loadEsmEntry({
   entry,
   remoteEntryExports,
@@ -36,7 +44,7 @@ async function loadEsmEntry({
             reject,
           ]);
         } else {
-          import(/* webpackIgnore: true */ /* @vite-ignore */ entry)
+          importWithBundlerIgnore<RemoteEntryExports>(entry)
             .then(resolve)
             .catch(reject);
         }

packages/utilities/package.json

@@ -23,7 +23,8 @@
     "rsbuild-plugin-publint": "^0.2.1"
   },
   "dependencies": {
-    "@module-federation/sdk": "workspace:*"
+    "@module-federation/sdk": "workspace:*",
+    "@module-federation/webpack-bundler-runtime": "workspace:*"
   },
   "peerDependencies": {
     "react": "^16 || ^17 || ^18",

packages/utilities/src/utils/importRemote.ts

@@ -4,6 +4,10 @@ import type {
   WebpackShareScopes,
   RemoteData,
 } from '../types';
+import {
+  importWithBundlerIgnore,
+  getWebpackRequireOrThrow,
+} from '@module-federation/webpack-bundler-runtime/accessor';
 
 /**
  * Type definition for RemoteUrl
@@ -50,7 +54,8 @@ const loadRemote = (
 ) =>
   new Promise<void>((resolve, reject) => {
     const timestamp = bustRemoteEntryCache ? `?t=${new Date().getTime()}` : '';
-    const webpackRequire = __webpack_require__ as unknown as WebpackRequire;
+    const webpackRequire =
+      getWebpackRequireOrThrow() as unknown as WebpackRequire;
     webpackRequire.l(
       `${url}${timestamp}`,
       (event) => {
@@ -72,19 +77,16 @@ const loadEsmRemote = async (
   url: RemoteData['url'],
   scope: ImportRemoteOptions['scope'],
 ) => {
-  const module = await import(/* webpackIgnore: true */ url);
+  const module = await importWithBundlerIgnore<WebpackRemoteContainer>(url);
 
   if (!module) {
     throw new Error(
       `Unable to load requested remote from ${url} with scope ${scope}`,
     );
   }
 
-  (window as any)[scope] = {
-    ...module,
-    __initializing: false,
-    __initialized: false,
-  } satisfies WebpackRemoteContainer;
+  module.__initialized = false;
+  (window as any)[scope] = module;
 };
 
 /**

packages/utilities/src/utils/pure.ts

@@ -3,8 +3,10 @@ import {
   RemoteVars,
   RuntimeRemote,
   RuntimeRemotesMap,
+  WebpackRequire,
   WebpackRemoteContainer,
 } from '../types';
+import { getWebpackRequireOrThrow } from '@module-federation/webpack-bundler-runtime/accessor';
 
 const pure = typeof process !== 'undefined' ? process.env['REMOTES'] || {} : {};
 export const remoteVars = pure as RemoteVars;
@@ -19,6 +21,8 @@ export const extractUrlAndGlobal = (urlAndGlobal: string): [string, string] => {
 
 export const loadScript = (keyOrRuntimeRemoteItem: string | RuntimeRemote) => {
   const runtimeRemotes = getRuntimeRemotes();
+  const webpackRequire =
+    getWebpackRequireOrThrow() as unknown as WebpackRequire;
 
   // 1) Load remote container if needed
   let asyncContainer: RuntimeRemote['asyncContainer'];
@@ -83,7 +87,7 @@ export const loadScript = (keyOrRuntimeRemoteItem: string | RuntimeRemote) => {
         return resolveRemoteGlobal();
       }
 
-      (__webpack_require__ as any).l(
+      webpackRequire.l(
         reference.url,
         function (event: Event) {
           //@ts-ignore

packages/webpack-bundler-runtime/__tests__/accessor.spec.ts

@@ -0,0 +1,36 @@
+import {
+  getWebpackRequire,
+  getWebpackRequireOrThrow,
+  importWithBundlerIgnore,
+} from '../src/accessor';
+
+describe('webpack require accessor', () => {
+  afterEach(() => {
+    delete (globalThis as { __webpack_require__?: unknown })
+      .__webpack_require__;
+  });
+
+  test('returns undefined when webpack runtime is unavailable', () => {
+    expect(getWebpackRequire()).toBeUndefined();
+  });
+
+  test('returns the webpack require function when present', () => {
+    const webpackRequire = Object.assign(jest.fn(), {
+      federation: { bundlerRuntime: {} },
+    });
+    (globalThis as { __webpack_require__?: unknown }).__webpack_require__ =
+      webpackRequire;
+
+    expect(getWebpackRequire()).toBe(webpackRequire);
+  });
+
+  test('throws with clear message when webpack runtime is unavailable', () => {
+    expect(() => getWebpackRequireOrThrow()).toThrow(
+      'Unable to access __webpack_require__.',
+    );
+  });
+
+  test('re-exports dynamic import helper', () => {
+    expect(typeof importWithBundlerIgnore).toBe('function');
+  });
+});

packages/webpack-bundler-runtime/package.json

@@ -50,6 +50,16 @@
         "default": "./dist/constant.cjs.cjs"
       }
     },
+    "./accessor": {
+      "import": {
+        "types": "./dist/accessor.d.ts",
+        "default": "./dist/accessor.esm.js"
+      },
+      "require": {
+        "types": "./dist/accessor.d.ts",
+        "default": "./dist/accessor.cjs.cjs"
+      }
+    },
     "./*": "./*"
   },
   "typesVersions": {
@@ -59,6 +69,9 @@
       ],
       "constant": [
         "./dist/constant.d.ts"
+      ],
+      "accessor": [
+        "./dist/accessor.d.ts"
       ]
     }
   }

packages/webpack-bundler-runtime/project.json

@@ -18,7 +18,8 @@
         "compiler": "tsc",
         "format": ["cjs", "esm"],
         "additionalEntryPoints": [
-          "packages/webpack-bundler-runtime/src/constant.ts"
+          "packages/webpack-bundler-runtime/src/constant.ts",
+          "packages/webpack-bundler-runtime/src/accessor.ts"
         ],
         "generatePackageJson": false,
         "useLegacyTypescriptPlugin": false,

packages/webpack-bundler-runtime/src/accessor.ts

@@ -0,0 +1,33 @@
+import type { WebpackRequire } from './types';
+
+declare const __webpack_require__: unknown;
+
+export function getWebpackRequire(): WebpackRequire | undefined {
+  if (typeof __webpack_require__ !== 'function') {
+    return undefined;
+  }
+
+  return __webpack_require__ as WebpackRequire;
+}
+
+export function getWebpackRequireOrThrow(): WebpackRequire {
+  const webpackRequire = getWebpackRequire();
+
+  if (!webpackRequire) {
+    throw new Error(
+      'Unable to access __webpack_require__. Ensure this code runs inside a webpack-compatible runtime.',
+    );
+  }
+
+  return webpackRequire;
+}
+
+export function importWithBundlerIgnore<T = unknown>(
+  modulePath: string,
+): Promise<T> {
+  return import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    modulePath
+  ) as Promise<T>;
+}

packages/webpack-bundler-runtime/src/index.ts

@@ -8,8 +8,14 @@ import { attachShareScopeMap } from './attachShareScopeMap';
 import { initContainerEntry } from './initContainerEntry';
 import { init } from './init';
 import { getSharedFallbackGetter } from './getSharedFallbackGetter';
+import {
+  getWebpackRequire,
+  getWebpackRequireOrThrow,
+  importWithBundlerIgnore,
+} from './accessor';
 
 export * from './types';
+export { getWebpackRequire, getWebpackRequireOrThrow, importWithBundlerIgnore };
 
 const federation: Federation = {
   runtime,