refactor: restructure module federation SDK types and plugins

.husky/pre-commit

@@ -1,6 +1,17 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
+# Regenerate schema validation & SDK types when JSON schemas change
+if git diff --cached --name-only | grep -qE '^packages/enhanced/src/schemas/.+\.json$'; then
+  echo "[husky] Detected schema changes, running pnpm generate:schema..."
+  pnpm generate:schema || {
+    echo "[husky] pnpm generate:schema failed";
+    exit 1;
+  }
+  # Re-stage generated files if any
+  git add packages/enhanced/src/schemas/container/*.check.ts packages/enhanced/src/schemas/container/*.ts packages/enhanced/src/schemas/sharing/*.check.ts packages/enhanced/src/schemas/sharing/*.ts packages/sdk/src/types/plugins/*.ts 2>/dev/null || true
+fi
+
 npm run lint-fix
 
 git add .

apps/website-new/docs/en/configure/experiments.mdx

@@ -24,19 +24,20 @@ When using this mode, all entrypoints will initialize asynchronously. If you're
 - **Required:** No
 - **Default:** `false`
 
-After setting `true`, the external {props.name || 'Module Federation'}  runtime will be used and the runtime provided by the consumer will be used. (Please make sure your consumer has `provideExternalRuntime: true` set, otherwise it will not run properly!)
+When set to `true`, `@module-federation/runtime-core` will be treated as an external and read from the global `_FEDERATION_RUNTIME_CORE` at runtime. Ensure the consumer provides this global (typically used together with `provideExternalRuntime`), otherwise it will not work.
 
 ## provideExternalRuntime
 
 - **Type:** `boolean`
 - **Required:** No
 - **Default:** `false`
 
-::: warning note
-Make sure to only configure it on the topmost consumer! If multiple consumers inject runtime at the same time, the ones executed later will not overwrite the existing runtime.
-:::
+Only for “pure consumer” scenarios (no `exposes`). When enabled, automatically injects `@module-federation/inject-external-runtime-core-plugin` to provide the external runtime at execution time.
 
-Setting `true` will inject the {props.name || 'Module Federation'}  runtime at the consumer.
+:::warning Notes
+- Using this together with `exposes` will throw an error — only pure consumers can enable it.
+- Prefer configuring it at the topmost consumer to avoid multiple injections.
+:::
 
 ## optimization
 

apps/website-new/docs/en/configure/getpublicpath.mdx

@@ -3,18 +3,21 @@
 - Type: `string`
 - Required: No
 - Default value: `undefined`
-- Purpose: Used to set a dynamic `publicPath`. Once set, the corresponding remote module resources will also use this `publicPath`. For instance, if the deployed project dynamically serves a `cdn_prefix`, `getPublicPath` can be set to `return "https:" + window.navigator.cdn_host + "/resource/app/"`.
+- Effective condition: only effective when `exposes` is set
+- Purpose: Used to set a dynamic `publicPath`. The value must be a stringified function or a stringified return expression. When other consumers load this provider, the string in `getPublicPath` will be executed via `new Function` to obtain the return value, which will be used as the `publicPath` prefix for the module’s static assets.
+  - Function form: ``function(){ return window.cdn_prefix }``
+  - Return form: ``return "https:" + window.navigator.cdn_host + "/resource/app/"``
 
 - Example:
 
-In the example below, `getPublicPath` is set. When other consumers load this provider, the code for `getPublicPath` will be executed using `new Function` to obtain the return value. The content of the return value will be used as the `publicPath` prefix for the static resources of the module.
+In the example below, `getPublicPath` is set. When other consumers load this provider, the string in `getPublicPath` will be executed using `new Function` to obtain the value, which will be used as the `publicPath` prefix for the module’s static assets.
 
 :::tip NOTE
-```getPublicPath``` Must be a function as a string.
+`getPublicPath` must be a stringified function or a stringified return expression.
 :::
 
 :::tip NOTE
-If you're using module federation webpack plugin and want to set a dynamic publicPath, you should set `__webpack_public_path__ = window.cdn_prefix` statement in `getPublicPath` function body.
+If you're using the module federation webpack plugin and want to set a dynamic publicPath, you should set `__webpack_public_path__ = window.cdn_prefix` in the `getPublicPath` function body.
 :::
 
 ```ts title="rspack.config.ts"

apps/website-new/docs/en/configure/treeShakingSharedPlugins.mdx

@@ -1,6 +1,6 @@
 # treeShakingSharedPlugins
 
-Allows users to explicitly specify which plugins should participate in the second tree-shaking pass for shared modules.
+A list of plugin module paths used when building independent shared fallbacks. During the secondary tree-shaking build, each item will be `require(p)`-loaded and instantiated to participate in compilation.
 
 - Type: `string[]`
 - Required: No

apps/website-new/docs/zh/configure/experiments.mdx

@@ -24,19 +24,20 @@
 - Required: No
 - Default: `false`
 
-设置 `true` 后 会 external {props.name || 'Module Federation'}  runtime，并使用消费者提供的 runtime 。（请确保你的消费者有设置 `provideExternalRuntime: true`，否则无法正常运行！）
+设置为 `true` 时，将把 `@module-federation/runtime-core` 作为外部依赖处理，并在运行时从全局变量 `_FEDERATION_RUNTIME_CORE` 读取。请确保消费者侧已正确提供该全局变量（通常与 `provideExternalRuntime` 配合使用），否则无法正常运行。
 
 ## provideExternalRuntime
 
 - Type: `boolean`
 - Required: No
 - Default: `false`
 
-::: warning 注意
-请确保仅在最顶层消费者配置！若同时有多个消费者注入 runtime，后执行的不会覆盖已有的 runtime。
-:::
+仅用于“纯消费者”（没有设置 `exposes`）的场景。开启后会自动注入 `@module-federation/inject-external-runtime-core-plugin` 以在运行时提供必要的外部 runtime。
 
-设置 `true` 后会在消费者处注入 {props.name || 'Module Federation'}  runtime。
+:::warning 注意
+- 与 `exposes` 同时使用会报错：仅纯消费者可开启。
+- 建议仅在应用最顶层消费者配置，避免多个消费者重复注入。
+:::
 
 
 ## optimization

apps/website-new/docs/zh/configure/getpublicpath.mdx

@@ -3,11 +3,14 @@
 - 类型：`string`
 - 是否必填：否
 - 默认值：`undefined`
-- 作用：用于设置动态 publicPath，设置后，对应的远程模块资源也将使用此 publicPath。例如，部署的项目是动态下发 `cdn_prefix` ，那么可以设置 `getPublicPath` 为 `return "https:" + window.navigator.cdn_host + "/resource/app/"`
+- 生效条件：仅当设置了 `exposes` 时生效
+- 作用：用于设置动态 publicPath。值为“字符串化的函数”或“字符串化的 return 表达式”。当消费者加载该生产者时，会通过 `new Function` 执行此字符串以获取返回值，并将其作为该模块静态资源的 `publicPath` 前缀。例如，部署的项目动态下发 `cdn_prefix`，可以设置：
+  - 函数形式：``function(){ return window.cdn_prefix }``
+  - return 形式：``return "https:" + window.navigator.cdn_host + "/resource/app/"``
 
 - 示例：
 
-下面的示例中，设置了 `getPublicPath`，在其他消费者加载该生产者时，将会通过 `new Function` 的方式执行 `getPublicPath` 的代码获取到返回值，将会把返回值的内容作为该模块的 `publicPath` 静态资源前缀
+下面的示例中，设置了 `getPublicPath`。在其他消费者加载该生产者时，将会通过 `new Function` 的方式执行 `getPublicPath` 字符串以获取值，并把返回值作为该模块的 `publicPath` 静态资源前缀
 
 ```ts title="rspack.config.ts"
 module.exports = {

apps/website-new/docs/zh/configure/index.mdx

@@ -4,10 +4,12 @@
 
 ```ts
 type ModuleFederationOptions {
-    // module federation name
+    // module federation name（必填）
     name: string;
     // 当前应用（host/remote）参与的共享池（默认 default）
     shareScope?: string | string[];
+    // 共享依赖加载策略（默认 'version-first'）
+    shareStrategy?: 'version-first' | 'loaded-first';
     // remoteEntry 名称
     filename?: string,
     // module federation remotes 远程模块别名和 entry 信息
@@ -16,10 +18,10 @@ type ModuleFederationOptions {
     exposes?: PluginExposesOptions;
     // 共享依赖配置
     shared?: ShareInfos;
-    // 动态 publicPath
+    // 动态 publicPath（仅当设置了 exposes 时生效）
     getPublicPath?: string;
-    // 运行时插件
-    runtimePlugins?: Array<string>;
+    // 运行时插件（支持元组 [path, params]）
+    runtimePlugins?: (string | [string, Record<string, unknown>])[];
     // runtime pkg 依赖
     implementation?: string;
     // manifest 配置
@@ -28,9 +30,22 @@ type ModuleFederationOptions {
     dev?: boolean | PluginDevOptions;
     // 控制类型生成
     dts?: boolean | PluginDtsOptions;
+    // 运行时入口使用虚拟模块（data:URI）
+    virtualRuntimeEntry?: boolean;
+    // 实验特性
+    experiments?: {
+      asyncStartup?: boolean;
+      externalRuntime?: boolean;
+      provideExternalRuntime?: boolean;
+      optimization?: {
+        disableSnapshot?: boolean;
+        target?: 'web' | 'node';
+      };
+    };
+    // Tree-shaking 相关
     injectTreeShakingUsedExports?: boolean;
     treeShakingDir?: string;
-    treeShakingSharedPlugins?: Array<string>;
-    treeShakingSharedExcludePlugins?: Array<string>;
+    treeShakingSharedPlugins?: string[];
+    treeShakingSharedExcludePlugins?: string[];
 };
 ```

apps/website-new/docs/zh/configure/shared.mdx

@@ -20,7 +20,9 @@ interface SharedConfig {
   requiredVersion?: string;
   eager?: boolean;
   shareScope?: string;
+  shareKey?: string;
   import?: string | false;
+  request?: string;
   allowNodeModulesSuffixMatch?: boolean;
   treeShaking?: TreeShakingConfig;
 }
@@ -94,6 +96,29 @@ new ModuleFederationPlugin({
 
 共享依赖作用域，默认值为 `'default'` 。
 
+## shareKey
+
+- 类型：`string`
+- 是否必填：否
+- 默认值：`shared` 配置的属性名（`key`）
+
+共享模块在 shared scope 中的协商 key。Provider 发布模块和 Consumer 匹配模块时都通过该 key 进行查找，**两端必须一致才能协商成功**，否则双方各自打包一份依赖。
+
+默认值为 `shared` 配置的属性名，大多数场景无需手动设置。典型的自定义场景是通过 `import` 将属性名映射到不同的实际包：
+
+```ts
+shared: {
+  'my-alias': {
+    import: 'react',     // 实际 resolve 的包
+    shareKey: 'react',   // shared scope 里用 "react" 协商，与其他应用对齐
+  },
+}
+```
+
+:::warning 注意
+不设置 `shareKey` 时，协商 key 就是属性名本身（此例为 `"my-alias"`）。若对端用 `"react"` 注册，则无法匹配。
+:::
+
 ## import
 
 - 类型：`string | false`
@@ -104,6 +129,32 @@ new ModuleFederationPlugin({
 
 若设置为 `false` ，则不会将此 shared 打包到产物中，仅使用消费者提供的 `shared`。 因此设置前请确认消费者已提供对应 `shared`。
 
+## request
+
+- 类型：`string`
+- 是否必填：否
+- 默认值：`shared` 配置的属性名（`key`）
+
+构建时需要拦截的模块请求路径。当代码中出现匹配该值的 `import` 时，构建器会将其替换为消费 shared scope 的模块，而不是打包进产物。
+
+默认值与属性名相同，大多数场景无需设置。`request` 与 `shareKey` 的区别：
+
+| 字段 | 作用层面 | 回答的问题 |
+|---|---|---|
+| `request` | 构建时 · 模块图 | 拦截哪个 `import` |
+| `shareKey` | 运行时 · 协商 | 去 shared scope 的哪个槽取模块 |
+
+前缀匹配场景下两者会配合使用：
+
+```ts
+shared: {
+  'lodash/': {
+    request: 'lodash/',    // 拦截所有 import 'lodash/*'
+    shareKey: 'lodash/',   // 最终协商 key = "lodash/" + 子路径后缀
+  },
+}
+```
+
 ## allowNodeModulesSuffixMatch
 
 - 类型：`boolean`

apps/website-new/docs/zh/configure/treeShakingSharedPlugins.mdx

@@ -1,6 +1,6 @@
 # treeShakingSharedPlugins
 
-允许用户显式指定哪些插件应该参与 shared 模块的第二次 treeshaking 过程。
+用于构建独立共享 fallback 的插件模块路径列表。构建二次 treeshaking 时会通过 `require(p)` 加载并实例化插件参与构建。
 
 - 类型：`string[]`
 - 是否必填：否
@@ -28,6 +28,6 @@ export default MyBuildPlugin;
 
 export default {
   // ...
-  treeShakingSharedPlugins: ['my-build-plugin@0.0.2'],
+  treeShakingSharedPlugins: ['my-build-plugin'],
 }
 ```

packages/enhanced/project.json

@@ -8,7 +8,11 @@
     "generate:schema": {
       "executor": "nx:run-commands",
       "options": {
-        "command": "node src/scripts/compile-schema.js",
+        "parallel": false,
+        "commands": [
+          "node src/scripts/compile-schema.js",
+          "node src/scripts/generate-sdk-types.js"
+        ],
         "cwd": "packages/enhanced"
       }
     },