@lynx-js/externals-loading-webpack-plugin-canary 0.0.0 → 0.0.1-canary-20251222-e9baa022

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# @lynx-js/externals-loading-webpack-plugin
+
+## 0.0.1-canary-20251222035050-e9baa022376ae79290d6811fa30597aece884b3f
+
+### Patch Changes
+
+- Introduce `@lynx-js/externals-loading-webpack-plugin`. It will help you to load externals built by `@lynx-js/lynx-bundle-rslib-config`. ([#1924](https://github.com/lynx-family/lynx-stack/pull/1924))
+
+  ```js
+  // webpack.config.js
+  import { ExternalsLoadingPlugin } from "@lynx-js/externals-loading-webpack-plugin";
+
+  export default {
+    plugins: [
+      new ExternalsLoadingPlugin({
+        mainThreadLayer: "main-thread",
+        backgroundLayer: "background",
+        externals: {
+          lodash: {
+            url: "http://lodash.lynx.bundle",
+            background: { sectionPath: "background" },
+            mainThread: { sectionPath: "main-thread" },
+          },
+        },
+      }),
+    ],
+  };
+  ```

package/README.md

@@ -0,0 +1,3 @@
+<h2 align="center">@lynx-js/externals-loading-webpack-plugin</h2>
+
+A webpack plugin to support loading externals in Lynx.

package/lib/index.d.ts

@@ -0,0 +1,223 @@
+/**
+ * @packageDocumentation
+ *
+ * A webpack plugin to load externals in Lynx. Use `lynx.fetchBundle()` and `lynx.loadScript()` API to load and parse the externals.
+ *
+ * @remarks
+ * Requires Lynx version 3.5 or later.
+ */
+import type { Compiler } from '@rspack/core';
+/**
+ * The options of the `ExternalsLoadingPlugin`.
+ *
+ * @public
+ */
+export interface ExternalsLoadingPluginOptions {
+    /**
+     * The name of the main thread layer.
+     */
+    mainThreadLayer: string;
+    /**
+     * The name of the background layer.
+     */
+    backgroundLayer: string;
+    /**
+     * Specify the externals to be loaded. The externals should be Lynx Bundles.
+     *
+     * @example
+     *
+     * Load `lodash` library in background layer and `main-thread` layer.
+     *
+     * ```js
+     * module.exports = {
+     *  plugins: [
+     *    new ExternalsLoadingPlugin({
+     *      externals: {
+     *        lodash: {
+     *          url: 'http://lodash.lynx.bundle',
+     *          background: { sectionPath: 'background' },
+     *          mainThread: { sectionPath: 'mainThread' },
+     *        },
+     *      },
+     *    }),
+     *  ],
+     * };
+     * ```
+     *
+     * @example
+     *
+     * Load `lodash` library only in background layer.
+     *
+     * ```js
+     * module.exports = {
+     *  plugins: [
+     *    new ExternalsLoadingPlugin({
+     *      externals: {
+     *        lodash: {
+     *          url: 'http://lodash.lynx.bundle',
+     *          background: { sectionPath: 'background' }
+     *        },
+     *      },
+     *    }),
+     *  ],
+     * };
+     * ```
+     */
+    externals: Record<string, {
+        /**
+         * The bundle(lynx.bundle) url of the library. The library source should be placed in `customSections`.
+         */
+        url: string;
+        /**
+         * The name of the library. Same as https://webpack.js.org/configuration/externals/#string.
+         *
+         * By default, the library name is the same as the externals key. For example:
+         *
+         * The config
+         *
+         * ```js
+         * ExternalsLoadingPlugin({
+         *   externals: {
+         *     lodash: {
+         *       url: '……',
+         *     }
+         *   }
+         * })
+         * ```
+         *
+         * Will generate the following webpack externals config:
+         *
+         * ```js
+         * externals: {
+         *   lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].lodash',
+         * }
+         * ```
+         *
+         * If one external bundle contains multiple modules, should set the same library name to ensure it's loaded only once. For example:
+         *
+         * ```js
+         * ExternalsLoadingPlugin({
+         *   externals: {
+         *     lodash: {
+         *       libraryName: 'Lodash',
+         *       url: '……',
+         *     },
+         *     'lodash-es': {
+         *       libraryName: 'Lodash',
+         *       url: '……',
+         *     }
+         *   }
+         * })
+         * ```
+         * Will generate the following webpack externals config:
+         *
+         * ```js
+         * externals: {
+         *   lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
+         *   'lodash-es': 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
+         * }
+         * ```
+         *
+         * You can pass an array to specify subpath of the external. Same as https://webpack.js.org/configuration/externals/#string-1. For example:
+         *
+         * ```js
+         * ExternalsLoadingPlugin({
+         *   externals: {
+         *     preact: {
+         *       libraryName: ['ReactLynx', 'Preact'],
+         *       url: '……',
+         *     },
+         *   }
+         * })
+         * ```
+         *
+         * Will generate the following webpack externals config:
+         *
+         * ```js
+         * externals: {
+         *   preact: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].ReactLynx.Preact',
+         * }
+         * ```
+         *
+         * @defaultValue `undefined`
+         *
+         * @example `Lodash`
+         */
+        libraryName?: string | string[];
+        /**
+         * Whether the source should be loaded asynchronously or not.
+         *
+         * @defaultValue `true`
+         */
+        async?: boolean;
+        /**
+         * The options of the background layer.
+         *
+         * @defaultValue `undefined`
+         */
+        background?: LayerOptions;
+        /**
+         * The options of the main-thread layer.
+         *
+         * @defaultValue `undefined`
+         */
+        mainThread?: LayerOptions;
+        /**
+         * The wait time in milliseconds.
+         *
+         * @defaultValue `2000`
+         */
+        timeout?: number;
+    }>;
+}
+/**
+ * The options of the background or main-thread layer.
+ *
+ * @public
+ */
+export interface LayerOptions {
+    /**
+     * The path in `customSections`.
+     */
+    sectionPath: string;
+}
+/**
+ * The webpack plugin to load lynx external bundles.
+ *
+ * @example
+ * ```js
+ * // webpack.config.js
+ * import { ExternalsLoadingPlugin } from '@lynx-js/externals-loading-webpack-plugin';
+ *
+ * export default {
+ *   plugins: [
+ *     new ExternalsLoadingPlugin({
+ *       mainThreadLayer: 'main-thread',
+ *       backgroundLayer: 'background',
+ *       mainThreadChunks: ['index__main-thread'],
+ *       backgroundChunks: ['index'],
+ *       externals: {
+ *        'lodash': {
+ *          url: 'http://lodash.lynx.bundle',
+ *          async: true,
+ *          background: {
+ *            sectionPath: 'background',
+ *          },
+ *          mainThread: {
+ *            sectionPath: 'mainThread',
+ *          },
+ *        },
+ *       }
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class ExternalsLoadingPlugin {
+    #private;
+    private options;
+    constructor(options: ExternalsLoadingPluginOptions);
+    apply(compiler: Compiler): void;
+}

package/lib/index.js

@@ -0,0 +1,206 @@
+// 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.
+function getLynxExternalGlobal() {
+    return `lynx[Symbol.for('__LYNX_EXTERNAL_GLOBAL__')]`;
+}
+/**
+ * The webpack plugin to load lynx external bundles.
+ *
+ * @example
+ * ```js
+ * // webpack.config.js
+ * import { ExternalsLoadingPlugin } from '@lynx-js/externals-loading-webpack-plugin';
+ *
+ * export default {
+ *   plugins: [
+ *     new ExternalsLoadingPlugin({
+ *       mainThreadLayer: 'main-thread',
+ *       backgroundLayer: 'background',
+ *       mainThreadChunks: ['index__main-thread'],
+ *       backgroundChunks: ['index'],
+ *       externals: {
+ *        'lodash': {
+ *          url: 'http://lodash.lynx.bundle',
+ *          async: true,
+ *          background: {
+ *            sectionPath: 'background',
+ *          },
+ *          mainThread: {
+ *            sectionPath: 'mainThread',
+ *          },
+ *        },
+ *       }
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @public
+ */
+export class ExternalsLoadingPlugin {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    apply(compiler) {
+        const { RuntimeModule } = compiler.webpack;
+        const externalsLoadingPluginOptions = this.options;
+        class ExternalsLoadingRuntimeModule extends RuntimeModule {
+            options;
+            constructor(options) {
+                super('externals-loading-runtime');
+                this.options = options;
+            }
+            generate() {
+                if (!this.chunk?.name || !externalsLoadingPluginOptions.externals) {
+                    return '';
+                }
+                return this.#genExternalsLoadingCode(this.options.layer);
+            }
+            #genExternalsLoadingCode(chunkLayer) {
+                const fetchCode = [];
+                const loadCode = [];
+                // 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();
+                let layer;
+                if (chunkLayer === externalsLoadingPluginOptions.backgroundLayer) {
+                    layer = 'background';
+                }
+                else if (chunkLayer === externalsLoadingPluginOptions.mainThreadLayer) {
+                    layer = 'mainThread';
+                }
+                else {
+                    return '';
+                }
+                for (const [pkgName, external] of Object.entries(externalsLoadingPluginOptions.externals)) {
+                    externalsMap.set(external.libraryName ?? pkgName, external);
+                }
+                const externals = Array.from(externalsMap.entries());
+                if (externals.length === 0) {
+                    return '';
+                }
+                const runtimeGlobalsInit = `${getLynxExternalGlobal()} = {};`;
+                const loadExternalFunc = `
+function createLoadExternalAsync(handler, sectionPath) {
+  return new Promise((resolve, reject) => {
+    handler.then((response) => {
+      if (response.code === 0) {
+        try {
+          const result = lynx.loadScript(sectionPath, { bundleName: response.url });
+          resolve(result)
+        } catch (error) {
+          reject(new Error('Failed to load script ' + sectionPath + ' in ' + response.url, { cause: error }))
+        }
+      } else {
+        reject(new Error('Failed to fetch external source ' + response.url + ' . The response is ' + JSON.stringify(response), { cause: response }));
+      }
+    })
+  })
+}
+function createLoadExternalSync(handler, sectionPath, timeout) {
+  const response = handler.wait(timeout)
+  if (response.code === 0) {
+    try  {
+      const result = lynx.loadScript(sectionPath, { bundleName: response.url });
+      return result
+    } catch (error) {
+      throw new Error('Failed to load script ' + sectionPath + ' in ' + response.url, { cause: error })
+    }
+  } else {
+    throw new Error('Failed to fetch external source ' + response.url + ' . The response is ' + JSON.stringify(response), { cause: response })
+  }
+}
+`;
+                const hasUrlLibraryNamePairInjected = new Set();
+                for (let i = 0; i < externals.length; i++) {
+                    const [pkgName, external] = externals[i];
+                    const { libraryName, url, async = true, timeout: timeoutInMs = 2000, } = external;
+                    const layerOptions = external[layer];
+                    // Lynx fetchBundle timeout is in seconds
+                    const timeout = timeoutInMs / 1000;
+                    if (!layerOptions?.sectionPath) {
+                        continue;
+                    }
+                    const libraryNameWithDefault = libraryName ?? pkgName;
+                    const libraryNameStr = Array.isArray(libraryNameWithDefault)
+                        ? libraryNameWithDefault[0]
+                        : libraryNameWithDefault;
+                    const hash = `${url}-${libraryNameStr}`;
+                    if (hasUrlLibraryNamePairInjected.has(hash)) {
+                        continue;
+                    }
+                    hasUrlLibraryNamePairInjected.add(hash);
+                    fetchCode.push(`const handler${i} = lynx.fetchBundle(${JSON.stringify(url)}, {});`);
+                    if (async) {
+                        loadCode.push(`${getLynxExternalGlobal()}[${JSON.stringify(libraryNameStr)}] = createLoadExternalAsync(handler${i}, ${JSON.stringify(layerOptions.sectionPath)});`);
+                        continue;
+                    }
+                    loadCode.push(`${getLynxExternalGlobal()}[${JSON.stringify(libraryNameStr)}] = createLoadExternalSync(handler${i}, ${JSON.stringify(layerOptions.sectionPath)}, ${timeout});`);
+                }
+                return [
+                    runtimeGlobalsInit,
+                    loadExternalFunc,
+                    fetchCode,
+                    loadCode,
+                ].flat().join('\n');
+            }
+        }
+        compiler.hooks.environment.tap(ExternalsLoadingPlugin.name, () => {
+            compiler.options.externals = [
+                ...(Array.isArray(compiler.options.externals)
+                    ? compiler.options.externals
+                    : (typeof compiler.options.externals === 'undefined'
+                        ? []
+                        : [compiler.options.externals])),
+                this.#genExternalsConfig(),
+            ];
+        });
+        compiler.hooks.compilation.tap(ExternalsLoadingRuntimeModule.name, compilation => {
+            compilation.hooks.additionalTreeRuntimeRequirements
+                .tap(ExternalsLoadingRuntimeModule.name, (chunk) => {
+                const modules = compilation.chunkGraph.getChunkModulesIterable(chunk);
+                let layer;
+                for (const module of modules) {
+                    if (module.layer) {
+                        layer = module.layer;
+                        break;
+                    }
+                }
+                if (!layer) {
+                    // Skip chunks without a layer
+                    return;
+                }
+                compilation.addRuntimeModule(chunk, new ExternalsLoadingRuntimeModule({ layer }));
+            });
+        });
+    }
+    /**
+     * If the external is async, use `promise` external type; otherwise, use `var` external type.
+     */
+    #genExternalsConfig() {
+        const { externals, backgroundLayer, mainThreadLayer } = this.options;
+        const externalDeps = new Set(Object.keys(externals));
+        return ({ request, contextInfo }, callback) => {
+            const currentLayer = contextInfo?.issuerLayer === mainThreadLayer
+                ? 'mainThread'
+                : (contextInfo?.issuerLayer === backgroundLayer
+                    ? 'background'
+                    : undefined);
+            if (request
+                && externalDeps.has(request)
+                && currentLayer
+                && externals[request]?.[currentLayer]) {
+                const isAsync = externals[request]?.async ?? true;
+                const libraryName = externals[request]?.libraryName ?? request;
+                return callback(undefined, [
+                    getLynxExternalGlobal(),
+                    ...(Array.isArray(libraryName) ? libraryName : [libraryName]),
+                ], isAsync ? 'promise' : undefined);
+            }
+            // Continue without externalizing the import
+            callback();
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,9 +1,46 @@
 {
   "name": "@lynx-js/externals-loading-webpack-plugin-canary",
-  "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.1-canary-20251222-e9baa022",
   "description": "A webpack plugin to load lynx external bundles.",
-  "main": "index.js",
-  "keywords": [],
-  "license": "Apache-2.0"
-}
+  "keywords": [
+    "webpack",
+    "Lynx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lynx-family/lynx-stack.git",
+    "directory": "packages/webpack/externals-loading-webpack-plugin"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Hengchang Lu",
+    "email": "luhengchang228@gmail.com"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "!lib/**/*.js.map",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@rspack/core": "1.6.6",
+    "foo": "./test/foo",
+    "@lynx-js/test-tools": "0.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "api-extractor": "api-extractor run --verbose",
+    "test": "vitest"
+  }
+}

package/index.js

@@ -1 +0,0 @@
-export {}