@fulgurjs/federation 5.1.4 → 5.2.1

package/dist/vue-adapter.js

@@ -8,7 +8,7 @@ import {
 import "./chunk-TSXZ7TWA.js";
 
 // src/vue-adapter.ts
-import { defineAsyncComponent, defineComponent, h } from "vue";
+import { defineAsyncComponent, defineComponent, h, ref } from "vue";
 var ERROR_STYLE = {
   padding: "16px",
   border: "1px solid #fde2e2",
@@ -18,28 +18,111 @@ var ERROR_STYLE = {
   fontSize: "13px",
   lineHeight: "1.6"
 };
+var BUTTON_STYLE = {
+  padding: "4px 14px",
+  marginRight: "8px",
+  border: "1px solid #c45656",
+  borderRadius: "4px",
+  background: "#c45656",
+  color: "#fff",
+  fontSize: "13px",
+  cursor: "pointer"
+};
+var SECONDARY_BUTTON_STYLE = {
+  padding: "4px 14px",
+  border: "1px solid #c45656",
+  borderRadius: "4px",
+  background: "#fff",
+  color: "#c45656",
+  fontSize: "13px",
+  cursor: "pointer"
+};
 var RemoteErrorPlaceholder = defineComponent({
   name: "FulgurjsRemoteError",
-  props: { error: { type: Object, default: void 0 } },
+  props: {
+    error: { type: Object, default: void 0 },
+    retry: { type: Function, required: false, default: void 0 },
+    retrying: { type: Boolean, default: false }
+  },
   setup(props) {
+    const reloadPage = () => {
+      window.location.reload();
+    };
     return () => {
       const err = props.error;
       const code = err?.code ?? "UNKNOWN";
       const message = err?.message ?? String(props.error ?? "unknown error");
-      return h("div", { style: ERROR_STYLE }, [
+      const buttons = [
+        props.retry ? h("button", {
+          key: "retry",
+          style: BUTTON_STYLE,
+          type: "button",
+          "data-fulgurjs-retry": "",
+          disabled: props.retrying,
+          onClick: () => props.retry?.()
+        }, props.retrying ? "\u52A0\u8F7D\u4E2D\u2026" : "\u91CD\u8BD5\u52A0\u8F7D") : null,
+        h("button", {
+          key: "reload",
+          style: SECONDARY_BUTTON_STYLE,
+          type: "button",
+          "data-fulgurjs-reload": "",
+          disabled: props.retrying,
+          onClick: reloadPage
+        }, "\u5237\u65B0\u9875\u9762\u91CD\u8BD5")
+      ].filter(Boolean);
+      return h("div", { style: ERROR_STYLE, "data-fulgurjs-error": code }, [
         h("p", { style: "margin:0 0 4px;font-weight:600" }, `\u8FDC\u7A0B\u7EC4\u4EF6\u52A0\u8F7D\u5931\u8D25\uFF08\u9519\u8BEF\u7801 ${code}\uFF09`),
         h("p", { style: "margin:0 0 8px;word-break:break-all" }, message),
-        h("p", { style: "margin:0" }, "\u4FEE\u6CD5\uFF1A\u2460 \u6838\u5BF9 spec \u7684\u300C\u8FDC\u7A0B\u540D/expose \u540D\u300D\u4E0E\u8FDC\u7A0B\u5E94\u7528 exposes \u662F\u5426\u4E00\u81F4\uFF08MFU-006/008\uFF09\uFF1B\u2461 \u6838\u5BF9 remotes \u5730\u5740\u7AEF\u53E3\u4E0E\u8FDC\u7A0B\u670D\u52A1\u53EF\u8FBE\u6027\u3001remoteEntry \u662F\u5426\u53EF\u8BBF\u95EE\uFF08MFU-001\uFF09\uFF1B\u2462 \u67E5\u770B window \u7684 fulgurjs:error \u4E8B\u4EF6\u4E0E console \u540C\u6E90\u9519\u8BEF\u5B9A\u4F4D\u6839\u56E0\u3002")
+        h("p", { style: "margin:0 0 8px" }, "\u4FEE\u6CD5\uFF1A\u2460 \u6838\u5BF9 spec \u7684\u300C\u8FDC\u7A0B\u540D/expose \u540D\u300D\u4E0E\u8FDC\u7A0B\u5E94\u7528 exposes \u662F\u5426\u4E00\u81F4\uFF08MFU-006/008\uFF09\uFF1B\u2461 \u6838\u5BF9 remotes \u5730\u5740\u7AEF\u53E3\u4E0E\u8FDC\u7A0B\u670D\u52A1\u53EF\u8FBE\u6027\u3001remoteEntry \u662F\u5426\u53EF\u8BBF\u95EE\uFF08MFU-001\uFF09\uFF1B\u2462 \u67E5\u770B window \u7684 fulgurjs:error \u4E8B\u4EF6\u4E0E console \u540C\u6E90\u9519\u8BEF\u5B9A\u4F4D\u6839\u56E0\u3002"),
+        h("p", { style: "margin:0 0 10px" }, "\u300C\u91CD\u8BD5\u52A0\u8F7D\u300D\u5728\u5F53\u524D\u9875\u9762\u91CD\u5EFA\u52A0\u8F7D\uFF1B\u82E5\u6D4F\u89C8\u5668\u5DF2\u7F13\u5B58\u5931\u8D25\u7684\u6A21\u5757\uFF08\u5982\u8FDC\u7A0B\u9759\u6001\u5B50\u4F9D\u8D56\u66FE\u52A0\u8F7D\u5931\u8D25\uFF09\uFF0C\u8BF7\u7528\u300C\u5237\u65B0\u9875\u9762\u91CD\u8BD5\u300D\u2014\u2014\u5B83\u4F1A\u6574\u9875\u5237\u65B0\uFF08\u4FDD\u7559\u5F53\u524D\u5730\u5740\uFF09\uFF0C\u672A\u4FDD\u5B58\u7684\u9875\u9762\u72B6\u6001\u4F1A\u4E22\u5931\u3002"),
+        h("div", { style: "margin:0" }, buttons)
       ]);
     };
   }
 });
+function createRecoverableErrorPlaceholder(loader, spec, userErrorComponent) {
+  if (userErrorComponent) return userErrorComponent;
+  return defineComponent({
+    name: "FulgurjsRemoteErrorWithRetry",
+    props: { error: { type: Object, default: void 0 } },
+    setup(props, { attrs }) {
+      const recovered = ref(null);
+      const retrying = ref(false);
+      const retryError = ref(void 0);
+      const retry = async () => {
+        if (retrying.value) return;
+        retrying.value = true;
+        retryError.value = void 0;
+        try {
+          const mod = await loader();
+          const inner = mod?.default ?? mod;
+          if (!inner) throw noRenderableExportError(spec, inner);
+          recovered.value = inner;
+        } catch (e) {
+          retryError.value = e;
+        } finally {
+          retrying.value = false;
+        }
+      };
+      return () => {
+        const inner = recovered.value;
+        if (inner) return h(inner, attrs);
+        return h(RemoteErrorPlaceholder, {
+          error: retryError.value ?? props.error,
+          retry,
+          retrying: retrying.value
+        });
+      };
+    }
+  });
+}
 function createRemoteComponent(loadRemote) {
   return function remoteComponent(spec, opts = {}) {
+    const loader = () => loadRemote(spec, { retries: opts.retries }).then((m) => m.default ?? m);
     return defineAsyncComponent({
-      loader: () => loadRemote(spec, { retries: opts.retries }).then((m) => m.default ?? m),
+      loader,
       loadingComponent: opts.loadingComponent,
-      errorComponent: opts.errorComponent ?? RemoteErrorPlaceholder,
+      errorComponent: createRecoverableErrorPlaceholder(loader, spec, opts.errorComponent),
       delay: opts.delay,
       timeout: opts.timeout
     });
@@ -59,18 +142,19 @@ function createHostPages(options, load) {
     let comp = compCache.get(spec);
     if (!comp) {
       const name = cleanCompName(spec);
+      const pageLoader = async () => {
+        await beforeLoad?.();
+        const mod = await load(spec);
+        const inner = mod?.default ?? mod;
+        if (!inner) {
+          throw noRenderableExportError(spec, inner);
+        }
+        return inner;
+      };
       const asyncComp = defineAsyncComponent({
-        loader: async () => {
-          await beforeLoad?.();
-          const mod = await load(spec);
-          const inner = mod?.default ?? mod;
-          if (!inner) {
-            throw noRenderableExportError(spec, inner);
-          }
-          return inner;
-        },
+        loader: pageLoader,
         loadingComponent,
-        errorComponent: errorComponent ?? RemoteErrorPlaceholder,
+        errorComponent: createRecoverableErrorPlaceholder(pageLoader, spec, errorComponent),
         delay
       });
       asyncComp.name = name;

package/examples/README.en.md

@@ -0,0 +1,47 @@
+# fulgurjs-federation Examples
+
+Pick your framework, copy the host and remote directories, run `npm install`, and you get a full module federation demo. All four projects are standalone: no dependency on this repo's source, the monorepo workspace, or any parent `node_modules` — the plugin dependency is an exact published version from the npm registry.
+
+## Vue (host 5214 / remote 5213)
+
+Full walkthrough: **[vue/README.md](./vue/README.md)** (Chinese).
+
+```bash
+cd examples/vue/remote && npm install && npm run dev   # terminal 1: vue-remote, http://localhost:5213
+cd examples/vue/host   && npm install && npm run dev   # terminal 2: vue-host,   http://localhost:5214
+```
+
+## React (host 5204 / remote 5203)
+
+Full walkthrough: **[react/README.md](./react/README.md)** (Chinese).
+
+```bash
+cd examples/react/remote && npm install && npm run dev   # terminal 1: react-remote, http://localhost:5203
+cd examples/react/host   && npm install && npm run dev   # terminal 2: react-host,   http://localhost:5204
+```
+
+## What each pair demonstrates
+
+- A clickable remote counter component (local state lives inside the remote component; operated on the host page)
+- Cross-application plain TS module calls (the host renders real return values)
+- A remote home page plus a parameterized detail page (deep links survive refresh)
+- Host navigation with route-level lazy loading (the home page never bulk-prefetches unvisited remote pages)
+- The plugin's built-in loading/error placeholders and recovery actions (**Retry load** recovers in-page; **Refresh page to retry** recovers via a user-initiated full reload)
+- Production build with a minimal Nginx deployment (including SPA fallback)
+
+## Layout
+
+```text
+examples/
+├── README.md / README.en.md   # this entry (CN/EN)
+├── vue/
+│   ├── README.md              # guide for the Vue pair
+│   ├── host/                  # Vue host (vue-host, 5214)
+│   └── remote/                # Vue remote (vue-remote, 5213)
+└── react/
+    ├── README.md              # guide for the React pair
+    ├── host/                  # React host (react-host, 5204)
+    └── remote/                # React remote (react-remote, 5203)
+```
+
+> `examples/` is for users to copy and run. The repository-root `fixtures/` are internal regression harnesses (source-linked to the plugin workspace) — do not treat them as usage templates.

package/examples/README.md

@@ -1,27 +1,49 @@
-# examples — 可复制的单项目配置样例
+# fulgurjs-federation 示例总入口
 
-每个目录是一个**独立项目**的 `fulgurjs.config.ts`（4.2.0 单项目契约：默认导出直接可传给 `federation()`）：
+选择你的框架，复制对应宿主与远程两个目录，`npm install` 后即可看到完整的模块联邦演示。四个工程互相独立：不依赖本仓库源码、monorepo workspace 或父目录 node_modules，插件依赖为 npm registry 精确正式包。
 
-- [`remote-a/fulgurjs.config.ts`](./remote-a/fulgurjs.config.ts) — 远程应用：exposes / setup / shared
-- [`host/fulgurjs.config.ts`](./host/fulgurjs.config.ts) — 宿主应用：remotes 消费地址 + 可选 `hostPages` 页面核对数据（仅供 CLI）
+## Vue（宿主 5214 / 远程 5213）
 
-React 完整可运行工程（5.1.0 起，npm registry 安装即跑，区别于上面两个「配置样例」目录）：
+完整操作步骤见 **[vue/README.md](./vue/README.md)**。
 
-- [`react-remote/`](./react-remote) — React 远程（5203）：Button/utils/pages expose + shared react/react-dom singleton
-- [`react-host/`](./react-host) — React 宿主（5204）：`@fulgurjs/federation/react` 导入 + 页面表 + React Router；运行说明见其 README
+```bash
+cd examples/vue/remote && npm install && npm run dev   # 终端 1：vue-remote，http://localhost:5213
+cd examples/vue/host   && npm install && npm run dev   # 终端 2：vue-host，http://localhost:5214
+```
+
+## React（宿主 5204 / 远程 5203）
 
-复制方式：把对应文件整份复制到**你自己的项目根目录**（两个项目不共享配置文件、不共享父目录配置），再在各自 `vite.config.ts` 的 plugins 里加一次 `federation(fulgurjsConfig)`：
+完整操作步骤见 **[react/README.md](./react/README.md)**。
 
-```ts
-import federation from '@fulgurjs/federation'
-import fulgurjsConfig from './fulgurjs.config'
+```bash
+cd examples/react/remote && npm install && npm run dev   # 终端 1：react-remote，http://localhost:5203
+cd examples/react/host   && npm install && npm run dev   # 终端 2：react-host，http://localhost:5204
+```
 
-export default defineConfig({
-  plugins: [
-    // ...原有插件,
-    federation(fulgurjsConfig),
-  ],
-})
+## 每对示例演示什么
+
+- 远程可点击计数组件（本地状态在远程组件内，宿主页面直接操作）
+- 普通 TS 模块跨应用调用（宿主展示真实返回值）
+- 远程首页 + 带真实路由参数的详情页（深链刷新可恢复）
+- 宿主导航、路由级懒加载（首页不批量预取未访问的远程页面）
+- 插件默认加载/错误占位与恢复操作（**重试加载** 同页恢复；**刷新页面重试** 整页恢复）
+- 生产构建 + 最小 Nginx 部署（含 SPA fallback）
+
+## 目录
+
+```text
+examples/
+├── README.md / README.en.md   # 本入口（中/英）
+├── vue/
+│   ├── README.md              # Vue 一对示例的组合说明
+│   ├── host/                  # Vue 宿主（vue-host，5214）
+│   └── remote/                # Vue 远程（vue-remote，5213）
+└── react/
+    ├── README.md              # React 一对示例的组合说明
+    ├── host/                  # React 宿主（react-host，5204）
+    └── remote/                # React 远程（react-remote，5203）
 ```
 
-验证：在复制后的项目根目录运行 `npx fulgurjs explain`（纯本地、无网络），应输出本应用的形态摘要与 `federation(fulgurjsConfig)` 接入块。
+> `examples/` 面向使用者拷贝运行；仓库根的 `fixtures/` 是插件内部回归夹具（源码 link 到插件工作区），请勿当作使用模板。
+
+> 提示：复制后可在项目根目录运行 `npx fulgurjs explain`（纯本地、无网络）核对联邦配置摘要。

package/examples/react/README.md

@@ -0,0 +1,83 @@
+# React 联邦示例：宿主 + 远程（可直接复制运行）
+
+本目录是一对完整、可独立安装运行的 React 19 模块联邦演示：
+
+| 目录 | 角色 | 端口 | 说明 |
+| --- | --- | --- | --- |
+| [`remote/`](./remote/) | **React 远程**（被消费方） | 5203 | 暴露可点击按钮组件、普通 TS 工具模块、联邦首页与参数详情页 |
+| [`host/`](./host/) | **React 宿主**（消费方） | 5204 | 消费 react-remote 的组件/模块/页面，提供导航与懒加载 |
+
+- 包管理器统一为 **npm**；插件依赖为 **registry 精确正式包**（`@fulgurjs/federation`，见各 `package.json`），不依赖本仓库源码、monorepo workspace 或父目录 node_modules。
+- 把 `host/` 与 `remote/` 复制到**两个互不共享父目录的目录**后，各自 `npm install` 仍可运行。
+
+## 最快开始（从干净拷贝）
+
+```bash
+# 终端 1 —— 先启动远程
+cd react/remote
+npm install
+npm run dev            # http://localhost:5203
+
+# 终端 2 —— 再启动宿主
+cd react/host
+npm install
+npm run dev            # http://localhost:5204
+```
+
+打开 <http://localhost:5204/>：
+
+- 「首页」里有来自 react-remote 的**可点击计数按钮**（进入页面才按需加载）。
+- 「远程首页 / 远程详情」是 react-remote 暴露的**联邦页面**；详情页演示真实路由参数（`/remote/detail/7?tab=basic`）。
+- 「TS 模块调用」演示 `useLoadRemote` 调用 react-remote 暴露的普通 TS 模块。
+- 停掉远程 dev server 再刷新宿主页面 → 插件默认错误占位出现，提供**「重试加载」**（同页恢复）与**「刷新页面重试」**（整页恢复）两个操作；重启远程后点击即可恢复业务。
+
+## 演示的功能点
+
+| 功能 | 位置 |
+| --- | --- |
+| 远程可点击组件（Hooks 计数） | `remote/src/exposes/ClickButton.tsx`，宿主首页消费 |
+| 普通 TS 模块调用（useLoadRemote） | `remote/src/exposes/utils.ts`，`host/src/pages/UtilsDemo.tsx` |
+| 联邦页面（远程首页 / 带参数详情页） | `remote/src/exposes/pages/`，页面表见 `host/fulgurjs.config.ts` |
+| 宿主导航 + 懒加载（不批量预取） | `host/src/main.tsx`（路由级按需加载） |
+| 默认加载/错误/恢复占位 | 插件内置（`remoteComponent` / `createReactHostPages`），示例不自建错误组件 |
+
+## 生产构建与最小 Nginx 部署
+
+```bash
+cd react/remote && npm run build -- --base=/react-remote/   # 产物 remote/dist/（子路径 base 与部署位置对应）
+cd react/host   && npm run build   # 产物 host/dist/
+```
+
+部署形态：宿主部署在站点根 `/`，远程部署在子路径 `/react-remote/`（与 `host/fulgurjs.config.ts` 的 `prod: '/react-remote'` 对应）。最小 Nginx 配置：
+
+```nginx
+server {
+  listen 8081;
+
+  root /srv/react-demo/host;
+  index index.html;
+
+  location /react-remote/ {
+    alias /srv/react-demo/remote/;
+    try_files $uri $uri/ =404;
+  }
+
+  # 宿主 SPA fallback：深链刷新回退到 index.html
+  location / {
+    try_files $uri /index.html;
+  }
+}
+```
+
+部署后访问 `http://<host>:8081/`，深链 `http://<host>:8081/remote/detail/7?tab=basic` 直接刷新也能到达同一页面。
+
+## HMR 边界（dev）
+
+- 远程组件修改（文本/样式/Hooks 结构不变的改动）自动热更新到**正在显示的宿主页面**，组件本地状态保留，无整页刷新（5.2.0 起跨源 Fast Refresh 由插件保证单一 react-refresh 实例）。
+- 远程普通 TS 模块修改同样自动传播到引用它的组件边界。
+- React Refresh 不兼容的导出/Hooks 结构变化、Vite 要求 full-reload 的改动会按框架标准重新挂载或整页刷新——不承诺任意改动保活。
+
+## examples 与 fixtures 的区别
+
+`examples/` 面向**使用者**：拷贝、安装 registry 正式包、独立运行。
+仓库根的 `fixtures/` 是**插件内部回归夹具**（源码 `link:` 到插件工作区），不要当作使用模板。

package/examples/react/host/README.md

@@ -0,0 +1,49 @@
+# react-host —— React 宿主（fulgurjs 联邦演示）
+
+> **角色：React 宿主（消费方）。** 消费 [`../remote/`](../remote/)（react-remote，端口 5203）暴露的组件、TS 模块与联邦页面；本应用自身不暴露任何模块。
+
+## 从干净拷贝运行
+
+前置：Node ≥ 20.19 与 npm。
+
+```bash
+# 先启动远程（另一终端）：见 ../remote/README.md
+cd react-host        # 把本目录复制到任意位置后进入
+npm install
+npm run dev          # http://localhost:5204
+```
+
+成功画面：导航条含「首页 / 远程首页 / 远程详情 / TS 模块调用」；「远程首页」出现 react-remote 的标题与可点击计数按钮。
+
+## 目录与关键配置
+
+| 文件 | 职责 |
+| --- | --- |
+| `fulgurjs.config.ts` | **联邦唯一声明**：remotes 地址（dev/prod）、页面表 `pages`、前缀归属 `remotePrefixes` |
+| `vite.config.ts` | 标准 Vite 配置，`federation(fulgurjsConfig)` 挂载插件 |
+| `src/remotePages.tsx` | `createReactHostPages({ pages, remotePrefixes })`（模块顶层一次）；`component(spec)` 取远程页面组件 |
+| `src/App.tsx` | `remoteComponent('react-remote/ClickButton')` 消费单个远程组件 |
+| `src/pages/UtilsDemo.tsx` | `useLoadRemote('react-remote/utils')` 调用普通 TS 模块 |
+| `src/main.tsx` | react-router 路由；参数页把 `params`/`query` 透传给远程组件 |
+
+## API 职责速查
+
+- `remoteComponent(spec, opts?)`：单个远程组件；失败时插件内置中文错误占位（错误码 + 修法 + **重试加载** + **刷新页面重试**）。
+- `useLoadRemote(spec)`：hook 形态的模块加载（`data/error/loading/reload`），适合普通 TS 模块。
+- `createReactHostPages(...)` + `component(spec)`：页面表驱动的联邦页面。
+
+## 生产构建与部署
+
+```bash
+npm run build        # dist/
+```
+
+部署在站点根 `/`（Nginx SPA fallback 见[组合说明](../README.md#生产构建与最小-nginx-部署)）；深链刷新由 fallback + 插件路由解析恢复。
+
+## 恢复操作（故障演练）
+
+停掉 react-remote → 刷新宿主进入远程页面 → 默认错误占位出现 → 重启 react-remote → 点「重试加载」同页恢复；静态子依赖曾失败等场景点「刷新页面重试」整页恢复。
+
+## HMR（5.2.0 起）
+
+react-remote 的组件修改（文本/样式/Hooks 结构不变）自动热更新到本宿主正在显示的页面并**保留组件本地状态**（插件保证全页单一 react-refresh 实例）；普通 TS 模块修改自动传播到引用它的组件边界；不兼容改动按框架标准重新挂载/整页刷新。

package/examples/react/host/fulgurjs.config.ts

@@ -0,0 +1,31 @@
+import type { FederationOptions, PageRouteLike } from '@fulgurjs/federation'
+
+/**
+ * 宿主端联邦配置（唯一需要维护的联邦声明文件）。
+ * - remotes：改远程地址只动这里；dev 与生产可以分别指定。
+ * - hostPages：页面表 + 路由前缀归属，浏览器侧 createReactHostPages 与 CLI check-pages 共用。
+ */
+export default {
+  name: 'react-host',
+  remotes: {
+    'react-remote': {
+      dev: 'http://localhost:5203',
+      prod: '/react-remote',
+    },
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+} satisfies FederationOptions
+
+/** 页面表：URL 路由 → 远程 expose 的映射（spec = 远程名 + exposes 键） */
+export const pages: PageRouteLike[] = [
+  { route: '/remote/home', spec: 'pages/HomePage', name: 'RemoteHome', title: '远程首页' },
+  { route: '/remote/detail/:id', spec: 'pages/DetailPage', name: 'RemoteDetail', title: '远程详情' },
+]
+
+/** 路由前缀 → 远程归属（最长前缀匹配） */
+export const remotePrefixes: Record<string, string> = {
+  '/remote': 'react-remote',
+}

package/examples/{react-remote → react/host}/index.html

@@ -2,7 +2,8 @@
 <html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
-    <title>react-remote（fulgurjs example）</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>react-host（fulgurjs 演示宿主）</title>
   </head>
   <body>
     <div id="root"></div>