@fulgurjs/federation 5.1.3 → 5.2.0

package/examples/react/host/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "fulgurjs-demo-react-host",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5204 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5204 --strictPort"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "file:../../../../work/fulgurjs-federation-5.2.0.tgz",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router-dom": "^7.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "typescript": "^5.8.0",
+    "vite": "^6.3.5"
+  }
+}

package/examples/react/host/src/App.tsx

@@ -0,0 +1,19 @@
+import { remoteComponent } from '@fulgurjs/federation/react'
+
+// remoteComponent：首次渲染才真正加载远程模块；失败时插件呈现默认错误占位
+// （含「重试加载 / 刷新页面重试」），无需自己实现错误组件。
+const RemoteButton = remoteComponent('react-remote/ClickButton')
+
+/** 宿主首页：演示单个远程组件消费（按需懒加载） */
+export default function App() {
+  return (
+    <div style={{ fontFamily: 'sans-serif', padding: 16 }}>
+      <h2>宿主首页</h2>
+      <p>
+        下面的按钮来自 react-remote（<code>./ClickButton</code> expose）。
+        仅在进入本页时按需加载——首页不会批量预取未访问的远程页面。
+      </p>
+      <RemoteButton />
+    </div>
+  )
+}

package/examples/react/host/src/main.tsx

@@ -0,0 +1,33 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter, Link, Route, Routes, useParams, useSearchParams } from 'react-router-dom'
+import App from './App'
+import UtilsDemo from './pages/UtilsDemo'
+import { RemoteHomePage, RemoteDetailPage } from './remotePages'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <nav style={{ display: 'flex', gap: 16, padding: 16, fontFamily: 'sans-serif' }}>
+        <Link to="/">首页</Link>
+        <Link to="/remote/home">远程首页</Link>
+        <Link to="/remote/detail/7?tab=basic">远程详情（id=7）</Link>
+        <Link to="/utils-demo">TS 模块调用</Link>
+      </nav>
+      <Routes>
+        <Route path="/" element={<App />} />
+        <Route path="/utils-demo" element={<UtilsDemo />} />
+        <Route path="/remote/home" element={<RemoteHomePage />} />
+        {/* 远程参数页：params + query 全量透传给远程页面组件 */}
+        <Route path="/remote/detail/:id" element={<RemoteDetailRoute />} />
+      </Routes>
+    </BrowserRouter>
+  </StrictMode>,
+)
+
+/** 从 react-router 取 params/query 再交给页面适配器组件（适配器与路由库解耦） */
+function RemoteDetailRoute() {
+  const { id } = useParams()
+  const [search] = useSearchParams()
+  return <RemoteDetailPage id={id} tab={search.get('tab') ?? undefined} />
+}

package/examples/react/host/src/pages/UtilsDemo.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react'
+import { useLoadRemote } from '@fulgurjs/federation/react'
+
+interface RemoteUtils {
+  DEMO_ANSWER: number
+  sumNumbers: (...numbers: number[]) => number
+  formatPrice: (yuan: number) => string
+}
+
+/** 普通 TS 模块调用演示：useLoadRemote 返回模块命名空间（loading/error/reload 内置） */
+export default function UtilsDemo(): ReactNode {
+  const { data, error, loading, reload } = useLoadRemote<RemoteUtils>('react-remote/utils')
+  return (
+    <div style={{ fontFamily: 'sans-serif', padding: 16 }}>
+      <h2>普通 TS 模块调用</h2>
+      {error ? (
+        <p data-testid="demo-utils-error" style={{ color: '#c45656' }}>
+          调用失败：{String((error as Error)?.message ?? error)}
+        </p>
+      ) : loading || !data ? (
+        <p>加载中…</p>
+      ) : (
+        <ul data-testid="demo-utils-result">
+          <li>sumNumbers(2, 3, 7) = {data.sumNumbers(2, 3, 7)}</li>
+          <li>DEMO_ANSWER = {data.DEMO_ANSWER}</li>
+          <li>formatPrice(12.5) = {data.formatPrice(12.5)}</li>
+        </ul>
+      )}
+      <button data-testid="demo-utils-reload" onClick={() => void reload()}>重新调用</button>
+    </div>
+  )
+}

package/examples/react/host/src/remotePages.tsx

