perf(externals-loading): merge multiple fetchBundle calls for the same URL

.changeset/merge-fetchbundle-calls.md

@@ -0,0 +1,5 @@
+---
+"@lynx-js/externals-loading-webpack-plugin": patch
+---
+
+perf: optimize external bundle loading by merging multiple `fetchBundle` calls for the same URL into a single request.

packages/webpack/externals-loading-webpack-plugin/package.json

@@ -38,7 +38,9 @@
   "devDependencies": {
     "@lynx-js/test-tools": "workspace:*",
     "@rspack/core": "catalog:rspack",
-    "foo": "./test/foo"
+    "bar": "./test/helpers/external-bundle-mock/bar",
+    "baz": "./test/helpers/external-bundle-mock/baz",
+    "foo": "./test/helpers/external-bundle-mock/foo"
   },
   "engines": {
     "node": ">=18"

packages/webpack/externals-loading-webpack-plugin/src/index.ts

@@ -282,8 +282,8 @@ export class ExternalsLoadingPlugin {
       #genExternalsLoadingCode(
         chunkLayer: string,
       ): string {
-        const fetchCode: string[] = [];
-        const loadCode: string[] = [];
+        const url2fetchCode: Map<string, string> = new Map();
+        const loadCode: Set<string> = new Set();
         // filter duplicate externals by libraryName or package name to avoid loading the same external multiple times. We keep the last one.
         const externalsMap = new Map<
           string | string[],
@@ -377,8 +377,7 @@ function createLoadExternalSync(handler, sectionPath, timeout) {
 
         const hasUrlLibraryNamePairInjected = new Set();
 
-        for (let i = 0; i < externals.length; i++) {
-          const [pkgName, external] = externals[i]!;
+        for (const [pkgName, external] of externals) {
           const {
             libraryName,
             url,
@@ -404,8 +403,9 @@ function createLoadExternalSync(handler, sectionPath, timeout) {
           }
           hasUrlLibraryNamePairInjected.add(hash);
 
-          fetchCode.push(
-            `const handler${i} = lynx.fetchBundle(${JSON.stringify(url)}, {});`,
+          url2fetchCode.set(
+            url,
+            `lynx.fetchBundle(${JSON.stringify(url)}, {});`,
           );
 
           const mountVar = `${
@@ -414,16 +414,18 @@ function createLoadExternalSync(handler, sectionPath, timeout) {
             )
           }[${JSON.stringify(libraryNameStr)}]`;
           if (async) {
-            loadCode.push(
-              `${mountVar} = ${mountVar} === undefined ? createLoadExternalAsync(handler${i}, ${
-                JSON.stringify(layerOptions.sectionPath)
-              }) : ${mountVar};`,
+            loadCode.add(
+              `${mountVar} = ${mountVar} === undefined ? createLoadExternalAsync(handler${
+                [...url2fetchCode.keys()].indexOf(url)
+              }, ${JSON.stringify(layerOptions.sectionPath)}) : ${mountVar};`,
             );
             continue;
           }
 
-          loadCode.push(
-            `${mountVar} = ${mountVar} === undefined ? createLoadExternalSync(handler${i}, ${
+          loadCode.add(
+            `${mountVar} = ${mountVar} === undefined ? createLoadExternalSync(handler${
+              [...url2fetchCode.keys()].indexOf(url)
+            }, ${
               JSON.stringify(layerOptions.sectionPath)
             }, ${timeout}) : ${mountVar};`,
           );
@@ -432,9 +434,11 @@ function createLoadExternalSync(handler, sectionPath, timeout) {
         return [
           runtimeGlobalsInit,
           loadExternalFunc,
-          fetchCode,
-          loadCode,
-        ].flat().join('\n');
+          ...[...url2fetchCode.values()].map((fetchCode, index) =>
+            `const handler${index} = ${fetchCode};`
+          ),
+          ...loadCode,
+        ].join('\n');
       }
     }
 

packages/webpack/externals-loading-webpack-plugin/test/cases.test.ts

@@ -8,4 +8,13 @@ import { describeCases } from '@lynx-js/test-tools';
 describeCases({
   name: 'externals-loading',
   casePath: path.join(__dirname, 'cases'),
+  beforeExecute: () => {
+    if (lynx[Symbol.for('__LYNX_EXTERNAL_GLOBAL__')]) {
+      delete lynx[Symbol.for('__LYNX_EXTERNAL_GLOBAL__')];
+    }
+  },
 });
+
+declare global {
+  var lynx: Record<symbol, unknown>;
+}

packages/webpack/externals-loading-webpack-plugin/test/cases/externals-loading/merge-fetchBundle-calls/index.js

@@ -0,0 +1,30 @@
+import { add } from 'foo';
+import { minus } from 'bar';
+import { mul } from 'baz/sub1';
+import { div } from 'baz/sub2';
+import { exp } from 'qux';
+
+console.info(add(1, 2));
+console.info(minus(1, 2));
+console.info(mul(2, 3));
+console.info(div(6, 2));
+console.info(exp(2, 3));
+
+it('should merge fetchBundle calls', async () => {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+
+  const background = fs.readFileSync(
+    path.resolve(__dirname, 'main:background.js'),
+    'utf-8',
+  );
+  const mainThread = fs.readFileSync(
+    path.resolve(__dirname, 'main:main-thread.js'),
+    'utf-8',
+  );
+
+  const backgroundFetchBundleCalls = background.split('fetchBundle' + '(');
+  const mainThreadFetchBundleCalls = mainThread.split('fetchBundle' + '(');
+  expect(backgroundFetchBundleCalls.length).toBe(2);
+  expect(mainThreadFetchBundleCalls.length).toBe(2);
+});

packages/webpack/externals-loading-webpack-plugin/test/cases/externals-loading/merge-fetchBundle-calls/rspack.config.js

@@ -0,0 +1,80 @@
+import { createConfig } from '../../../helpers/create-config.js';
+
+/** @type {import('@rspack/core').Configuration} */
+export default {
+  context: __dirname,
+  ...createConfig(
+    {
+      backgroundLayer: 'background',
+      mainThreadLayer: 'main-thread',
+      externals: {
+        'foo': {
+          libraryName: 'Foo',
+          url: 'https://example.com/common.bundle',
+          async: false,
+          background: {
+            sectionPath: 'background',
+          },
+          mainThread: {
+            sectionPath: 'mainThread',
+          },
+        },
+        'bar': {
+          libraryName: 'Bar',
+          url: 'https://example.com/common.bundle',
+          async: false,
+          background: {
+            sectionPath: 'Bar__background',
+          },
+          mainThread: {
+            sectionPath: 'Bar__mainThread',
+          },
+        },
+        'baz/sub1': {
+          libraryName: ['Baz', 'Sub1'],
+          url: 'https://example.com/common.bundle',
+          async: false,
+          background: {
+            sectionPath: 'Baz__background',
+          },
+          mainThread: {
+            sectionPath: 'Baz__mainThread',
+          },
+        },
+        'baz/sub2': {
+          libraryName: ['Baz', 'Sub2'],
+          url: 'https://example.com/common.bundle',
+          async: false,
+          background: {
+            sectionPath: 'Baz__background',
+          },
+          mainThread: {
+            sectionPath: 'Baz__mainThread',
+          },
+        },
+        'baz/sub2?async': {
+          libraryName: ['Baz', 'Sub2'],
+          url: 'https://example.com/common.bundle',
+          async: true,
+          background: {
+            sectionPath: 'Baz__background',
+          },
+          mainThread: {
+            sectionPath: 'Baz__mainThread',
+          },
+        },
+        'qux': {
+          libraryName: 'Qux',
+          url: 'https://example.com/common.bundle',
+          async: true,
+          background: {
+            sectionPath: 'Qux__background',
+          },
+          mainThread: {
+            sectionPath: 'Qux__mainThread',
+          },
+        },
+      },
+    },
+  ),
+};

packages/webpack/externals-loading-webpack-plugin/test/cases/externals-loading/merge-fetchBundle-calls/test.config.cjs

@@ -0,0 +1,7 @@
+/** @type {import("@lynx-js/test-tools").TConfigCaseConfig} */
+module.exports = {
+  bundlePath: [
+    'main:main-thread.js',
+    'main:background.js',
+  ],
+};

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/bar/index.js

@@ -0,0 +1,6 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+export function minus(a, b) {
+  return a - b;
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/bar/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "bar",
+  "private": true
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/baz/common.js

@@ -0,0 +1,7 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+export function log(msg) {
+  console.info(msg);
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/baz/index.js

@@ -0,0 +1,6 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+export * as Sub1 from './sub1/index.js';
+export * as Sub2 from './sub2/index.js';

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/baz/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "baz",
+  "private": true
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/baz/sub1/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { log } from '../common.js';
+
+export function mul(a, b) {
+  log(`mul(${a}, ${b})`);
+  return a * b;
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/baz/sub2/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { log } from '../common.js';
+
+export function div(a, b) {
+  log(`div(${a}, ${b})`);
+  return a / b;
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/qux/index.js

@@ -0,0 +1,6 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+export function exp(a, b) {
+  return a ** b;
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/external-bundle-mock/qux/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "qux",
+  "private": true
+}

packages/webpack/externals-loading-webpack-plugin/test/helpers/setup-env.js

@@ -1,18 +1,22 @@
 // Copyright 2025 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
-import { createRequire } from 'node:module';
+import * as bar from './external-bundle-mock/bar/index.js';
+import * as baz from './external-bundle-mock/baz/index.js';
+import * as foo from './external-bundle-mock/foo/index.js';
+import * as qux from './external-bundle-mock/qux/index.js';
 
 __injectGlobals(globalThis);
 
-const require = createRequire(import.meta.url);
-
-// eslint-disable-next-line import/no-commonjs
-const foo = require('../foo/index');
-
 const CustomSections = {
   'background': foo,
   'mainThread': foo,
+  'Bar__background': bar,
+  'Bar__mainThread': bar,
+  'Baz__background': baz,
+  'Baz__mainThread': baz,
+  'Qux__background': qux,
+  'Qux__mainThread': qux,
 };
 
 function __injectGlobals(target) {