diff --git a/docs/en/api/_meta.json b/docs/en/api/_meta.json index c47646114..3b5ec46e0 100644 --- a/docs/en/api/_meta.json +++ b/docs/en/api/_meta.json @@ -1148,6 +1148,36 @@ "collapsible": true, "collapsed": true, "items": [ + { + "type": "custom-link", + "label": "builtInExternalsPresetDefinitions", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions" + }, + { + "type": "custom-link", + "label": "ExternalsPresetContext", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinition", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinitions", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions" + }, + { + "type": "custom-link", + "label": "ExternalsPresets", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets" + }, + { + "type": "custom-link", + "label": "normalizeBundlePath", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath" + }, { "type": "custom-link", "label": "pluginExternalBundle", @@ -1157,6 +1187,21 @@ "type": "custom-link", "label": "PluginExternalBundleOptions", "link": "/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions" + }, + { + "type": "custom-link", + "label": "PluginExternalConfig", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig" + }, + { + "type": "custom-link", + "label": "PluginExternalValue", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue" + }, + { + "type": "custom-link", + "label": "ReactLynxExternalsPresetOptions", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions" } ] }, @@ -1167,6 +1212,11 @@ "collapsible": true, "collapsed": true, "items": [ + { + "type": "custom-link", + "label": "builtInExternalsPresetDefinitions", + "link": "/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions" + }, { "type": "custom-link", "label": "defaultExternalBundleLibConfig", @@ -1179,98 +1229,63 @@ }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.encodeoptions", "label": "EncodeOptions", - "items": [ - { - "type": "custom-link", - "label": "targetSdkVersion", - "link": "/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.encodeoptions" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin", "label": "ExternalBundleWebpackPlugin", - "items": [ - { - "type": "custom-link", - "label": "(constructor)", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_" - }, - { - "type": "custom-link", - "label": "apply", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.apply" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin" + }, + { + "type": "custom-link", + "label": "ExternalBundleLibConfig", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions", "label": "ExternalBundleWebpackPluginOptions", - "items": [ - { - "type": "custom-link", - "label": "bundleFileName", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename" - }, - { - "type": "custom-link", - "label": "encode", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode" - }, - { - "type": "custom-link", - "label": "targetSdkVersion", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions" }, { "type": "custom-link", - "label": "LAYERS", - "link": "/api/rspeedy/lynx-bundle-rslib-config.layers" + "label": "Externals", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externals" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinition", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinitions", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions" + }, + { + "type": "custom-link", + "label": "ExternalsPresets", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalspresets" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin", "label": "MainThreadRuntimeWrapperWebpackPlugin", - "items": [ - { - "type": "custom-link", - "label": "(constructor)", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_" - }, - { - "type": "custom-link", - "label": "apply", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions", "label": "MainThreadRuntimeWrapperWebpackPluginOptions", - "items": [ - { - "type": "custom-link", - "label": "test", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions" + }, + { + "type": "custom-link", + "label": "OutputConfig", + "link": "/api/rspeedy/lynx-bundle-rslib-config.outputconfig" + }, + { + "type": "custom-link", + "label": "reactLynxExternalsPreset", + "link": "/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset" } ] }, diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md new file mode 100644 index 000000000..383bbbed6 --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [builtInExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md) + +## builtInExternalsPresetDefinitions variable + +Built-in externals preset definitions. + +**Signature:** + +```typescript +export declare const builtInExternalsPresetDefinitions: ExternalsPresetDefinitions; +``` diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md new file mode 100644 index 000000000..a3f52eebd --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresetContext](./external-bundle-rsbuild-plugin.externalspresetcontext.md) + +## ExternalsPresetContext interface + +Context passed to externals preset resolvers. + +**Signature:** + +```typescript +export interface ExternalsPresetContext +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `rootPath` | `string` | The current Rsbuild project root path. | diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md new file mode 100644 index 000000000..4e4059fb1 --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinition](./external-bundle-rsbuild-plugin.externalspresetdefinition.md) + +## ExternalsPresetDefinition interface + +Definition for a named externals preset. + +**Signature:** + +```typescript +export interface ExternalsPresetDefinition +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `extends?` | `string \| string[]` | Other preset names to apply before the current preset. | +| `resolveExternals?` | `(value: boolean \| object, context: ExternalsPresetContext) => ExternalsLoadingPluginOptions['externals']` | Resolve external request mappings contributed by this preset. | +| `resolveManagedAssets?` | `(value: boolean \| object, context: ExternalsPresetContext) => Map \| Record` | Resolve managed bundle assets contributed by this preset. | diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md new file mode 100644 index 000000000..b35e4f37e --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.externalspresetdefinitions.md) + +## ExternalsPresetDefinitions type alias + +Available externals preset definitions. + +**Signature:** + +```typescript +export type ExternalsPresetDefinitions = Record; +``` diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md new file mode 100644 index 000000000..bdf74a319 --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresets](./external-bundle-rsbuild-plugin.externalspresets.md) + +## ExternalsPresets interface + +Presets for external bundle dependencies. + +**Signature:** + +```typescript +export interface ExternalsPresets +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `reactlynx?` | `boolean \| ReactLynxExternalsPresetOptions` | Load the ReactLynx runtime bundle and wire its standard module globals. | +| `[presetName: string]` | `boolean \| object \| undefined` | Additional custom preset flags. | diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.md index db680c80a..e313b11f3 100644 --- a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.md +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.md @@ -10,11 +10,29 @@ A rsbuild plugin for loading external bundles using externals-loading-webpack-pl | Function | Description | | --- | --- | -| [pluginExternalBundle(options)](./external-bundle-rsbuild-plugin.pluginexternalbundle.md) |

Create a rsbuild plugin for loading external bundles.

This plugin wraps the externals-loading-webpack-plugin and automatically retrieves layer names from the react-rsbuild-plugin via api.useExposed.

| +| [normalizeBundlePath(bundlePath)](./external-bundle-rsbuild-plugin.normalizebundlepath.md) | Normalize a public bundle path by removing leading slashes. | +| [pluginExternalBundle(options)](./external-bundle-rsbuild-plugin.pluginexternalbundle.md) | Create a rsbuild plugin for loading external bundles. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [ExternalsPresetContext](./external-bundle-rsbuild-plugin.externalspresetcontext.md) | Context passed to externals preset resolvers. | +| [ExternalsPresetDefinition](./external-bundle-rsbuild-plugin.externalspresetdefinition.md) | Definition for a named externals preset. | +| [ExternalsPresets](./external-bundle-rsbuild-plugin.externalspresets.md) | Presets for external bundle dependencies. | +| [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | Options for the external-bundle-rsbuild-plugin. | +| [PluginExternalValue](./external-bundle-rsbuild-plugin.pluginexternalvalue.md) | External bundle reference accepted by `pluginExternalBundle`. | +| [ReactLynxExternalsPresetOptions](./external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) | Options for the built-in `reactlynx` externals preset. | ## Type Aliases | Type Alias | Description | | --- | --- | -| [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | Options for the external-bundle-rsbuild-plugin. | +| [ExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.externalspresetdefinitions.md) | Available externals preset definitions. | +| [PluginExternalConfig](./external-bundle-rsbuild-plugin.pluginexternalconfig.md) | External bundle shorthand accepted by `pluginExternalBundle`. | + +## Variables +| Variable | Description | +| --- | --- | +| [builtInExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md) | Built-in externals preset definitions. | diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md new file mode 100644 index 000000000..b247532ee --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [normalizeBundlePath](./external-bundle-rsbuild-plugin.normalizebundlepath.md) + +## normalizeBundlePath() function + +Normalize a public bundle path by removing leading slashes. + +**Signature:** + +```typescript +export declare function normalizeBundlePath(bundlePath: string): string; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| bundlePath | `string` | The bundle path to normalize. | + +**Returns:** + +`string` diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md index de597591d..80562840e 100644 --- a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md @@ -6,8 +6,6 @@ Create a rsbuild plugin for loading external bundles. -This plugin wraps the externals-loading-webpack-plugin and automatically retrieves layer names from the react-rsbuild-plugin via api.useExposed. - **Signature:** ```typescript @@ -18,17 +16,15 @@ export declare function pluginExternalBundle(options: PluginExternalBundleOption | Parameter | Type | Description | | --- | --- | --- | -| options | [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | | +| options | [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | Plugin options. | **Returns:** -RsbuildPlugin +`RsbuildPlugin` ## Example - ```ts -// lynx.config.ts import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin' import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin' @@ -36,15 +32,14 @@ export default { plugins: [ pluginReactLynx(), pluginExternalBundle({ + externalsPresets: { + reactlynx: true, + }, externals: { - lodash: { - url: 'http://lodash.lynx.bundle', - background: { sectionPath: 'background' }, - mainThread: { sectionPath: 'mainThread' }, - }, + './App.js': 'comp-lib.lynx.bundle', }, + globalObject: 'globalThis', }), ], } ``` - diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md index 5bca24b3b..850628ed4 100644 --- a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md @@ -2,14 +2,23 @@ [Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) -## PluginExternalBundleOptions type +## PluginExternalBundleOptions interface Options for the external-bundle-rsbuild-plugin. **Signature:** ```typescript -export type PluginExternalBundleOptions = Pick; +export interface PluginExternalBundleOptions extends Pick ``` -**References:** [ExternalsLoadingPluginOptions](./externals-loading-webpack-plugin.externalsloadingpluginoptions.md) +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `externalBundleRoot?` | `string` | Root directory that stores project-owned external bundles referenced by `bundlePath`. | +| `externals?` | `Record` | Additional explicit externals to load. | +| `externalsPresetDefinitions?` | `ExternalsPresetDefinitions` | Definitions for custom externals presets enabled by `externalsPresets`. | +| `externalsPresets?` | [`ExternalsPresets`](./external-bundle-rsbuild-plugin.externalspresets.md) | Presets for external libraries. | +| `globalObject?` | `ExternalsLoadingPluginOptions['globalObject']` | Global object used to mount external libraries. | +| `timeout?` | `number` | Default timeout for loading external bundles. | diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md new file mode 100644 index 000000000..f2344a364 --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [PluginExternalConfig](./external-bundle-rsbuild-plugin.pluginexternalconfig.md) + +## PluginExternalConfig type alias + +External bundle shorthand accepted by `pluginExternalBundle`. + +When a string is provided, it is treated as `bundlePath` and the plugin infers: + +- `libraryName`: the external request key +- `background.sectionPath`: the external request key +- `mainThread.sectionPath`: `${request}__main-thread` + +**Signature:** + +```typescript +export type PluginExternalConfig = PluginExternalValue | string; +``` diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md new file mode 100644 index 000000000..53543ae74 --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [PluginExternalValue](./external-bundle-rsbuild-plugin.pluginexternalvalue.md) + +## PluginExternalValue interface + +External bundle reference accepted by `pluginExternalBundle`. + +**Signature:** + +```typescript +export interface PluginExternalValue extends Omit +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `bundlePath?` | `string` | Bundle path resolved against the runtime public path. | +| `url?` | `string` | Deprecated. Prefer `bundlePath` unless the bundle is hosted outside the current build output. | diff --git a/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md new file mode 100644 index 000000000..e608e0543 --- /dev/null +++ b/docs/en/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ReactLynxExternalsPresetOptions](./external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) + +## ReactLynxExternalsPresetOptions interface + +Options for the built-in `reactlynx` externals preset. + +**Signature:** + +```typescript +export interface ReactLynxExternalsPresetOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `bundlePath?` | `string` | Emit the ReactLynx runtime bundle into the current build output and load it through the runtime public path. | +| `reactUmdPackageName?` | `string` | Package name that provides the ReactLynx runtime bundle. | +| `url?` | `string` | Deprecated. Override the runtime bundle URL directly. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md new file mode 100644 index 000000000..47c485a96 --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [builtInExternalsPresetDefinitions](./lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md) + +## builtInExternalsPresetDefinitions variable + +Built-in externals preset definitions. + +**Signature:** + +```typescript +export declare const builtInExternalsPresetDefinitions: ExternalsPresetDefinitions; +``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md index 53691e835..3b1bbfed7 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md @@ -9,5 +9,5 @@ The default lib config for external bundle. **Signature:** ```typescript -defaultExternalBundleLibConfig: LibConfig +export declare const defaultExternalBundleLibConfig: LibConfig; ``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md index 0a60ff832..925c63492 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md @@ -4,7 +4,7 @@ ## defineExternalBundleRslibConfig() function -Get the rslib config for building Lynx external bundles. +Get the Rslib config for building Lynx external bundles. **Signature:** @@ -16,73 +16,32 @@ export declare function defineExternalBundleRslibConfig(userLibConfig: ExternalB | Parameter | Type | Description | | --- | --- | --- | -| userLibConfig | ExternalBundleLibConfig | | -| encodeOptions | [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | _(Optional)_ | +| userLibConfig | [ExternalBundleLibConfig](./lynx-bundle-rslib-config.externalbundlelibconfig.md) | User-provided Rslib config. | +| encodeOptions | [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | Optional encode options. | **Returns:** -RslibConfig +`RslibConfig` -## Example 1 +## Example -If you want to build an external bundle which use in Lynx background thread, you can use the following code: - -```js -// rslib.config.js -import { defineExternalBundleRslibConfig, LAYERS } from '@lynx-js/lynx-bundle-rslib-config' - -export default defineExternalBundleRslibConfig({ - id: 'utils-lib', - source: { - entry: { - utils: { - import: './src/utils.ts', - layer: LAYERS.BACKGROUND, - } - } - } -}) -``` -Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in background thread. - -## Example 2 - -If you want to build an external bundle which use in Lynx main thread, you can use the following code: - -```js -// rslib.config.js -import { defineExternalBundleRslibConfig, LAYERS } from '@lynx-js/lynx-bundle-rslib-config' - -export default defineExternalBundleRslibConfig({ - id: 'utils-lib', - source: { - entry: { - utils: { - import: './src/utils.ts', - layer: LAYERS.MAIN_THREAD, - } - } - } -}) -``` -Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in main-thread. - -## Example 3 - -If you want to build an external bundle which use both in Lynx main thread and background thread. You don't need to set the layer. - -```js -// rslib.config.js +```ts import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config' +import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin' export default defineExternalBundleRslibConfig({ - id: 'utils-lib', + id: 'comp-lib', source: { entry: { - utils: './src/utils.ts', + './App.js': './external-bundle/CompLib.tsx', }, - } + }, + plugins: [pluginReactLynx()], + output: { + externalsPresets: { + reactlynx: true, + }, + globalObject: 'globalThis', + }, }) ``` -Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in background thread and `lynx.loadScript('utils__main-thread', { bundleName: 'utils-lib-bundle-url' })` in main-thread. - diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md index 5fb6d2cd7..e0fc59bdb 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md @@ -4,17 +4,16 @@ ## EncodeOptions interface -The options for encoding the external bundle. +Options for encoding the external bundle. **Signature:** ```typescript -export interface EncodeOptions +export interface EncodeOptions ``` ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [targetSdkVersion?](./lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md) | | string | _(Optional)_ The target SDK version of the external bundle. | - +| Property | Type | Description | +| --- | --- | --- | +| `engineVersion?` | `string` | The engine version of the external bundle. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md deleted file mode 100644 index 608322009..000000000 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) > [targetSdkVersion](./lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md) - -## EncodeOptions.targetSdkVersion property - -The target SDK version of the external bundle. - -**Signature:** - -```typescript -targetSdkVersion?: string; -``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md new file mode 100644 index 000000000..0ce8553a7 --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalBundleLibConfig](./lynx-bundle-rslib-config.externalbundlelibconfig.md) + +## ExternalBundleLibConfig interface + +Rslib config shape accepted by `defineExternalBundleRslibConfig`. + +**Signature:** + +```typescript +export interface ExternalBundleLibConfig extends LibConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `output?` | [`OutputConfig`](./lynx-bundle-rslib-config.outputconfig.md) | Output config accepted by Lynx external bundle builds. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md index cc3495de6..db5e1181c 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md @@ -4,23 +4,22 @@ ## ExternalBundleWebpackPlugin class -The webpack plugin to build and emit the external bundle. +Webpack plugin that builds and emits an external bundle. **Signature:** ```typescript -export declare class ExternalBundleWebpackPlugin +export declare class ExternalBundleWebpackPlugin ``` ## Constructors -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(options)](./lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_.md) | | Constructs a new instance of the ExternalBundleWebpackPlugin class | +| Constructor | Description | +| --- | --- | +| `new ExternalBundleWebpackPlugin(options)` | Constructs a new instance of `ExternalBundleWebpackPlugin`. | ## Methods -| Method | Modifiers | Description | +| Method | Return Type | Description | | --- | --- | --- | -| [apply(compiler)](./lynx-bundle-rslib-config.externalbundlewebpackplugin.apply.md) | | | - +| `apply(compiler)` | `void` | Apply the plugin to the compiler. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md index a92179683..1e12160bf 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md @@ -4,19 +4,18 @@ ## ExternalBundleWebpackPluginOptions interface -The options for [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md). +Options for `ExternalBundleWebpackPlugin`. **Signature:** ```typescript -export interface ExternalBundleWebpackPluginOptions +export interface ExternalBundleWebpackPluginOptions ``` ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [bundleFileName](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename.md) | | string | The external bundle filename. | -| [encode](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode.md) | | (opts: unknown) => Promise<{ buffer: Buffer; }> | The encode method which is exported from lynx-tasm package. | -| [targetSdkVersion?](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md) | | string \| undefined | _(Optional)_ The target SDK version of the external bundle. | - +| Property | Type | Description | +| --- | --- | --- | +| `bundleFileName` | `string` | The external bundle filename. | +| `encode` | `(opts: unknown) => Promise<{ buffer: Buffer; }>` | Encode method exported from the Lynx encoder package. | +| `engineVersion?` | `string` | The target engine version of the external bundle. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md deleted file mode 100644 index 93e2decc8..000000000 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) > [targetSdkVersion](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md) - -## ExternalBundleWebpackPluginOptions.targetSdkVersion property - -The target SDK version of the external bundle. - -**Signature:** - -```typescript -targetSdkVersion?: string | undefined; -``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externals.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externals.md new file mode 100644 index 000000000..6725c2dc3 --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externals.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [Externals](./lynx-bundle-rslib-config.externals.md) + +## Externals type alias + +External module to global-name mappings used when building Lynx external bundles. + +**Signature:** + +```typescript +export type Externals = Record; +``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md new file mode 100644 index 000000000..16849726c --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalsPresetDefinition](./lynx-bundle-rslib-config.externalspresetdefinition.md) + +## ExternalsPresetDefinition interface + +Definition for a named externals preset. + +**Signature:** + +```typescript +export interface ExternalsPresetDefinition +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `extends?` | `string \| string[]` | Other preset names to include before applying the current preset. | +| `externals?` | [`Externals`](./lynx-bundle-rslib-config.externals.md) | Externals contributed by this preset. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md new file mode 100644 index 000000000..d4e6876de --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalsPresetDefinitions](./lynx-bundle-rslib-config.externalspresetdefinitions.md) + +## ExternalsPresetDefinitions type alias + +Available externals preset definitions. + +**Signature:** + +```typescript +export type ExternalsPresetDefinitions = Record; +``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md new file mode 100644 index 000000000..3a5ed3787 --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalsPresets](./lynx-bundle-rslib-config.externalspresets.md) + +## ExternalsPresets type alias + +Enabled externals presets. + +**Signature:** + +```typescript +export type ExternalsPresets = { + reactlynx?: boolean; +} & Record; +``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.layers.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.layers.md deleted file mode 100644 index 2437d8804..000000000 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.layers.md +++ /dev/null @@ -1,16 +0,0 @@ - - -[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [LAYERS](./lynx-bundle-rslib-config.layers.md) - -## LAYERS variable - -The Layer name of background and main-thread. - -**Signature:** - -```typescript -LAYERS: { - readonly BACKGROUND: "background"; - readonly MAIN_THREAD: "main-thread"; -} -``` diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md index 25753026c..5ec8ed50c 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md @@ -4,23 +4,22 @@ ## MainThreadRuntimeWrapperWebpackPlugin class -The main-thread runtime wrapper for external bundle. +Webpack plugin that wraps main-thread runtime modules for external bundles. **Signature:** ```typescript -export declare class MainThreadRuntimeWrapperWebpackPlugin +export declare class MainThreadRuntimeWrapperWebpackPlugin ``` ## Constructors -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(options)](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_.md) | | Constructs a new instance of the MainThreadRuntimeWrapperWebpackPlugin class | +| Constructor | Description | +| --- | --- | +| `new MainThreadRuntimeWrapperWebpackPlugin(options?)` | Constructs a new instance of `MainThreadRuntimeWrapperWebpackPlugin`. | ## Methods -| Method | Modifiers | Description | +| Method | Return Type | Description | | --- | --- | --- | -| [apply(compiler)](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply.md) | | | - +| `apply(compiler)` | `void` | Apply the plugin to the compiler. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md index ad374d0f4..e0767cf82 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md @@ -4,17 +4,16 @@ ## MainThreadRuntimeWrapperWebpackPluginOptions interface -The options of [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md). +Options for `MainThreadRuntimeWrapperWebpackPlugin`. **Signature:** ```typescript -export interface MainThreadRuntimeWrapperWebpackPluginOptions +export interface MainThreadRuntimeWrapperWebpackPluginOptions ``` ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [test](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test.md) | | BannerPlugin\['options'\]\['test'\] | Include all modules that pass test assertion. | - +| Property | Type | Description | +| --- | --- | --- | +| `test` | `BannerPlugin['options']['test']` | Include all modules that pass the test assertion. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.md index faea3d794..1705c30ec 100644 --- a/docs/en/api/rspeedy/lynx-bundle-rslib-config.md +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.md @@ -4,33 +4,44 @@ ## lynx-bundle-rslib-config package -`@lynx-js/lynx-bundle-rslib-config` is the package that provides the configurations for bundling Lynx bundle with [Rslib](https://rslib.rs/). +`@lynx-js/lynx-bundle-rslib-config` is the package that provides the configurations for bundling Lynx bundle with [Rslib](https://rslib.rs/). ## Classes | Class | Description | | --- | --- | -| [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md) | The webpack plugin to build and emit the external bundle. | -| [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md) | The main-thread runtime wrapper for external bundle. | +| [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md) | Webpack plugin that builds and emits an external bundle. | +| [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md) | Webpack plugin that wraps main-thread runtime modules for external bundles. | ## Functions | Function | Description | | --- | --- | -| [defineExternalBundleRslibConfig(userLibConfig, encodeOptions)](./lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md) | Get the rslib config for building Lynx external bundles. | +| [defineExternalBundleRslibConfig(userLibConfig, encodeOptions)](./lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md) | Get the Rslib config for building Lynx external bundles. | ## Interfaces | Interface | Description | | --- | --- | -| [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | The options for encoding the external bundle. | -| [ExternalBundleWebpackPluginOptions](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) | The options for [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md). | -| [MainThreadRuntimeWrapperWebpackPluginOptions](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md) | The options of [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md). | +| [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | Options for encoding the external bundle. | +| [ExternalBundleLibConfig](./lynx-bundle-rslib-config.externalbundlelibconfig.md) | Rslib config shape accepted by `defineExternalBundleRslibConfig`. | +| [ExternalBundleWebpackPluginOptions](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) | Options for `ExternalBundleWebpackPlugin`. | +| [ExternalsPresetDefinition](./lynx-bundle-rslib-config.externalspresetdefinition.md) | Definition for a named externals preset. | +| [MainThreadRuntimeWrapperWebpackPluginOptions](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md) | Options for `MainThreadRuntimeWrapperWebpackPlugin`. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [Externals](./lynx-bundle-rslib-config.externals.md) | External module to global-name mappings used when building Lynx external bundles. | +| [ExternalsPresetDefinitions](./lynx-bundle-rslib-config.externalspresetdefinitions.md) | Available externals preset definitions. | +| [ExternalsPresets](./lynx-bundle-rslib-config.externalspresets.md) | Enabled externals presets. | +| [OutputConfig](./lynx-bundle-rslib-config.outputconfig.md) | Output config accepted by Lynx external bundle builds. | ## Variables | Variable | Description | | --- | --- | +| [builtInExternalsPresetDefinitions](./lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md) | Built-in externals preset definitions. | | [defaultExternalBundleLibConfig](./lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md) | The default lib config for external bundle. | -| [LAYERS](./lynx-bundle-rslib-config.layers.md) | The Layer name of background and main-thread. | - +| [reactLynxExternalsPreset](./lynx-bundle-rslib-config.reactlynxexternalspreset.md) | Standard ReactLynx external mappings used by the built-in `reactlynx` preset. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md new file mode 100644 index 000000000..35b74a59b --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [OutputConfig](./lynx-bundle-rslib-config.outputconfig.md) + +## OutputConfig type alias + +Output config accepted by Lynx external bundle builds. + +**Signature:** + +```typescript +export type OutputConfig = Required['output'] & { + externalsPresets?: ExternalsPresets; + externalsPresetDefinitions?: ExternalsPresetDefinitions; + externals?: Externals; + globalObject?: 'lynx' | 'globalThis'; +}; +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `externals?` | [`Externals`](./lynx-bundle-rslib-config.externals.md) | Explicit external module mappings. | +| `externalsPresetDefinitions?` | [`ExternalsPresetDefinitions`](./lynx-bundle-rslib-config.externalspresetdefinitions.md) | Definitions for custom presets enabled by `externalsPresets`. | +| `externalsPresets?` | [`ExternalsPresets`](./lynx-bundle-rslib-config.externalspresets.md) | Presets for external libraries. | +| `globalObject?` | `'lynx' \| 'globalThis'` | Global object used to mount the built library. | diff --git a/docs/en/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md b/docs/en/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md new file mode 100644 index 000000000..04f5099eb --- /dev/null +++ b/docs/en/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [reactLynxExternalsPreset](./lynx-bundle-rslib-config.reactlynxexternalspreset.md) + +## reactLynxExternalsPreset variable + +Standard ReactLynx external mappings used by the built-in `reactlynx` preset. + +**Signature:** + +```typescript +export declare const reactLynxExternalsPreset: Externals; +``` diff --git a/docs/en/rspeedy/external-bundle.mdx b/docs/en/rspeedy/external-bundle.mdx index 59056be26..3a9695816 100644 --- a/docs/en/rspeedy/external-bundle.mdx +++ b/docs/en/rspeedy/external-bundle.mdx @@ -1,400 +1,256 @@ import { PackageManagerTabs } from '@theme'; -import { VersionBadge } from '@lynx'; +import { Go, VersionBadge } from '@lynx'; # External Bundle -External Bundle packages code into standalone modules that can be dynamically loaded across different Lynx applications to reduce bundle size. The usage process involves two steps: - -1. **[`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config)** - Used to build External Bundle -2. **[`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin)** - Used to load External Bundle in applications - :::info +Loading CSS files from an External Bundle requires Lynx 3.7 or later. +::: -Differences from [Chunk Splitting](/api/rspeedy/rspeedy.performance.chunksplit): - -1. **Thread Support**: Chunk Splitting only supports background thread code splitting, while External Bundle supports both background thread and main thread -2. **Cross-Application Sharing**: External Bundle can be shared across multiple Lynx applications to reduce duplicate code, while Chunk Splitting artifacts are only used within the current application -3. **Packaging Method**: Chunk Splitting is automatically split during build and deployed together with the application; External Bundle requires separate building, which can be deployed with the application artifacts or uploaded to CDN or server for dynamic loading at runtime -4. **Use Cases**: External Bundle is suitable for common libraries shared across applications (e.g., `lodash-es`, `moment`); Chunk Splitting is suitable for code splitting optimization within a single application +External Bundle lets you build a Lynx bundle once and load it from multiple Lynx apps at runtime. Use it when you want to share ReactLynx components or common business bundles across apps. -::: +Compared with [Chunk Splitting](/api/rspeedy/rspeedy.performance.chunksplit), External Bundle is for cross-application reuse, while Chunk Splitting is for splitting code inside one app. -## 1. Building External Bundle +This workflow has two parts: -### Installation +1. Use [`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config) to build the external bundle. +2. Use [`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin) to load it in the host app. - +## Install -### Basic Usage + -Use [`defineExternalBundleRslibConfig()`](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig) in `rslib.config.ts` to define the build configuration for External Bundle. +## Build An External Bundle -#### Example 1: Support Both Background Thread and Main Thread +For a ReactLynx component bundle, the recommended setup is: -```js title="rslib.config.ts" +```ts title="rslib-comp-lib.config.ts" import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; - -const require = createRequire(import.meta.url); +import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; export default defineExternalBundleRslibConfig({ - id: 'lodash-es', + id: 'comp-lib', source: { entry: { - 'lodash-es': require.resolve('lodash-es'), + './App.js': './external-bundle/CompLib.tsx', + }, + }, + plugins: [pluginReactLynx()], + output: { + externalsPresets: { + reactlynx: true, }, }, }); ``` -Run the following command to build: +`externalsPresets.reactlynx` maps the standard ReactLynx requests for you, so a ReactLynx component bundle can depend on the shared runtime directly. - +Run the build with: -The output file is `dist/lodash-es.lynx.bundle`, with the file name prefix determined by the `id` configuration. You can upload `.lynx.bundle` files to a CDN or server. - -:::tip -Since Lynx background thread and main thread have different artifact formats, the current version builds artifacts separately for both threads. The `dist/lodash-es.lynx.bundle` artifact content looks like: - -```js -{ - 'lodash-es': `// background code`, // Background thread artifact - 'lodash-es__main-thread': `// main-thread code`, // `__main-thread` is an automatically generated suffix, representing the main thread artifact -} -``` - -Future versions will support unified code artifacts to further reduce bundle size. -::: - -:::info Section Path Naming Rules - -The `'lodash-es'` and `'lodash-es__main-thread'` in the artifacts above are called **section path**, which are identifiers for internal modules in `.lynx.bundle`. These section paths need to be configured through [`background.sectionPath`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle#backgroundsectionpath) and [`mainThread.sectionPath`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle#mainthreadsectionpath) when loading external bundle. We will introduce this in the following sections. -::: + -#### Example 2: Background Thread Only +## Load It In The Host App -```js title="rslib.config.ts" {12} -import { - defineExternalBundleRslibConfig, - LAYERS, -} from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; +Use the same request key in the app: -const require = createRequire(import.meta.url); +```ts title="lynx.config.ts" +import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'; +import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'; +import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; +import { defineConfig } from '@lynx-js/rspeedy'; -export default defineExternalBundleRslibConfig({ - id: 'lodash-es', - source: { - entry: { - 'lodash-es': { - import: require.resolve('lodash-es'), - layer: LAYERS.BACKGROUND, +export default defineConfig({ + plugins: [ + pluginReactLynx(), + pluginQRCode(), + pluginExternalBundle({ + externalsPresets: { + reactlynx: true, }, - }, - }, + externals: { + './App.js': 'comp-lib.lynx.bundle', + }, + }), + ], }); ``` -The `dist/lodash-es.lynx.bundle` artifact content looks like: +This shorthand is equivalent to the following expanded config: -```js -{ - 'lodash-es': `// lodash-es`, +```ts +externals: { + './App.js': { + bundlePath: 'comp-lib.lynx.bundle', + libraryName: './App.js', + background: { sectionPath: './App.js' }, + mainThread: { sectionPath: './App.js__main-thread' }, + async: true, + }, } ``` -#### Example 3: Main Thread Only +If your section names already match the request key, this is the smallest recommended setup. -```js title="rslib.config.ts" {9} -import { - defineExternalBundleRslibConfig, - LAYERS, -} from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; +## When To Set `globalObject` -const require = createRequire(import.meta.url); +In most projects, you can omit `globalObject`. -export default defineExternalBundleRslibConfig({ - id: 'lodash-es', - source: { - entry: { - 'lodash-es': { - import: require.resolve('lodash-es'), - layer: LAYERS.MAIN_THREAD, - }, - }, - }, -}); -``` +Set `globalObject: 'globalThis'` only when your app enables a shared `globalThis` across background-thread runtimes and you want later bundles to reuse externals that have already been loaded there. -The `dist/lodash-es.lynx.bundle` artifact content looks like: +Use it on both sides when needed: -```js -{ - 'lodash-es': `// lodash-es main-thread code`, +```ts title="rslib-comp-lib.config.ts" +output: { + externalsPresets: { + reactlynx: true, + }, + globalObject: 'globalThis', } ``` -### Bundle Multiple Dependencies - -Supports packaging multiple dependencies into the same external bundle to reduce the number of runtime requests and improve performance. - -```js title="rslib.config.ts" {9} -import { - defineExternalBundleRslibConfig, - LAYERS, -} from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; - -const require = createRequire(import.meta.url); - -export default defineExternalBundleRslibConfig({ - id: 'lodash', - source: { - entry: { - 'lodash.get': require.resolve('lodash.get'), - 'lodash.isequal': require.resolve('lodash.isequal'), - }, +```ts title="lynx.config.ts" +pluginExternalBundle({ + externalsPresets: { + reactlynx: true, + }, + externals: { + './App.js': 'comp-lib.lynx.bundle', }, + globalObject: 'globalThis', }); ``` -The `dist/lodash.lynx.bundle` artifact content looks like: +## Why `@lynx-js/react-umd` Is Needed -```js -{ - 'lodash.get': '// lodash.get background code', - 'lodash.get__main-thread': '// lodash.get main-thread code', - 'lodash.isequal': '// lodash.isequal background code', - 'lodash.isequal__main-thread': '// lodash.isequal main-thread code', -} -``` +`@lynx-js/react-umd` ships the prebuilt ReactLynx runtime bundles used by the built-in `reactlynx` preset. -### Referencing Other External Bundles +When you enable `externalsPresets.reactlynx` in [`pluginExternalBundle()`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle), the plugin will automatically resolve `@lynx-js/react-umd/dev` or `@lynx-js/react-umd/prod` based on `NODE_ENV`, emit `react.lynx.bundle`, and load it through the current runtime public path. -When an external bundle depends on other external bundles, you can declare these dependencies as external dependencies via [`output.externals`](https://rslib.rs/config/rsbuild/output#outputexternals) to avoid duplicate packaging: +For most projects, this means: -```js title="rslib.config.ts" -import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'; +- install `@lynx-js/react-umd` +- enable `reactlynx` +- let the preset provide the ReactLynx runtime mapping -export default defineExternalBundleRslibConfig({ - id: 'my-components', - output: { - externals: { - // Read @lynx-js/react from ReactLynx.React - '@lynx-js/react': ['ReactLynx', 'React'], - }, - }, -}); -``` +## Extend Presets -:::warning -Before loading `my-components` at runtime, you must ensure that the `@lynx-js/react` external bundle has been loaded, otherwise it will cause runtime errors. -::: +Use the same preset name on both sides so the bundle build and the host app stay aligned. -### Custom Configuration +### From The Library Side -`defineExternalBundleRslibConfig()` automatically applies [default configuration](https://github.com/lynx-family/lynx-stack/blob/71b9083d7c117666ae815e62ced38709c3d207e6/packages/rspeedy/lynx-bundle-rslib-config/src/externalBundleRslibConfig.ts#L42). To modify the default configuration, simply override it in the configuration object: +On the external bundle build side, presets live in `output.externalsPresets` and `output.externalsPresetDefinitions`: -```js title="rslib.config.ts" {4-13} +```ts title="rslib-comp-lib.config.ts" import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'; export default defineExternalBundleRslibConfig({ - id: 'my-lib', - source: { - entry: { - index: './src/index.ts', + output: { + externalsPresets: { + reactlynxPlus: true, }, - define: { - __PROFILE__: false, - __MAIN_THREAD__: "__webpack_layer__ === 'main-thread'", - __BACKGROUND__: "__webpack_layer__ === 'background'", + externalsPresetDefinitions: { + reactlynxPlus: { + extends: 'reactlynx', + externals: { + '@lynx-js/lynx-ui': ['LynxUI', 'UI'], + }, + }, }, }, - autoExternal: { - dependencies: true, // Set dependencies as external - }, }); ``` -### Viewing Bundle Intermediate Artifacts - -`.lynx.bundle` is a compiled artifact and cannot be read directly. If you need to view the pre-compiled code, add the `DEBUG=rspeedy` environment variable: - -```bash -DEBUG=rspeedy npm exec rslib build -``` - -This will output the following intermediate artifacts: - -```md -./dist -├── lodash-es.js -├── lodash-es.lynx.bundle -├── lodash-es\_\_main-thread.js -└── tasm.json -``` - -## 2. Loading External Bundle +This side decides how imports are mapped to external globals when the bundle is built. -Based on [Webpack Externals](https://webpack.js.org/configuration/externals/) implementation. When importing an external bundle, dependencies are not bundled into the main bundle but dynamically loaded from `.lynx.bundle` files. +### From The Lynx Page Side -### Installation - - - -### Basic Usage - -If your code uses `lodash-es`: - -```js -import _ from 'lodash-es'; - -_.isEmpty([]); -``` - -Use the [`pluginExternalBundle`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle) plugin in `lynx.config.ts` to configure `lodash-es` in `externals`, avoiding packaging it into the main bundle: +On the host app side, presets live in `pluginExternalBundle({ externalsPresets, externalsPresetDefinitions })`: ```ts title="lynx.config.ts" import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'; -import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; -export default { - plugins: [ - pluginReactLynx(), // Must be placed before - pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash-es.lynx.bundle', - background: { sectionPath: 'lodash-es' }, - mainThread: { sectionPath: 'lodash-es__main-thread' }, - }, - }, - }), - ], -}; -``` - -After configuration, `lodash-es` in your code will not be bundled into the main bundle but dynamically loaded from the specified URL at runtime. - -### Configuring Multiple External Bundles - -You can configure multiple external bundles in `externals`: - -```ts title="lynx.config.ts" pluginExternalBundle({ - externals: { - '@lynx-js/react': { - libraryName: ['ReactLynx', 'React'], - url: 'http://example.com/react.lynx.bundle', - background: { sectionPath: 'ReactLynx' }, - mainThread: { sectionPath: 'ReactLynx__main-thread' }, - async: false, // Synchronous loading - }, - 'my-components': { - url: 'http://example.com/comp-lib.lynx.bundle', - background: { sectionPath: 'components' }, - mainThread: { sectionPath: 'components__main-thread' }, + externalsPresets: { + reactlynxPlus: true, + }, + externalsPresetDefinitions: { + reactlynxPlus: { + extends: 'reactlynx', + resolveExternals() { + return { + '@lynx-js/lynx-ui': { + libraryName: ['LynxUI', 'UI'], + bundlePath: 'lynx-ui.lynx.bundle', + background: { sectionPath: 'LynxUI' }, + mainThread: { sectionPath: 'LynxUI__main-thread' }, + async: false, + }, + }; + }, }, }, }); ``` -### Configuration Options +This side decides where the bundle is loaded from and which section names the runtime should request. -- **url**: External Bundle loading address (required) -- **libraryName**: Specify global variable name, `string` / `string[]` (optional) -- **background**: Background thread configuration, including `sectionPath` (optional) -- **mainThread**: Main thread configuration, including `sectionPath` (optional) -- **async**: Whether to load asynchronously, defaults to `true` (optional) +Explicit `externals` still override mappings provided by presets. Use that when a single app needs a different bundle path or section name. -#### `libraryName` +## When To Use The Object Form -Specifies which global variable to read the external bundle's module exports from. Usually no configuration is needed, as the plugin automatically infers based on the package's import name. +Use the full object form when you need custom section names, custom exported library names, timeouts, or a dedicated local bundle directory. -When external bundle is mounted to a nested object, use `string[]` to specify the access path: +The `external-bundle` example in `lynx-examples` uses that style: -```ts title="lynx.config.ts" +```ts title="lynx.config.mjs" pluginExternalBundle({ - externals: { - '@lynx-js/react': { - libraryName: ['ReactLynx', 'React'], // Read from global.ReactLynx.React - url: 'http://example.com/react.lynx.bundle', - }, + externalBundleRoot: 'dist-external-bundle', + externalsPresets: { + reactlynx: true, }, -}); -``` - -Most of the time, you can just rely on automatic inference: - -```ts title="lynx.config.ts" -pluginExternalBundle({ externals: { - lodash: { - // Don't configure libraryName, the plugin automatically infers to 'lodash' based on the import name - url: 'http://example.com/lodash.lynx.bundle', + 'lodash-es': { + bundlePath: 'lodash-es.lynx.bundle', + background: { sectionPath: 'lodash-es' }, + mainThread: { sectionPath: 'lodash-es__main-thread' }, + async: false, + timeout: 10000, + }, + './components': { + bundlePath: 'comp.lynx.bundle', + background: { sectionPath: 'component' }, + mainThread: { sectionPath: 'component__main-thread' }, + async: true, + timeout: 5000, }, }, + timeout: 10000, }); ``` -#### `sectionPath` - -`sectionPath` is the path identifier for internal modules within the external bundle: - -- **background**: Module path used by the background thread -- **mainThread**: Module path used by the main thread - -`sectionPath` must exactly match the actual output section name when building the external bundle, otherwise runtime errors will occur due to the missing corresponding module. - -Taking [Building External Bundle - Example 1](#example-1-support-both-background-thread-and-main-thread) as an example, the corresponding `sectionPath` configuration is as follows: +Use this form when: -```ts title="lynx.config.ts" {9,10} -import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'; - -export default { - plugins: [ - pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash.lynx.bundle', - background: { sectionPath: 'lodash-es' }, - mainThread: { sectionPath: 'lodash-es__main-thread' }, - }, - }, - }), - ], -}; -``` +- one bundle contains multiple business modules +- section names do not match the request key +- bundles are built into `dist-external-bundle` +- you want per-bundle timeout or loading behavior -If your external bundle only supports a specific thread (refer to [Building External Bundle - Example 2](#example-2-background-thread-only) and [Building External Bundle - Example 3](#example-3-main-thread-only)), you only need to configure the `sectionPath` for the corresponding thread: +## Example -```ts title="lynx.config.ts" -// Background thread only -pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash.lynx.bundle', - background: { sectionPath: 'lodash-es' }, - }, - }, -}); -``` +The `lynx-examples` external-bundle example is available directly in the docs: -```ts title="lynx.config.ts" -// Main thread only -pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash.lynx.bundle', - mainThread: { sectionPath: 'lodash-es' }, - }, - }, -}); -``` + -## Reference Examples +## API Reference -- [react-external-bundle-example](https://github.com/lynx-family/lynx-stack/tree/main/examples/react-externals) +- [`defineExternalBundleRslibConfig()`](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig) +- [`pluginExternalBundle()`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle) +- [`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config) +- [`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin) diff --git a/docs/zh/api/_meta.json b/docs/zh/api/_meta.json index c47646114..3b5ec46e0 100644 --- a/docs/zh/api/_meta.json +++ b/docs/zh/api/_meta.json @@ -1148,6 +1148,36 @@ "collapsible": true, "collapsed": true, "items": [ + { + "type": "custom-link", + "label": "builtInExternalsPresetDefinitions", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions" + }, + { + "type": "custom-link", + "label": "ExternalsPresetContext", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinition", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinitions", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions" + }, + { + "type": "custom-link", + "label": "ExternalsPresets", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets" + }, + { + "type": "custom-link", + "label": "normalizeBundlePath", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath" + }, { "type": "custom-link", "label": "pluginExternalBundle", @@ -1157,6 +1187,21 @@ "type": "custom-link", "label": "PluginExternalBundleOptions", "link": "/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions" + }, + { + "type": "custom-link", + "label": "PluginExternalConfig", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig" + }, + { + "type": "custom-link", + "label": "PluginExternalValue", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue" + }, + { + "type": "custom-link", + "label": "ReactLynxExternalsPresetOptions", + "link": "/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions" } ] }, @@ -1167,6 +1212,11 @@ "collapsible": true, "collapsed": true, "items": [ + { + "type": "custom-link", + "label": "builtInExternalsPresetDefinitions", + "link": "/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions" + }, { "type": "custom-link", "label": "defaultExternalBundleLibConfig", @@ -1179,98 +1229,63 @@ }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.encodeoptions", "label": "EncodeOptions", - "items": [ - { - "type": "custom-link", - "label": "targetSdkVersion", - "link": "/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.encodeoptions" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin", "label": "ExternalBundleWebpackPlugin", - "items": [ - { - "type": "custom-link", - "label": "(constructor)", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_" - }, - { - "type": "custom-link", - "label": "apply", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.apply" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin" + }, + { + "type": "custom-link", + "label": "ExternalBundleLibConfig", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions", "label": "ExternalBundleWebpackPluginOptions", - "items": [ - { - "type": "custom-link", - "label": "bundleFileName", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename" - }, - { - "type": "custom-link", - "label": "encode", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode" - }, - { - "type": "custom-link", - "label": "targetSdkVersion", - "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions" }, { "type": "custom-link", - "label": "LAYERS", - "link": "/api/rspeedy/lynx-bundle-rslib-config.layers" + "label": "Externals", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externals" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinition", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition" + }, + { + "type": "custom-link", + "label": "ExternalsPresetDefinitions", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions" + }, + { + "type": "custom-link", + "label": "ExternalsPresets", + "link": "/api/rspeedy/lynx-bundle-rslib-config.externalspresets" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin", "label": "MainThreadRuntimeWrapperWebpackPlugin", - "items": [ - { - "type": "custom-link", - "label": "(constructor)", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_" - }, - { - "type": "custom-link", - "label": "apply", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin" }, { "type": "custom-link", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions", "label": "MainThreadRuntimeWrapperWebpackPluginOptions", - "items": [ - { - "type": "custom-link", - "label": "test", - "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test" - } - ], - "collapsible": true, - "collapsed": true + "link": "/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions" + }, + { + "type": "custom-link", + "label": "OutputConfig", + "link": "/api/rspeedy/lynx-bundle-rslib-config.outputconfig" + }, + { + "type": "custom-link", + "label": "reactLynxExternalsPreset", + "link": "/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset" } ] }, diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md new file mode 100644 index 000000000..383bbbed6 --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [builtInExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md) + +## builtInExternalsPresetDefinitions variable + +Built-in externals preset definitions. + +**Signature:** + +```typescript +export declare const builtInExternalsPresetDefinitions: ExternalsPresetDefinitions; +``` diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md new file mode 100644 index 000000000..a3f52eebd --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresetContext](./external-bundle-rsbuild-plugin.externalspresetcontext.md) + +## ExternalsPresetContext interface + +Context passed to externals preset resolvers. + +**Signature:** + +```typescript +export interface ExternalsPresetContext +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `rootPath` | `string` | The current Rsbuild project root path. | diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md new file mode 100644 index 000000000..4e4059fb1 --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinition](./external-bundle-rsbuild-plugin.externalspresetdefinition.md) + +## ExternalsPresetDefinition interface + +Definition for a named externals preset. + +**Signature:** + +```typescript +export interface ExternalsPresetDefinition +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `extends?` | `string \| string[]` | Other preset names to apply before the current preset. | +| `resolveExternals?` | `(value: boolean \| object, context: ExternalsPresetContext) => ExternalsLoadingPluginOptions['externals']` | Resolve external request mappings contributed by this preset. | +| `resolveManagedAssets?` | `(value: boolean \| object, context: ExternalsPresetContext) => Map \| Record` | Resolve managed bundle assets contributed by this preset. | diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md new file mode 100644 index 000000000..b35e4f37e --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.externalspresetdefinitions.md) + +## ExternalsPresetDefinitions type alias + +Available externals preset definitions. + +**Signature:** + +```typescript +export type ExternalsPresetDefinitions = Record; +``` diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md new file mode 100644 index 000000000..bdf74a319 --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ExternalsPresets](./external-bundle-rsbuild-plugin.externalspresets.md) + +## ExternalsPresets interface + +Presets for external bundle dependencies. + +**Signature:** + +```typescript +export interface ExternalsPresets +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `reactlynx?` | `boolean \| ReactLynxExternalsPresetOptions` | Load the ReactLynx runtime bundle and wire its standard module globals. | +| `[presetName: string]` | `boolean \| object \| undefined` | Additional custom preset flags. | diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.md index db680c80a..e313b11f3 100644 --- a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.md +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.md @@ -10,11 +10,29 @@ A rsbuild plugin for loading external bundles using externals-loading-webpack-pl | Function | Description | | --- | --- | -| [pluginExternalBundle(options)](./external-bundle-rsbuild-plugin.pluginexternalbundle.md) |

Create a rsbuild plugin for loading external bundles.

This plugin wraps the externals-loading-webpack-plugin and automatically retrieves layer names from the react-rsbuild-plugin via api.useExposed.

| +| [normalizeBundlePath(bundlePath)](./external-bundle-rsbuild-plugin.normalizebundlepath.md) | Normalize a public bundle path by removing leading slashes. | +| [pluginExternalBundle(options)](./external-bundle-rsbuild-plugin.pluginexternalbundle.md) | Create a rsbuild plugin for loading external bundles. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [ExternalsPresetContext](./external-bundle-rsbuild-plugin.externalspresetcontext.md) | Context passed to externals preset resolvers. | +| [ExternalsPresetDefinition](./external-bundle-rsbuild-plugin.externalspresetdefinition.md) | Definition for a named externals preset. | +| [ExternalsPresets](./external-bundle-rsbuild-plugin.externalspresets.md) | Presets for external bundle dependencies. | +| [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | Options for the external-bundle-rsbuild-plugin. | +| [PluginExternalValue](./external-bundle-rsbuild-plugin.pluginexternalvalue.md) | External bundle reference accepted by `pluginExternalBundle`. | +| [ReactLynxExternalsPresetOptions](./external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) | Options for the built-in `reactlynx` externals preset. | ## Type Aliases | Type Alias | Description | | --- | --- | -| [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | Options for the external-bundle-rsbuild-plugin. | +| [ExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.externalspresetdefinitions.md) | Available externals preset definitions. | +| [PluginExternalConfig](./external-bundle-rsbuild-plugin.pluginexternalconfig.md) | External bundle shorthand accepted by `pluginExternalBundle`. | + +## Variables +| Variable | Description | +| --- | --- | +| [builtInExternalsPresetDefinitions](./external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md) | Built-in externals preset definitions. | diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md new file mode 100644 index 000000000..b247532ee --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [normalizeBundlePath](./external-bundle-rsbuild-plugin.normalizebundlepath.md) + +## normalizeBundlePath() function + +Normalize a public bundle path by removing leading slashes. + +**Signature:** + +```typescript +export declare function normalizeBundlePath(bundlePath: string): string; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| bundlePath | `string` | The bundle path to normalize. | + +**Returns:** + +`string` diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md index de597591d..80562840e 100644 --- a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md @@ -6,8 +6,6 @@ Create a rsbuild plugin for loading external bundles. -This plugin wraps the externals-loading-webpack-plugin and automatically retrieves layer names from the react-rsbuild-plugin via api.useExposed. - **Signature:** ```typescript @@ -18,17 +16,15 @@ export declare function pluginExternalBundle(options: PluginExternalBundleOption | Parameter | Type | Description | | --- | --- | --- | -| options | [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | | +| options | [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) | Plugin options. | **Returns:** -RsbuildPlugin +`RsbuildPlugin` ## Example - ```ts -// lynx.config.ts import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin' import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin' @@ -36,15 +32,14 @@ export default { plugins: [ pluginReactLynx(), pluginExternalBundle({ + externalsPresets: { + reactlynx: true, + }, externals: { - lodash: { - url: 'http://lodash.lynx.bundle', - background: { sectionPath: 'background' }, - mainThread: { sectionPath: 'mainThread' }, - }, + './App.js': 'comp-lib.lynx.bundle', }, + globalObject: 'globalThis', }), ], } ``` - diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md index 5bca24b3b..850628ed4 100644 --- a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md @@ -2,14 +2,23 @@ [Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](./external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) -## PluginExternalBundleOptions type +## PluginExternalBundleOptions interface Options for the external-bundle-rsbuild-plugin. **Signature:** ```typescript -export type PluginExternalBundleOptions = Pick; +export interface PluginExternalBundleOptions extends Pick ``` -**References:** [ExternalsLoadingPluginOptions](./externals-loading-webpack-plugin.externalsloadingpluginoptions.md) +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `externalBundleRoot?` | `string` | Root directory that stores project-owned external bundles referenced by `bundlePath`. | +| `externals?` | `Record` | Additional explicit externals to load. | +| `externalsPresetDefinitions?` | `ExternalsPresetDefinitions` | Definitions for custom externals presets enabled by `externalsPresets`. | +| `externalsPresets?` | [`ExternalsPresets`](./external-bundle-rsbuild-plugin.externalspresets.md) | Presets for external libraries. | +| `globalObject?` | `ExternalsLoadingPluginOptions['globalObject']` | Global object used to mount external libraries. | +| `timeout?` | `number` | Default timeout for loading external bundles. | diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md new file mode 100644 index 000000000..f2344a364 --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [PluginExternalConfig](./external-bundle-rsbuild-plugin.pluginexternalconfig.md) + +## PluginExternalConfig type alias + +External bundle shorthand accepted by `pluginExternalBundle`. + +When a string is provided, it is treated as `bundlePath` and the plugin infers: + +- `libraryName`: the external request key +- `background.sectionPath`: the external request key +- `mainThread.sectionPath`: `${request}__main-thread` + +**Signature:** + +```typescript +export type PluginExternalConfig = PluginExternalValue | string; +``` diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md new file mode 100644 index 000000000..53543ae74 --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [PluginExternalValue](./external-bundle-rsbuild-plugin.pluginexternalvalue.md) + +## PluginExternalValue interface + +External bundle reference accepted by `pluginExternalBundle`. + +**Signature:** + +```typescript +export interface PluginExternalValue extends Omit +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `bundlePath?` | `string` | Bundle path resolved against the runtime public path. | +| `url?` | `string` | Deprecated. Prefer `bundlePath` unless the bundle is hosted outside the current build output. | diff --git a/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md new file mode 100644 index 000000000..e608e0543 --- /dev/null +++ b/docs/zh/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@lynx-js/external-bundle-rsbuild-plugin](./external-bundle-rsbuild-plugin.md) > [ReactLynxExternalsPresetOptions](./external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) + +## ReactLynxExternalsPresetOptions interface + +Options for the built-in `reactlynx` externals preset. + +**Signature:** + +```typescript +export interface ReactLynxExternalsPresetOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `bundlePath?` | `string` | Emit the ReactLynx runtime bundle into the current build output and load it through the runtime public path. | +| `reactUmdPackageName?` | `string` | Package name that provides the ReactLynx runtime bundle. | +| `url?` | `string` | Deprecated. Override the runtime bundle URL directly. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md new file mode 100644 index 000000000..47c485a96 --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [builtInExternalsPresetDefinitions](./lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md) + +## builtInExternalsPresetDefinitions variable + +Built-in externals preset definitions. + +**Signature:** + +```typescript +export declare const builtInExternalsPresetDefinitions: ExternalsPresetDefinitions; +``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md index 53691e835..3b1bbfed7 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md @@ -9,5 +9,5 @@ The default lib config for external bundle. **Signature:** ```typescript -defaultExternalBundleLibConfig: LibConfig +export declare const defaultExternalBundleLibConfig: LibConfig; ``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md index 0a60ff832..925c63492 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md @@ -4,7 +4,7 @@ ## defineExternalBundleRslibConfig() function -Get the rslib config for building Lynx external bundles. +Get the Rslib config for building Lynx external bundles. **Signature:** @@ -16,73 +16,32 @@ export declare function defineExternalBundleRslibConfig(userLibConfig: ExternalB | Parameter | Type | Description | | --- | --- | --- | -| userLibConfig | ExternalBundleLibConfig | | -| encodeOptions | [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | _(Optional)_ | +| userLibConfig | [ExternalBundleLibConfig](./lynx-bundle-rslib-config.externalbundlelibconfig.md) | User-provided Rslib config. | +| encodeOptions | [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | Optional encode options. | **Returns:** -RslibConfig +`RslibConfig` -## Example 1 +## Example -If you want to build an external bundle which use in Lynx background thread, you can use the following code: - -```js -// rslib.config.js -import { defineExternalBundleRslibConfig, LAYERS } from '@lynx-js/lynx-bundle-rslib-config' - -export default defineExternalBundleRslibConfig({ - id: 'utils-lib', - source: { - entry: { - utils: { - import: './src/utils.ts', - layer: LAYERS.BACKGROUND, - } - } - } -}) -``` -Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in background thread. - -## Example 2 - -If you want to build an external bundle which use in Lynx main thread, you can use the following code: - -```js -// rslib.config.js -import { defineExternalBundleRslibConfig, LAYERS } from '@lynx-js/lynx-bundle-rslib-config' - -export default defineExternalBundleRslibConfig({ - id: 'utils-lib', - source: { - entry: { - utils: { - import: './src/utils.ts', - layer: LAYERS.MAIN_THREAD, - } - } - } -}) -``` -Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in main-thread. - -## Example 3 - -If you want to build an external bundle which use both in Lynx main thread and background thread. You don't need to set the layer. - -```js -// rslib.config.js +```ts import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config' +import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin' export default defineExternalBundleRslibConfig({ - id: 'utils-lib', + id: 'comp-lib', source: { entry: { - utils: './src/utils.ts', + './App.js': './external-bundle/CompLib.tsx', }, - } + }, + plugins: [pluginReactLynx()], + output: { + externalsPresets: { + reactlynx: true, + }, + globalObject: 'globalThis', + }, }) ``` -Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in background thread and `lynx.loadScript('utils__main-thread', { bundleName: 'utils-lib-bundle-url' })` in main-thread. - diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md index 5fb6d2cd7..e0fc59bdb 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md @@ -4,17 +4,16 @@ ## EncodeOptions interface -The options for encoding the external bundle. +Options for encoding the external bundle. **Signature:** ```typescript -export interface EncodeOptions +export interface EncodeOptions ``` ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [targetSdkVersion?](./lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md) | | string | _(Optional)_ The target SDK version of the external bundle. | - +| Property | Type | Description | +| --- | --- | --- | +| `engineVersion?` | `string` | The engine version of the external bundle. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md deleted file mode 100644 index 608322009..000000000 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) > [targetSdkVersion](./lynx-bundle-rslib-config.encodeoptions.targetsdkversion.md) - -## EncodeOptions.targetSdkVersion property - -The target SDK version of the external bundle. - -**Signature:** - -```typescript -targetSdkVersion?: string; -``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md new file mode 100644 index 000000000..0ce8553a7 --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalBundleLibConfig](./lynx-bundle-rslib-config.externalbundlelibconfig.md) + +## ExternalBundleLibConfig interface + +Rslib config shape accepted by `defineExternalBundleRslibConfig`. + +**Signature:** + +```typescript +export interface ExternalBundleLibConfig extends LibConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `output?` | [`OutputConfig`](./lynx-bundle-rslib-config.outputconfig.md) | Output config accepted by Lynx external bundle builds. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md index cc3495de6..db5e1181c 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md @@ -4,23 +4,22 @@ ## ExternalBundleWebpackPlugin class -The webpack plugin to build and emit the external bundle. +Webpack plugin that builds and emits an external bundle. **Signature:** ```typescript -export declare class ExternalBundleWebpackPlugin +export declare class ExternalBundleWebpackPlugin ``` ## Constructors -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(options)](./lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_.md) | | Constructs a new instance of the ExternalBundleWebpackPlugin class | +| Constructor | Description | +| --- | --- | +| `new ExternalBundleWebpackPlugin(options)` | Constructs a new instance of `ExternalBundleWebpackPlugin`. | ## Methods -| Method | Modifiers | Description | +| Method | Return Type | Description | | --- | --- | --- | -| [apply(compiler)](./lynx-bundle-rslib-config.externalbundlewebpackplugin.apply.md) | | | - +| `apply(compiler)` | `void` | Apply the plugin to the compiler. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md index a92179683..1e12160bf 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md @@ -4,19 +4,18 @@ ## ExternalBundleWebpackPluginOptions interface -The options for [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md). +Options for `ExternalBundleWebpackPlugin`. **Signature:** ```typescript -export interface ExternalBundleWebpackPluginOptions +export interface ExternalBundleWebpackPluginOptions ``` ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [bundleFileName](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename.md) | | string | The external bundle filename. | -| [encode](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode.md) | | (opts: unknown) => Promise<{ buffer: Buffer; }> | The encode method which is exported from lynx-tasm package. | -| [targetSdkVersion?](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md) | | string \| undefined | _(Optional)_ The target SDK version of the external bundle. | - +| Property | Type | Description | +| --- | --- | --- | +| `bundleFileName` | `string` | The external bundle filename. | +| `encode` | `(opts: unknown) => Promise<{ buffer: Buffer; }>` | Encode method exported from the Lynx encoder package. | +| `engineVersion?` | `string` | The target engine version of the external bundle. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md deleted file mode 100644 index 93e2decc8..000000000 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) > [targetSdkVersion](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.targetsdkversion.md) - -## ExternalBundleWebpackPluginOptions.targetSdkVersion property - -The target SDK version of the external bundle. - -**Signature:** - -```typescript -targetSdkVersion?: string | undefined; -``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externals.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externals.md new file mode 100644 index 000000000..6725c2dc3 --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externals.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [Externals](./lynx-bundle-rslib-config.externals.md) + +## Externals type alias + +External module to global-name mappings used when building Lynx external bundles. + +**Signature:** + +```typescript +export type Externals = Record; +``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md new file mode 100644 index 000000000..16849726c --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalsPresetDefinition](./lynx-bundle-rslib-config.externalspresetdefinition.md) + +## ExternalsPresetDefinition interface + +Definition for a named externals preset. + +**Signature:** + +```typescript +export interface ExternalsPresetDefinition +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `extends?` | `string \| string[]` | Other preset names to include before applying the current preset. | +| `externals?` | [`Externals`](./lynx-bundle-rslib-config.externals.md) | Externals contributed by this preset. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md new file mode 100644 index 000000000..d4e6876de --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalsPresetDefinitions](./lynx-bundle-rslib-config.externalspresetdefinitions.md) + +## ExternalsPresetDefinitions type alias + +Available externals preset definitions. + +**Signature:** + +```typescript +export type ExternalsPresetDefinitions = Record; +``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md new file mode 100644 index 000000000..3a5ed3787 --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [ExternalsPresets](./lynx-bundle-rslib-config.externalspresets.md) + +## ExternalsPresets type alias + +Enabled externals presets. + +**Signature:** + +```typescript +export type ExternalsPresets = { + reactlynx?: boolean; +} & Record; +``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.layers.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.layers.md deleted file mode 100644 index 2437d8804..000000000 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.layers.md +++ /dev/null @@ -1,16 +0,0 @@ - - -[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [LAYERS](./lynx-bundle-rslib-config.layers.md) - -## LAYERS variable - -The Layer name of background and main-thread. - -**Signature:** - -```typescript -LAYERS: { - readonly BACKGROUND: "background"; - readonly MAIN_THREAD: "main-thread"; -} -``` diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md index 25753026c..5ec8ed50c 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md @@ -4,23 +4,22 @@ ## MainThreadRuntimeWrapperWebpackPlugin class -The main-thread runtime wrapper for external bundle. +Webpack plugin that wraps main-thread runtime modules for external bundles. **Signature:** ```typescript -export declare class MainThreadRuntimeWrapperWebpackPlugin +export declare class MainThreadRuntimeWrapperWebpackPlugin ``` ## Constructors -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(options)](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_.md) | | Constructs a new instance of the MainThreadRuntimeWrapperWebpackPlugin class | +| Constructor | Description | +| --- | --- | +| `new MainThreadRuntimeWrapperWebpackPlugin(options?)` | Constructs a new instance of `MainThreadRuntimeWrapperWebpackPlugin`. | ## Methods -| Method | Modifiers | Description | +| Method | Return Type | Description | | --- | --- | --- | -| [apply(compiler)](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply.md) | | | - +| `apply(compiler)` | `void` | Apply the plugin to the compiler. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md index ad374d0f4..e0767cf82 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md @@ -4,17 +4,16 @@ ## MainThreadRuntimeWrapperWebpackPluginOptions interface -The options of [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md). +Options for `MainThreadRuntimeWrapperWebpackPlugin`. **Signature:** ```typescript -export interface MainThreadRuntimeWrapperWebpackPluginOptions +export interface MainThreadRuntimeWrapperWebpackPluginOptions ``` ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [test](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test.md) | | BannerPlugin\['options'\]\['test'\] | Include all modules that pass test assertion. | - +| Property | Type | Description | +| --- | --- | --- | +| `test` | `BannerPlugin['options']['test']` | Include all modules that pass the test assertion. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.md index faea3d794..1705c30ec 100644 --- a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.md +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.md @@ -4,33 +4,44 @@ ## lynx-bundle-rslib-config package -`@lynx-js/lynx-bundle-rslib-config` is the package that provides the configurations for bundling Lynx bundle with [Rslib](https://rslib.rs/). +`@lynx-js/lynx-bundle-rslib-config` is the package that provides the configurations for bundling Lynx bundle with [Rslib](https://rslib.rs/). ## Classes | Class | Description | | --- | --- | -| [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md) | The webpack plugin to build and emit the external bundle. | -| [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md) | The main-thread runtime wrapper for external bundle. | +| [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md) | Webpack plugin that builds and emits an external bundle. | +| [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md) | Webpack plugin that wraps main-thread runtime modules for external bundles. | ## Functions | Function | Description | | --- | --- | -| [defineExternalBundleRslibConfig(userLibConfig, encodeOptions)](./lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md) | Get the rslib config for building Lynx external bundles. | +| [defineExternalBundleRslibConfig(userLibConfig, encodeOptions)](./lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md) | Get the Rslib config for building Lynx external bundles. | ## Interfaces | Interface | Description | | --- | --- | -| [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | The options for encoding the external bundle. | -| [ExternalBundleWebpackPluginOptions](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) | The options for [ExternalBundleWebpackPlugin](./lynx-bundle-rslib-config.externalbundlewebpackplugin.md). | -| [MainThreadRuntimeWrapperWebpackPluginOptions](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md) | The options of [MainThreadRuntimeWrapperWebpackPlugin](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md). | +| [EncodeOptions](./lynx-bundle-rslib-config.encodeoptions.md) | Options for encoding the external bundle. | +| [ExternalBundleLibConfig](./lynx-bundle-rslib-config.externalbundlelibconfig.md) | Rslib config shape accepted by `defineExternalBundleRslibConfig`. | +| [ExternalBundleWebpackPluginOptions](./lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) | Options for `ExternalBundleWebpackPlugin`. | +| [ExternalsPresetDefinition](./lynx-bundle-rslib-config.externalspresetdefinition.md) | Definition for a named externals preset. | +| [MainThreadRuntimeWrapperWebpackPluginOptions](./lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md) | Options for `MainThreadRuntimeWrapperWebpackPlugin`. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [Externals](./lynx-bundle-rslib-config.externals.md) | External module to global-name mappings used when building Lynx external bundles. | +| [ExternalsPresetDefinitions](./lynx-bundle-rslib-config.externalspresetdefinitions.md) | Available externals preset definitions. | +| [ExternalsPresets](./lynx-bundle-rslib-config.externalspresets.md) | Enabled externals presets. | +| [OutputConfig](./lynx-bundle-rslib-config.outputconfig.md) | Output config accepted by Lynx external bundle builds. | ## Variables | Variable | Description | | --- | --- | +| [builtInExternalsPresetDefinitions](./lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md) | Built-in externals preset definitions. | | [defaultExternalBundleLibConfig](./lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md) | The default lib config for external bundle. | -| [LAYERS](./lynx-bundle-rslib-config.layers.md) | The Layer name of background and main-thread. | - +| [reactLynxExternalsPreset](./lynx-bundle-rslib-config.reactlynxexternalspreset.md) | Standard ReactLynx external mappings used by the built-in `reactlynx` preset. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md new file mode 100644 index 000000000..35b74a59b --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [OutputConfig](./lynx-bundle-rslib-config.outputconfig.md) + +## OutputConfig type alias + +Output config accepted by Lynx external bundle builds. + +**Signature:** + +```typescript +export type OutputConfig = Required['output'] & { + externalsPresets?: ExternalsPresets; + externalsPresetDefinitions?: ExternalsPresetDefinitions; + externals?: Externals; + globalObject?: 'lynx' | 'globalThis'; +}; +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `externals?` | [`Externals`](./lynx-bundle-rslib-config.externals.md) | Explicit external module mappings. | +| `externalsPresetDefinitions?` | [`ExternalsPresetDefinitions`](./lynx-bundle-rslib-config.externalspresetdefinitions.md) | Definitions for custom presets enabled by `externalsPresets`. | +| `externalsPresets?` | [`ExternalsPresets`](./lynx-bundle-rslib-config.externalspresets.md) | Presets for external libraries. | +| `globalObject?` | `'lynx' \| 'globalThis'` | Global object used to mount the built library. | diff --git a/docs/zh/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md new file mode 100644 index 000000000..04f5099eb --- /dev/null +++ b/docs/zh/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@lynx-js/lynx-bundle-rslib-config](./lynx-bundle-rslib-config.md) > [reactLynxExternalsPreset](./lynx-bundle-rslib-config.reactlynxexternalspreset.md) + +## reactLynxExternalsPreset variable + +Standard ReactLynx external mappings used by the built-in `reactlynx` preset. + +**Signature:** + +```typescript +export declare const reactLynxExternalsPreset: Externals; +``` diff --git a/docs/zh/rspeedy/external-bundle.mdx b/docs/zh/rspeedy/external-bundle.mdx index 6a92a29e4..b356384c6 100644 --- a/docs/zh/rspeedy/external-bundle.mdx +++ b/docs/zh/rspeedy/external-bundle.mdx @@ -1,378 +1,256 @@ import { PackageManagerTabs } from '@theme'; -import { VersionBadge } from '@lynx'; +import { Go, VersionBadge } from '@lynx'; # External Bundle -External Bundle 是指将代码打包为可在**不同** Lynx 应用中运行时动态加载的模块，以减小产物体积。使用流程包含两个步骤： - -1. **[`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config)** - 用于构建 External Bundle -2. **[`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin)** - 用于在应用中加载 External Bundle - :::info +加载 External Bundle 中的 CSS 文件需要 Lynx 3.7 及以上版本。 +::: -与 [Chunk Splitting](/api/rspeedy/rspeedy.performance.chunksplit) 区别： - -1. **线程支持范围**：Chunk Splitting 仅支持后台线程代码拆分，External Bundle 同时支持后台线程和主线程 -2. **跨应用共享**：External Bundle 可以在多个 Lynx 应用之间共享，减少重复代码；而 Chunk Splitting 的产物仅在当前应用内使用 -3. **打包方式**：Chunk Splitting 是构建时自动拆分，与应用产物一起部署；External Bundle 需要单独构建，可以与应用产物一起部署、也可以上传到 CDN 或服务器，运行时动态加载 -4. **使用场景**：External Bundle 适合跨应用共享的通用库（如 `lodash-es`、`moment`）；Chunk Splitting 适合单应用内的代码分割优化 +External Bundle 用来把 Lynx 代码打成一份可复用的独立 bundle，并在多个 Lynx 应用里按需加载。它适合抽离 ReactLynx 组件库或跨应用共享的业务 bundle。 -::: +和 [Chunk Splitting](/api/rspeedy/rspeedy.performance.chunksplit) 的区别可以简单理解为：External Bundle 解决跨应用复用，Chunk Splitting 解决单应用内拆包。 -## 1. 构建 External Bundle +整个流程分成两步： -### 安装 +1. 用 [`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config) 构建 external bundle。 +2. 用 [`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin) 在宿主应用里加载它。 - +## 安装 -### 基础用法 + -在 `rslib.config.ts` 中使用 [`defineExternalBundleRslibConfig()`](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig) 定义 External Bundle 的构建配置。 +## 构建 External Bundle -#### 示例 1：同时支持后台线程和主线程 +对于 ReactLynx 组件 bundle，推荐直接使用下面这套配置： -```js title="rslib.config.ts" +```ts title="rslib-comp-lib.config.ts" import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; - -const require = createRequire(import.meta.url); +import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; export default defineExternalBundleRslibConfig({ - id: 'lodash-es', + id: 'comp-lib', source: { entry: { - 'lodash-es': require.resolve('lodash-es'), + './App.js': './external-bundle/CompLib.tsx', + }, + }, + plugins: [pluginReactLynx()], + output: { + externalsPresets: { + reactlynx: true, }, }, }); ``` -执行以下命令构建： - - - -输出文件为 `dist/lodash-es.lynx.bundle`，文件名前缀由 `id` 配置决定。可将 `.lynx.bundle` 文件上传至 CDN 或服务器。 +`externalsPresets.reactlynx` 会帮你补齐标准的 ReactLynx 运行时映射，让 ReactLynx 组件 bundle 可以直接依赖共享运行时。 -:::tip -由于 Lynx 后台线程和主线程的产物格式不同，当前版本会针对两个线程分别构建产物。`dist/lodash-es.lynx.bundle` 产物内容类似于： +执行构建： -```js -{ - 'lodash-es': `// background code`, // 后台线程产物 - 'lodash-es__main-thread': `// main-thread code`, // `__main-thread` 是自动生成的后缀，代表主线程产物 -} -``` + -后续版本将支持统一的代码产物，以进一步减小产物体积。 -::: - -:::info Section Path 命名规则 - -上述产物中的 `'lodash-es'` 和 `'lodash-es__main-thread'` 称为 **section path**，是 `.lynx.bundle` 内部模块的标识符。这些 section path 在加载 external bundle 时需要通过 [`background.sectionPath`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle#backgroundsectionpath) 和 [`mainThread.sectionPath`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle#mainthreadsectionpath) 配置。我们将在下面的章节介绍到。 -::: +## 在宿主应用中加载 -#### 示例 2：仅用于后台线程 +宿主应用里使用同一个 request key： -```js title="rslib.config.ts" {15} -import { - defineExternalBundleRslibConfig, - LAYERS, -} from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; - -const require = createRequire(import.meta.url); +```ts title="lynx.config.ts" +import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'; +import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'; +import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; +import { defineConfig } from '@lynx-js/rspeedy'; -export default defineExternalBundleRslibConfig({ - id: 'lodash-es', - source: { - entry: { - 'lodash-es': { - import: require.resolve('lodash-es'), - layer: LAYERS.BACKGROUND, +export default defineConfig({ + plugins: [ + pluginReactLynx(), + pluginQRCode(), + pluginExternalBundle({ + externalsPresets: { + reactlynx: true, }, - }, - }, + externals: { + './App.js': 'comp-lib.lynx.bundle', + }, + }), + ], }); ``` -`dist/lodash-es.lynx.bundle` 产物内容类似于： +这里的简写，等价于下面这份展开后的配置： -```js -{ - 'lodash-es': `// lodash-es background code`, +```ts +externals: { + './App.js': { + bundlePath: 'comp-lib.lynx.bundle', + libraryName: './App.js', + background: { sectionPath: './App.js' }, + mainThread: { sectionPath: './App.js__main-thread' }, + async: true, + }, } ``` -#### 示例 3：仅用于主线程 +如果 section name 和 request key 本来就一致，这就是最简洁的推荐写法。 -```js title="rslib.config.ts" {15} -import { - defineExternalBundleRslibConfig, - LAYERS, -} from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; +## 什么时候配置 `globalObject` -const require = createRequire(import.meta.url); +大多数项目都不需要配置 `globalObject`。 -export default defineExternalBundleRslibConfig({ - id: 'lodash-es', - source: { - entry: { - 'lodash-es': { - import: require.resolve('lodash-es'), - layer: LAYERS.MAIN_THREAD, - }, - }, - }, -}); -``` +只有在你的应用开启了后台线程之间共享 `globalThis`，并且希望后续 bundle 复用之前已经加载过的 externals 时，才需要设置 `globalObject: 'globalThis'`。 -`dist/lodash-es.lynx.bundle` 产物内容类似于： +需要时，构建侧和宿主侧都保持一致： -```js -{ - 'lodash-es': `// lodash-es main-thread code`, +```ts title="rslib-comp-lib.config.ts" +output: { + externalsPresets: { + reactlynx: true, + }, + globalObject: 'globalThis', } ``` -### 打包多个依赖 - -支持将多个依赖打包到同一个 external bundle，减少运行时请求次数，提升性能。 - -```js title="rslib.config.ts" -import { - defineExternalBundleRslibConfig, - LAYERS, -} from '@lynx-js/lynx-bundle-rslib-config'; -import { createRequire } from 'node:module'; - -const require = createRequire(import.meta.url); - -export default defineExternalBundleRslibConfig({ - id: 'lodash', - source: { - entry: { - 'lodash.get': require.resolve('lodash.get'), - 'lodash.isequal': require.resolve('lodash.isequal'), - }, +```ts title="lynx.config.ts" +pluginExternalBundle({ + externalsPresets: { + reactlynx: true, + }, + externals: { + './App.js': 'comp-lib.lynx.bundle', }, + globalObject: 'globalThis', }); ``` -`dist/lodash.lynx.bundle` 产物内容类似于： +## 为什么需要 `@lynx-js/react-umd` -```js -{ - 'lodash.get': '// lodash.get background code', - 'lodash.get__main-thread': '// lodash.get main-thread code', - 'lodash.isequal': '// lodash.isequal background code', - 'lodash.isequal__main-thread': '// lodash.isequal main-thread code', -} -``` +`@lynx-js/react-umd` 提供的是 `reactlynx` 内置 preset 依赖的 ReactLynx 运行时 bundle。 -### 引用其他 External Bundle +当你在 [`pluginExternalBundle()`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle) 里开启 `externalsPresets.reactlynx` 时，插件会根据 `NODE_ENV` 自动解析 `@lynx-js/react-umd/dev` 或 `@lynx-js/react-umd/prod`，产出 `react.lynx.bundle`，并通过当前运行时 public path 去加载它。 -当 external bundle 依赖其他 external bundle 时，可通过 [`output.externals`](https://rslib.rs/config/rsbuild/output#outputexternals) 将这些依赖声明为外部依赖，避免重复打包： +对大多数项目来说，推荐路径就是： -```js title="rslib.config.ts" -import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'; +- 安装 `@lynx-js/react-umd` +- 开启 `reactlynx` +- 让 preset 提供 ReactLynx 运行时映射 -export default defineExternalBundleRslibConfig({ - id: 'my-components', - output: { - externals: { - // 从 ReactLynx.React 中读取 @lynx-js/react - '@lynx-js/react': ['ReactLynx', 'React'], - }, - }, -}); -``` +## 扩展 Presets -:::warning -在运行时加载 `my-components` 之前，必须确保 `@lynx-js/react` external bundle 已经加载完成，否则会导致运行时错误。 -::: +推荐让构建侧和宿主侧使用同一个 preset 名称，这样“构建阶段的 external 映射”和“运行时的 bundle 加载规则”才能保持一致。 -### 自定义配置 +### 从 Lib 侧扩展 -`defineExternalBundleRslibConfig()` 会自动应用[默认配置](https://github.com/lynx-family/lynx-stack/blob/71b9083d7c117666ae815e62ced38709c3d207e6/packages/rspeedy/lynx-bundle-rslib-config/src/externalBundleRslibConfig.ts#L42)。如需修改默认配置，直接在配置对象中覆盖即可： +在 external bundle 构建侧，通过 `defineExternalBundleRslibConfig({ output })` 里的 `externalsPresets` 和 `externalsPresetDefinitions` 扩展： -```js title="rslib.config.ts" {5-13} +```ts title="rslib-comp-lib.config.ts" import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'; export default defineExternalBundleRslibConfig({ - source: { - define: { - __PROFILE__: false, - __MAIN_THREAD__: "__webpack_layer__ === 'main-thread'", - __BACKGROUND__: "__webpack_layer__ === 'background'", + output: { + externalsPresets: { + reactlynxPlus: true, + }, + externalsPresetDefinitions: { + reactlynxPlus: { + extends: 'reactlynx', + externals: { + '@lynx-js/lynx-ui': ['LynxUI', 'UI'], + }, + }, }, - }, - autoExternal: { - dependencies: true, // 将 dependencies 设为外部依赖 }, }); ``` -### 查看 Bundle 中间产物 - -`.lynx.bundle` 是编译后的产物，不可直接阅读。如需查看编译前代码，添加 `DEBUG=rspeedy` 环境变量： - -```bash -DEBUG=rspeedy npm exec rslib build -``` - -会输出以下中间产物： - -```md -./dist -├── lodash-es.js -├── lodash-es.lynx.bundle -├── lodash-es\_\_main-thread.js -└── tasm.json -``` - -## 2. 加载 External Bundle +这一侧负责的是：构建时把 import 映射成 external global。 -基于 [Webpack Externals](https://webpack.js.org/configuration/externals/) 实现。引入 external bundle 时，依赖不会被打包到主 bundle 中，而是从 `.lynx.bundle` 文件动态加载。 +### 从 Lynx 页面侧扩展 -### 安装 - - - -### 基础用法 - -若代码中使用 `lodash-es`： - -```js -import _ from 'lodash-es'; - -_.isEmpty([]); -``` - -在 `lynx.config.ts` 中使用 [`pluginExternalBundle`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle) 插件，将 `lodash-es` 配置到 `externals`，避免打包到主 bundle 中： +在宿主应用侧，通过 `pluginExternalBundle({ externalsPresets, externalsPresetDefinitions })` 扩展： ```ts title="lynx.config.ts" import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'; -import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; -export default { - plugins: [ - pluginReactLynx(), // 必须在前面 - pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash-es.lynx.bundle', - background: { sectionPath: 'lodash-es' }, - mainThread: { sectionPath: 'lodash-es__main-thread' }, - }, - }, - }), - ], -}; -``` - -配置完成后，代码中 `lodash-es` 不会被打包到主 bundle 中，而是在运行时从指定 URL 动态加载。 - -### 配置多个 external bundle - -可在 `externals` 中配置多个 external bundle： - -```ts title="lynx.config.ts" pluginExternalBundle({ - externals: { - '@lynx-js/react': { - libraryName: ['ReactLynx', 'React'], - url: 'http://example.com/react.lynx.bundle', - background: { sectionPath: 'ReactLynx' }, - mainThread: { sectionPath: 'ReactLynx__main-thread' }, - async: false, // 同步加载 - }, - 'my-components': { - url: 'http://example.com/comp-lib.lynx.bundle', - background: { sectionPath: 'components' }, - mainThread: { sectionPath: 'components__main-thread' }, + externalsPresets: { + reactlynxPlus: true, + }, + externalsPresetDefinitions: { + reactlynxPlus: { + extends: 'reactlynx', + resolveExternals() { + return { + '@lynx-js/lynx-ui': { + libraryName: ['LynxUI', 'UI'], + bundlePath: 'lynx-ui.lynx.bundle', + background: { sectionPath: 'LynxUI' }, + mainThread: { sectionPath: 'LynxUI__main-thread' }, + async: false, + }, + }; + }, }, }, }); ``` -### 配置项 +这一侧负责的是：告诉运行时 bundle 从哪里加载，以及 section name 是什么。 -- **url**: External Bundle 的加载地址（必填） -- **libraryName**: 指定全局变量名称，`string` / `string[]`（可选） -- **background**: 后台线程配置，包含 `sectionPath`（可选） -- **mainThread**: 主线程配置，包含 `sectionPath`（可选） -- **async**: 是否异步加载，默认为 `true`（可选） +如果某个应用需要覆盖 preset 结果，依然可以直接写显式 `externals`。 -#### `libraryName` +## 什么时候用对象形式的 `externals` -指定从哪个全局变量读取 external bundle 的模块导出。通常不需要配置，插件会根据 package 的导入名自动推断。 +当你需要自定义 section name、自定义导出 library name、设置 timeout，或者本地 bundle 输出到独立目录时，使用完整对象形式。 -当 external bundle 挂载到嵌套对象时，使用 `string[]` 指定访问路径： +`lynx-examples` 里的 `external-bundle` 示例就是这种写法： -```ts title="lynx.config.ts" +```ts title="lynx.config.mjs" pluginExternalBundle({ + externalBundleRoot: 'dist-external-bundle', + externalsPresets: { + reactlynx: true, + }, externals: { - '@lynx-js/react': { - libraryName: ['ReactLynx', 'React'], // 类似从 global.ReactLynx.React 读取 - url: 'http://example.com/react.lynx.bundle', + 'lodash-es': { + bundlePath: 'lodash-es.lynx.bundle', + background: { sectionPath: 'lodash-es' }, + mainThread: { sectionPath: 'lodash-es__main-thread' }, + async: false, + timeout: 10000, + }, + './components': { + bundlePath: 'comp.lynx.bundle', + background: { sectionPath: 'component' }, + mainThread: { sectionPath: 'component__main-thread' }, + async: true, + timeout: 5000, }, }, + timeout: 10000, }); ``` -#### `sectionPath` +适合这些场景： -`sectionPath` 是 external bundle 内部模块的路径标识符： +- 一个 bundle 里放多个业务模块 +- section name 和 request key 不一致 +- bundle 构建在 `dist-external-bundle` +- 需要单独控制每个 bundle 的超时或加载方式 -- **background**：后台线程使用的模块路径 -- **mainThread**：主线程使用的模块路径 - -`sectionPath` 必须与构建 external bundle 时的实际输出 section 名称完全一致，否则运行时因找不到对应模块而报错。 - -以 [构建 External Bundle - 示例 1](#示例-1同时支持后台线程和主线程) 为例，对应的 `sectionPath` 配置如下： - -```ts title="lynx.config.ts" {9,10} -import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'; +## 示例 -export default { - plugins: [ - pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash.lynx.bundle', - background: { sectionPath: 'lodash-es' }, - mainThread: { sectionPath: 'lodash-es__main-thread' }, - }, - }, - }), - ], -}; -``` +文档里可以直接打开 `lynx-examples` 的 external-bundle 示例： -若 external bundle 仅支持某个线程（参考 [构建 External Bundle - 示例 2](#示例-2仅用于后台线程) 和 [构建 External Bundle - 示例 3](#示例-3仅用于主线程)），只需配置对应线程的 `sectionPath`： + -```ts title="lynx.config.ts" -pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash.lynx.bundle', - background: { sectionPath: 'lodash-es' }, - }, - }, -}); -``` +## API 参考 -```ts title="lynx.config.ts" -// 主线程 -pluginExternalBundle({ - externals: { - 'lodash-es': { - url: 'http://cdn.example.com/lodash.lynx.bundle', - mainThread: { sectionPath: 'lodash-es' }, - }, - }, -}); -``` +- [`defineExternalBundleRslibConfig()`](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig) +- [`pluginExternalBundle()`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle) +- [`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config) +- [`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin) diff --git a/packages/lynx-example-packages/package.json b/packages/lynx-example-packages/package.json index 036785e24..1da32935f 100644 --- a/packages/lynx-example-packages/package.json +++ b/packages/lynx-example-packages/package.json @@ -19,6 +19,7 @@ "@lynx-example/design-guide": "0.4.2", "@lynx-example/element-manipulation": "0.6.6", "@lynx-example/event": "0.6.6", + "@lynx-example/external-bundle": "0.0.2", "@lynx-example/fetch": "0.6.5", "@lynx-example/frame": "0.1.2", "@lynx-example/gallery": "0.6.7", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 65f9a5994..257eb67b0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -280,6 +280,9 @@ importers: '@lynx-example/event': specifier: 0.6.6 version: 0.6.6(@types/react@19.2.14) + '@lynx-example/external-bundle': + specifier: 0.0.2 + version: 0.0.2(@types/react@19.2.14) '@lynx-example/fetch': specifier: 0.6.5 version: 0.6.5(@types/react@19.2.14) @@ -1276,6 +1279,9 @@ packages: '@lynx-example/event@0.6.6': resolution: {integrity: sha512-bNmTw4UAmuU0voB8VfpaERSsJ7BsFivUm4NCkbx3fJtqsYDSthMn/FZyL/W8Im3GPBbDhjmaGbBeyq9wZLZFmA==} + '@lynx-example/external-bundle@0.0.2': + resolution: {integrity: sha512-IJzngqzBPQCA0ucWuzyOLL8waF9t7jnq7CndpTQI0ci6ZGi7kYsvWav9NIMrAkNzU3yxsL+VoNq8rmZ4wS86ow==} + '@lynx-example/fetch@0.6.5': resolution: {integrity: sha512-UTPAbEQd8INicwnQfRUTy5lKiW8axbZpRqy5Dr7vgOAXHbN3VPldeVo91EFMGZZf5tz+S83R/ivtnsebEyztIg==} engines: {node: '>=18'} @@ -6587,6 +6593,13 @@ snapshots: - '@lynx-js/types' - '@types/react' + '@lynx-example/external-bundle@0.0.2(@types/react@19.2.14)': + dependencies: + '@lynx-js/react': 0.117.0(@types/react@19.2.14) + transitivePeerDependencies: + - '@lynx-js/types' + - '@types/react' + '@lynx-example/fetch@0.6.5(@types/react@19.2.14)': dependencies: '@lynx-js/react': 0.115.1(@types/react@19.2.14)