@fulgurjs/federation 5.1.3 → 5.2.0

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>