@lynx-js/external-bundle-rsbuild-plugin 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @lynx-js/external-bundle-rsbuild-plugin
 
+## 0.4.0
+
+### Minor Changes
+
+- The `reactlynx` externals preset accepts `{ async: true }`, mounting ReactLynx as an awaited promise so async runtimes can load it via `fetchBundle().then` (the sync array form reads `React.memo` etc. off a pending promise and gets `undefined`). Externals presets resolve per environment (`environmentName` is available in the preset context): `lynx` / `lynx-*` environments use `react.lynx.bundle`, other environments (e.g. `web`) use the web-encoded `@lynx-js/react-umd/{dev,prod}-web` `react.web.bundle` — `async` only controls the mount form. ([#2934](https://github.com/lynx-family/lynx-stack/pull/2934))
+
+### Patch Changes
+
+- Updated dependencies [[`34318ea`](https://github.com/lynx-family/lynx-stack/commit/34318ea3432b6484a383707458ed9c4ee19e2097)]:
+  - @lynx-js/externals-loading-webpack-plugin@0.2.1
+
 ## 0.3.0
 
 ### Minor Changes

package/lib/index.d.ts

@@ -28,6 +28,19 @@ export interface ReactLynxExternalsPresetOptions {
      * @defaultValue `'@lynx-js/react-umd'`
      */
     reactUmdPackageName?: string;
+    /**
+     * Load the ReactLynx runtime bundle asynchronously, for the web target.
+     *
+     * The web runtime (`@lynx-js/web-core`) can only fetch external bundles
+     * asynchronously (`fetchBundle().then`), so ReactLynx must be mounted as a
+     * promise that consuming modules await before reading a subpath (otherwise
+     * `React.memo` etc. are read off a pending promise and are `undefined`).
+     * Enabling this also resolves the web-encoded `@lynx-js/react-umd/{dev,prod}-web`
+     * bundle and defaults `bundlePath` to `react.web.bundle`.
+     *
+     * @defaultValue `false`
+     */
+    async?: boolean;
     /**
      * Override the runtime bundle URL directly.
      *
@@ -65,6 +78,16 @@ export interface ExternalsPresetContext {
      * The current Rsbuild project root path.
      */
     rootPath: string;
+    /**
+     * The Rsbuild environment being resolved (e.g. `'lynx'`, `'web'`).
+     *
+     * @remarks
+     *
+     * Presets use this to pick environment-specific artifacts — for example the
+     * built-in `reactlynx` preset resolves the web-encoded `react.web.bundle`
+     * for the `web` environment and `react.lynx.bundle` otherwise.
+     */
+    environmentName?: string;
 }
 /**
  * Definition for a named externals preset.

package/lib/index.js

@@ -13,6 +13,7 @@ import { ExternalsLoadingPlugin } from '@lynx-js/externals-loading-webpack-plugi
 const require = createRequire(import.meta.url);
 const DEFAULT_REACT_UMD_PACKAGE_NAME = '@lynx-js/react-umd';
 const REACT_LYNX_BUNDLE_FILE_NAME = 'react.lynx.bundle';
+const REACT_LYNX_WEB_BUNDLE_FILE_NAME = 'react.web.bundle';
 const reactLynxExternalTemplate = {
     'react': {
         libraryName: ['ReactLynx', 'React'],
@@ -125,28 +126,39 @@ export function normalizeBundlePath(bundlePath) {
 function createBuiltInExternalsPresetDefinitions() {
     return {
         reactlynx: {
-            resolveExternals(value) {
-                return createReactLynxExternals(normalizeReactLynxPreset(value));
+            resolveExternals(value, context) {
+                return createReactLynxExternals(normalizeReactLynxPreset(value), isWebEnvironment(context));
             },
             resolveManagedAssets(value, context) {
                 const preset = normalizeReactLynxPreset(value);
                 if (!preset || preset.url) {
                     return new Map();
                 }
+                const isWeb = isWebEnvironment(context);
                 return new Map([
                     [
-                        getDefaultReactLynxBundlePath(preset),
-                        getReactLynxBundlePath(context.rootPath, preset.reactUmdPackageName ?? DEFAULT_REACT_UMD_PACKAGE_NAME),
+                        getDefaultReactLynxBundlePath(preset, isWeb),
+                        getReactLynxBundlePath(context.rootPath, preset.reactUmdPackageName ?? DEFAULT_REACT_UMD_PACKAGE_NAME, isWeb),
                     ],
                 ]);
             },
         },
     };
 }
-function getReactLynxBundlePath(rootPath, reactUmdPackageName) {
-    const reactUmdExport = process.env['NODE_ENV'] === 'production'
-        ? `${reactUmdPackageName}/prod`
-        : `${reactUmdPackageName}/dev`;
+// The bundle encoding follows the target environment: `lynx` / `lynx-*`
+// environments decode `tasm` bundles (mirroring rspeedy's `isLynx`
+// convention), every other environment (e.g. `web`) decodes web-encoded
+// bundles. `async` only controls how the external is mounted.
+function isWebEnvironment(context) {
+    const name = context.environmentName;
+    if (name === undefined) {
+        return false;
+    }
+    return name !== 'lynx' && !name.startsWith('lynx-');
+}
+function getReactLynxBundlePath(rootPath, reactUmdPackageName, isWeb) {
+    const variant = process.env['NODE_ENV'] === 'production' ? 'prod' : 'dev';
+    const reactUmdExport = `${reactUmdPackageName}/${variant}${isWeb ? '-web' : ''}`;
     try {
         return require.resolve(reactUmdExport, { paths: [rootPath] });
     }
@@ -238,14 +250,15 @@ function resolvePresetExternals(externalsPresets, presetDefinitions, context) {
     }
     return { externals, managedAssets };
 }
-function createReactLynxExternals(preset) {
+function createReactLynxExternals(preset, isWeb) {
     const bundleReference = preset?.url
         ? { url: preset.url }
-        : { bundlePath: getDefaultReactLynxBundlePath(preset) };
+        : { bundlePath: getDefaultReactLynxBundlePath(preset, isWeb) };
     return Object.fromEntries(Object.entries(reactLynxExternalTemplate).map(([request, external]) => [
         request,
         {
             ...external,
+            ...(preset?.async === undefined ? {} : { async: preset.async }),
             ...bundleReference,
         },
     ]));
@@ -278,8 +291,13 @@ class EmitManagedBundleAssetsPlugin {
         });
     }
 }
-function getDefaultReactLynxBundlePath(preset) {
-    return normalizeBundlePath(preset?.bundlePath ?? REACT_LYNX_BUNDLE_FILE_NAME);
+function getDefaultReactLynxBundlePath(preset, isWeb) {
+    if (preset?.bundlePath) {
+        return normalizeBundlePath(preset.bundlePath);
+    }
+    return isWeb
+        ? REACT_LYNX_WEB_BUNDLE_FILE_NAME
+        : REACT_LYNX_BUNDLE_FILE_NAME;
 }
 function joinUrlPath(base, bundlePath) {
     const normalizedBase = base ?? '/';
@@ -312,13 +330,6 @@ function getManagedBundleAssets(options, presetManagedAssets, api) {
     }
     return assets;
 }
-function getLocalBundleAssets(options, presetManagedAssets, api, serverBase) {
-    const assets = new Map();
-    for (const [bundlePath, sourcePath] of getManagedBundleAssets(options, presetManagedAssets, api)) {
-        assets.set(joinUrlPath(serverBase, bundlePath), sourcePath);
-    }
-    return assets;
-}
 function resolvePluginExternals(externals) {
     if (!externals) {
         return {};
@@ -386,12 +397,16 @@ export function pluginExternalBundle(options) {
         name: 'lynx:external-bundle',
         setup(api) {
             const presetDefinitions = resolvePresetDefinitions(options.externalsPresetDefinitions);
-            const presetResolution = resolvePresetExternals(options.externalsPresets, presetDefinitions, {
-                rootPath: api.context.rootPath,
-            });
+            // Presets resolve per environment (in `modifyRspackConfig`, where the
+            // environment name is known); this map collects every environment's
+            // local bundle assets for the dev-server middleware, which reads it at
+            // request time.
+            const localBundleAssets = new Map();
+            let serverBase;
             api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
-                const localBundleAssets = getLocalBundleAssets(options, presetResolution.managedAssets, api, config.server?.base);
-                if (localBundleAssets.size === 0) {
+                serverBase = config.server?.base;
+                if (options.externals === undefined
+                    && options.externalsPresets === undefined) {
                     return config;
                 }
                 return mergeRsbuildConfig(config, {
@@ -423,17 +438,24 @@ export function pluginExternalBundle(options) {
                     },
                 });
             });
-            api.modifyRspackConfig((config) => {
+            api.modifyRspackConfig((config, { environment }) => {
                 const LAYERS = api.useExposed(Symbol.for('LAYERS'));
                 if (!LAYERS) {
                     throw new Error('external-bundle-rsbuild-plugin requires exposed `LAYERS`. Please install a DSL plugin, for example `pluginReactLynx` for ReactLynx.');
                 }
+                const presetResolution = resolvePresetExternals(options.externalsPresets, presetDefinitions, {
+                    rootPath: api.context.rootPath,
+                    environmentName: environment.name,
+                });
                 const explicitExternals = resolvePluginExternals(options.externals);
                 const externals = {
                     ...presetResolution.externals,
                     ...explicitExternals,
                 };
                 const managedBundleAssets = getManagedBundleAssets(options, presetResolution.managedAssets, api);
+                for (const [bundlePath, sourcePath] of managedBundleAssets) {
+                    localBundleAssets.set(joinUrlPath(serverBase, bundlePath), sourcePath);
+                }
                 config.plugins = config.plugins || [];
                 if (managedBundleAssets.size > 0) {
                     config.plugins.push(new EmitManagedBundleAssetsPlugin(managedBundleAssets));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynx-js/external-bundle-rsbuild-plugin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "An rsbuild plugin for loading lynx external bundles.",
   "keywords": [
     "rsbuild",
@@ -34,12 +34,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@lynx-js/externals-loading-webpack-plugin": "0.2.0"
+    "@lynx-js/externals-loading-webpack-plugin": "0.2.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "7.58.2",
-    "@rsbuild/core": "2.0.11",
-    "@lynx-js/react-umd": "0.121.2"
+    "@rsbuild/core": "2.1.4",
+    "@lynx-js/react-umd": "0.123.0"
   },
   "engines": {
     "node": ">=18"