@@ -0,0 +1,16 @@
+import { createReactHostPages } from '@fulgurjs/federation/react'
+import { pages, remotePrefixes } from '../fulgurjs.config.ts'
+
+// 页面适配器：URL 解析、最长前缀远程归属、异步组件缓存、
+// 加载/错误占位（含「重试加载 / 刷新页面重试」）全部由插件完成。
+// 模块顶层创建一次（不能在组件 render 内调用工厂）。
+const hostPages = createReactHostPages({
+  pages,
+  remotePrefixes,
+})
+
+/** 远程首页组件（spec = 远程名 + exposes 键） */
+export const RemoteHomePage = hostPages.component('react-remote/pages/HomePage')
+
+/** 远程详情组件：宿主路由层把 params/query 作为 props 传入 */
+export const RemoteDetailPage = hostPages.component<{ id?: string; tab?: string }>('react-remote/pages/DetailPage')

package/examples/{react-remote → react/host}/tsconfig.json

@@ -1,14 +1,13 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "jsx": "react-jsx",
     "strict": true,
+    "jsx": "react-jsx",
     "skipLibCheck": true,
     "noEmit": true,
-    "isolatedModules": true
+    "types": ["vite/client"]
   },
   "include": ["src", "fulgurjs.config.ts", "vite.config.ts"]
 }

package/examples/{react-remote → react/host}/vite.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
-import federation from '@fulgurjs/federation'
-import fulgurjsConfig from './fulgurjs.config'
+import { federation } from '@fulgurjs/federation'
+import fulgurjsConfig from './fulgurjs.config.ts'
 
 export default defineConfig({
   plugins: [react(), federation(fulgurjsConfig)],

package/examples/react/remote/README.md

@@ -0,0 +1,47 @@
+# react-remote —— React 远程（fulgurjs 联邦演示）
+
+> **角色：React 远程（被消费方）。** 向 [`../host/`](../host/)（react-host，端口 5204）暴露可点击按钮组件、普通 TS 工具模块、联邦首页与参数详情页；也可独立运行调试。
+
+## 从干净拷贝运行
+
+```bash
+cd react-remote      # 把本目录复制到任意位置后进入
+npm install
+npm run dev          # http://localhost:5203
+```
+
+独立运行画面：`react-remote 独立运行` 页面 + 一枚可点击计数按钮（远程自己的壳；联邦消费走 `fulgurjs-remoteEntry.js` 容器入口，与壳无关）。
+
+## 暴露的模块（exposes）
+
+| expose 键 | 源文件 | 说明 |
+| --- | --- | --- |
+| `./ClickButton` | `src/exposes/ClickButton.tsx` | 可点击计数按钮（useState 本地状态） |
+| `./utils` | `src/exposes/utils.ts` | 普通 TS 模块：`sumNumbers` / `DEMO_ANSWER` / `formatPrice` |
+| `./pages/HomePage` | `src/exposes/pages/HomePage.tsx` | 联邦页面：远程首页 |
+| `./pages/DetailPage` | `src/exposes/pages/DetailPage.tsx` | 联邦页面：详情页（接收宿主路由的 `id` / `tab` props） |
+
+宿主如何调用 `./utils`（宿主侧代码）：
+
+```tsx
+import { useLoadRemote } from '@fulgurjs/federation/react'
+const { data } = useLoadRemote<{ sumNumbers: (...n: number[]) => number }>('react-remote/utils')
+data?.sumNumbers(2, 3, 7) // 12
+```
+
+## 关键配置
+
+- `fulgurjs.config.ts`：**联邦唯一声明**（name = `react-remote`、exposes、shared）。
+- `vite.config.ts`：`federation(fulgurjsConfig)` 挂载插件；端口在 `package.json` 的 `dev` 脚本（5203）。
+
+## 生产构建与部署
+
+```bash
+npm run build        # dist/（含 fulgurjs-remoteEntry.js 与 fulgurjs-manifest.json）
+```
+
+部署到 Nginx 子路径 `/react-remote/`（与宿主 `prod: '/react-remote'` 对应）。完整 Nginx 示例见[组合说明](../README.md#生产构建与最小-nginx-部署)。
+
+## 故障演练（配合宿主）
+
+停掉本 dev server → 宿主远程页面出现插件默认错误占位 → 重启本服务 → 宿主占位上「重试加载」同页恢复，或「刷新页面重试」整页恢复。

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

@@ -0,0 +1,20 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * 远程端联邦配置（唯一需要维护的联邦声明文件）。
+ * exposes：宿主将按这里的键加载模块；改键名时宿主页面表/引用需同步。
+ */
+export default {
+  name: 'react-remote',
+  filename: 'fulgurjs-remoteEntry.js',
+  exposes: {
+    './ClickButton': './src/exposes/ClickButton.tsx',
+    './utils': './src/exposes/utils.ts',
+    './pages/HomePage': './src/exposes/pages/HomePage.tsx',
+    './pages/DetailPage': './src/exposes/pages/DetailPage.tsx',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+} satisfies FederationOptions

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

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