feat(runtime): add loadEntryTimeout option for the remote entry script timeout

Author: marksnode

.changeset/patient-remote-entry-timeout.md

@@ -0,0 +1,6 @@
+---
+'@module-federation/sdk': patch
+'@module-federation/runtime-core': patch
+---
+
+feat: `loadEntryTimeout` runtime option — how long a remote entry script may take to load before it fails with RUNTIME-008 (default 20000 ms, `Infinity` disables the timer); `createScript` / `loadScript` accept a `timeout` and a `createScript` hook return value still overrides it

apps/website-new/docs/en/guide/runtime/runtime-api.mdx

@@ -41,6 +41,12 @@ const mf = createInstance({
 mf.loadRemote('sub1/util').then((m) => m.add(1, 2, 3));
 ```
 
+**Options**
+
+Besides `name`, `remotes`, `shared`, `plugins` and `shareStrategy`, the instance accepts:
+
+- `loadEntryTimeout` — how long (ms) a remote entry script may take to load before the load fails with `RUNTIME-008`. Defaults to `20000`; pass `Infinity` to wait indefinitely. A `createScript` hook that returns `timeout` still takes precedence.
+
 ## init <Badge type='warning'>Use with caution</Badge>
 
 Used to initialize or reuse a `ModuleFederation` runtime instance.

apps/website-new/docs/zh/guide/runtime/runtime-api.mdx

@@ -41,6 +41,12 @@ const mf = createInstance({
 mf.loadRemote('sub1/util').then((m) => m.add(1, 2, 3));
 ```
 
+**配置项**
+
+除了 `name`、`remotes`、`shared`、`plugins` 和 `shareStrategy`，实例还接受：
+
+- `loadEntryTimeout` — 远程入口脚本的加载超时时间（毫秒），超时后以 `RUNTIME-008` 报错。默认 `20000`；传 `Infinity` 表示不限时。`createScript` 钩子返回的 `timeout` 仍然优先。
+
 ## init <Badge type='warning'>谨慎使用</Badge>
 
 用于初始化或复用 `ModuleFederation` 运行时实例。

packages/runtime-core/__tests__/load.spec.ts

@@ -126,6 +126,53 @@ describe('getRemoteEntry - script load error discrimination', () => {
     );
   });
 
+  it('passes loadEntryTimeout to the entry script loader', async () => {
+    const entry = `${BASE}/success.js`;
+    const origin = new ModuleFederation({
+      name: 'test-host',
+      remotes: [],
+      loadEntryTimeout: 45000,
+    });
+    const remoteInfo = getRemoteInfo({ name: 'remote', entry });
+    const setTimeoutSpy = rs.spyOn(globalThis, 'setTimeout');
+
+    try {
+      await getRemoteEntry({ origin, remoteInfo });
+      expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 45000);
+      expect(setTimeoutSpy).not.toHaveBeenCalledWith(
+        expect.any(Function),
+        20000,
+      );
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
+  it('does not arm the entry timer when loadEntryTimeout is Infinity', async () => {
+    const entry = `${BASE}/success.js`;
+    const origin = new ModuleFederation({
+      name: 'test-host',
+      remotes: [],
+      loadEntryTimeout: Infinity,
+    });
+    const remoteInfo = getRemoteInfo({ name: 'remote', entry });
+    const setTimeoutSpy = rs.spyOn(globalThis, 'setTimeout');
+
+    try {
+      await getRemoteEntry({ origin, remoteInfo });
+      expect(setTimeoutSpy).not.toHaveBeenCalledWith(
+        expect.any(Function),
+        20000,
+      );
+      expect(setTimeoutSpy).not.toHaveBeenCalledWith(
+        expect.any(Function),
+        Infinity,
+      );
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
   it('module entry load failure can recover through loadEntryError with getEntryUrl', async () => {
     const entry = createDataUrlEntry(
       `throw new TypeError('Failed to fetch dynamically imported module: http://localhost:4999/remoteEntry.js');`,

packages/runtime-core/src/type/config.ts

@@ -141,6 +141,11 @@ export interface Options {
   plugins: Array<ModuleFederationRuntimePlugin>;
   inBrowser: boolean;
   shareStrategy?: ShareStrategy;
+  /**
+   * How long (ms) a remote entry script may take to load before it is reported as RUNTIME-008.
+   * Defaults to 20000; `Infinity` disables the timer. A `createScript` hook returning `timeout` still wins.
+   */
+  loadEntryTimeout?: number;
 }
 
 export type UserOptions = Omit<

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

@@ -165,6 +165,7 @@ async function loadEntryScript({
   loaderHook,
   getEntryUrl,
   resourceContext,
+  timeout,
 }: {
   name: string;
   globalName: string;
@@ -173,6 +174,7 @@ async function loadEntryScript({
   loaderHook: ModuleFederation['loaderHook'];
   getEntryUrl?: (url: string) => string;
   resourceContext?: ResourceLoadContext;
+  timeout?: number;
 }): Promise<RemoteEntryExports> {
   const { entryExports: remoteEntryExports } = getRemoteEntryExports(
     name,
@@ -187,6 +189,7 @@ async function loadEntryScript({
   const url = getEntryUrl ? getEntryUrl(entry) : entry;
   return loadScript(url, {
     attrs: {},
+    timeout,
     createScriptHook: (url, attrs) => {
       const res = loaderHook.lifecycle.createScript.emit({
         url,
@@ -244,12 +247,14 @@ async function loadEntryDom({
   loaderHook,
   getEntryUrl,
   resourceContext,
+  timeout,
 }: {
   remoteInfo: RemoteInfo;
   remoteEntryExports?: RemoteEntryExports;
   loaderHook: ModuleFederation['loaderHook'];
   getEntryUrl?: (url: string) => string;
   resourceContext?: ResourceLoadContext;
+  timeout?: number;
 }) {
   const { entry, entryGlobalName: globalName, name, type } = remoteInfo;
   if (isEsmRemoteType(type)) {
@@ -268,6 +273,7 @@ async function loadEntryDom({
     loaderHook,
     getEntryUrl,
     resourceContext,
+    timeout,
   });
 }
 
@@ -388,6 +394,7 @@ export async function getRemoteEntry(params: {
               loaderHook,
               getEntryUrl,
               resourceContext,
+              timeout: origin.options.loadEntryTimeout,
             })
           : loadEntryNode({ remoteInfo, loaderHook, resourceContext });
       })

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

@@ -233,6 +233,7 @@ function waitForScriptPreload({
         );
       },
       attrs,
+      timeout: host.options.loadEntryTimeout,
       createScriptHook: (hookUrl: string, hookAttrs: any) => {
         const res = host.loaderHook.lifecycle.createScript.emit({
           url: hookUrl,

packages/sdk/__tests__/dom.spec.ts

@@ -86,6 +86,36 @@ describe('createScript', () => {
       expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 20000);
     });
 
+    it('should use the timeout passed to createScript', () => {
+      const url = 'https://example.com/script.js';
+      const cb = jest.fn();
+      createScript({ url, cb, timeout: 45000 });
+
+      expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 45000);
+    });
+
+    it('should let the createScriptHook timeout override the passed timeout', () => {
+      const url = 'https://example.com/script.js';
+      const cb = jest.fn();
+      createScript({
+        url,
+        cb,
+        attrs: {},
+        timeout: 45000,
+        createScriptHook: () => ({ timeout: 5000 }),
+      });
+
+      expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 5000);
+    });
+
+    it('should not start a timer when the timeout is Infinity', () => {
+      const url = 'https://example.com/script.js';
+      const cb = jest.fn();
+      createScript({ url, cb, timeout: Infinity });
+
+      expect(setTimeout).not.toHaveBeenCalled();
+    });
+
     it('should use the timeout specified in the createScriptHook', () => {
       const url = 'https://example.com/script.js';
       const cb = jest.fn();

packages/sdk/src/dom.ts

@@ -28,19 +28,26 @@ export function isStaticResourcesEqual(url1: string, url2: string): boolean {
   return relativeUrl1 === relativeUrl2;
 }
 
+export const DEFAULT_SCRIPT_TIMEOUT = 20000;
+
 export function createScript(info: {
   url: string;
   cb?: (value: void | PromiseLike<void>) => void;
   onErrorCallback?: (error: Error) => void;
   attrs?: Record<string, any>;
   needDeleteScript?: boolean;
   createScriptHook?: CreateScriptHookDom;
+  /** Load timeout in ms; a `createScriptHook` return value still overrides it. `Infinity` disables the timer. */
+  timeout?: number;
 }): { script: HTMLScriptElement; needAttach: boolean } {
   // Retrieve the existing script element by its src attribute
   let script: HTMLScriptElement | null = null;
   let needAttach = true;
-  let timeout = 20000;
-  let timeoutId: NodeJS.Timeout;
+  let timeout =
+    typeof info.timeout === 'number' && info.timeout > 0
+      ? info.timeout
+      : DEFAULT_SCRIPT_TIMEOUT;
+  let timeoutId: NodeJS.Timeout | undefined;
   const scripts = document.getElementsByTagName('script');
 
   for (let i = 0; i < scripts.length; i++) {
@@ -162,9 +169,11 @@ export function createScript(info: {
   script.onerror = onScriptComplete.bind(null, script.onerror);
   script.onload = onScriptComplete.bind(null, script.onload);
 
-  timeoutId = setTimeout(() => {
-    onScriptComplete(null, { type: 'error', isTimeout: true });
-  }, timeout);
+  if (Number.isFinite(timeout)) {
+    timeoutId = setTimeout(() => {
+      onScriptComplete(null, { type: 'error', isTimeout: true });
+    }, timeout);
+  }
 
   return { script, needAttach };
 }
@@ -295,9 +304,10 @@ export function loadScript(
   info: {
     attrs?: Record<string, any>;
     createScriptHook?: CreateScriptHookDom;
+    timeout?: number;
   },
 ) {
-  const { attrs = {}, createScriptHook } = info;
+  const { attrs = {}, createScriptHook, timeout } = info;
   return new Promise<void>((resolve, reject) => {
     const { script, needAttach } = createScript({
       url,
@@ -309,6 +319,7 @@ export function loadScript(
       },
       createScriptHook,
       needDeleteScript: true,
+      timeout,
     });
     needAttach && document.head.appendChild(script);
   });