@fulgurjs/federation 5.1.3 → 5.2.0

package/examples/react/remote/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "fulgurjs-demo-react-remote",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5203 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5203 --strictPort"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "file:../../../../work/fulgurjs-federation-5.2.0.tgz",
+    "react": "^19.1.0",
+    "react-dom": "^19.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/remote/src/App.tsx

@@ -0,0 +1,16 @@
+import ClickButton from './exposes/ClickButton'
+
+/** 独立运行壳：联邦消费方按 exposes 加载下列模块 */
+export default function App() {
+  return (
+    <div style={{ fontFamily: 'sans-serif', padding: 16 }}>
+      <h1>react-remote 独立运行</h1>
+      <ul>
+        <li>./ClickButton —— 可点击计数按钮组件</li>
+        <li>./utils —— 普通 TS 工具模块</li>
+        <li>./pages/HomePage / ./pages/DetailPage —— 联邦页面</li>
+      </ul>
+      <ClickButton />
+    </div>
+  )
+}

package/examples/react/remote/src/exposes/ClickButton.tsx

@@ -0,0 +1,15 @@
+import { useState } from 'react'
+
+/** 可点击计数按钮：本地 state 保存在远程组件内部（宿主消费时运行在宿主页面的 React 上） */
+export default function ClickButton() {
+  const [count, setCount] = useState(0)
+  return (
+    <button
+      data-testid="demo-remote-button"
+      style={{ padding: '8px 16px', border: 'none', borderRadius: 6, background: '#1677ff', color: '#fff', cursor: 'pointer' }}
+      onClick={() => setCount((c) => c + 1)}
+    >
+      远程按钮（点击了 {count} 次）
+    </button>
+  )
+}

package/examples/react/remote/src/exposes/pages/DetailPage.tsx

@@ -0,0 +1,10 @@
+/** 联邦参数页：宿主路由的 params + query 作为 props 传入 */
+export default function DetailPage({ id, tab }: { id?: string; tab?: string }) {
+  return (
+    <div data-testid="demo-remote-detail">
+      <h3>react-remote / 详情页</h3>
+      <p data-testid="demo-detail-id">路由参数 id：{id ?? '(无)'}</p>
+      <p data-testid="demo-detail-tab">query 参数 tab：{tab ?? '(无)'}</p>
+    </div>
+  )
+}

package/examples/react/remote/src/exposes/pages/HomePage.tsx

@@ -0,0 +1,12 @@
+import ClickButton from '../ClickButton'
+
+/** 联邦页面：渲染在宿主的路由出口内 */
+export default function HomePage() {
+  return (
+    <div data-testid="demo-remote-home">
+      <h3>react-remote / 首页</h3>
+      <p>这是由 react-remote 暴露的联邦页面。</p>
+      <ClickButton />
+    </div>
+  )
+}

package/examples/react/remote/src/exposes/utils.ts

@@ -0,0 +1,10 @@
+/** 普通 TS 工具模块：演示跨应用函数/常量消费（不含任何组件） */
+export const DEMO_ANSWER = 42
+
+export function sumNumbers(...numbers: number[]): number {
+  return numbers.reduce((acc, n) => acc + n, 0)
+}
+
+export function formatPrice(yuan: number): string {
+  return `¥${yuan.toFixed(2)}`
+}

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

@@ -0,0 +1,11 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+// 独立运行入口：单独开发/调试远程自身时使用。
+// 被宿主消费时走的是 fulgurjs-remoteEntry.js 容器入口，与本文件无关。
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/examples/{react-host → react/remote}/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", "src/fulgurjs/types", "fulgurjs.config.ts", "vite.config.ts"]
+  "include": ["src", "fulgurjs.config.ts", "vite.config.ts"]
 }

package/examples/{react-host → react/remote}/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/vue/README.md

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

package/examples/vue/host/README.md

@@ -0,0 +1,50 @@
+# vue-host —— Vue 宿主（fulgurjs 联邦演示）
+
+> **角色：Vue 宿主（消费方）。** 消费 [`../remote/`](../remote/)（vue-remote，端口 5213）暴露的组件、TS 模块与联邦页面；本应用自身不暴露任何模块。
+
+## 从干净拷贝运行
+
+前置：Node ≥ 20.19 与 npm（与本仓库示例验证版本一致即可）。
+
+```bash
+# 先启动远程（另一终端）：见 ../remote/README.md
+cd vue-host          # 把本目录复制到任意位置后进入
+npm install
+npm run dev          # http://localhost:5214
+```
+
+成功画面：导航条含「首页 / 远程首页 / 远程详情 / TS 模块调用」；「远程首页」出现 vue-remote 的标题与可点击计数按钮。
+
+## 目录与关键配置
+
+| 文件 | 职责 |
+| --- | --- |
+| `fulgurjs.config.ts` | **联邦唯一声明**：remotes 地址（dev/prod）、页面表 `pages`、前缀归属 `remotePrefixes`。改远程地址只动这里 |
+| `vite.config.ts` | 标准 Vite 配置，`federation(fulgurjsConfig)` 挂载插件 |
+| `src/main.ts` | 路由 + `createHostPages({ pages, remotePrefixes })`；远程页面用 `hostPages.component('<远程名>/<expose 键>')` |
+| `src/pages/HomePage.vue` | `remoteComponent('vue-remote/ClickButton')` 消费单个远程组件 |
+| `src/pages/UtilsDemo.vue` | `loadRemote('vue-remote/utils')` 调用普通 TS 模块 |
+
+## API 职责速查
+
+- `remoteComponent(spec)`：单个远程组件；首次渲染才加载；失败时插件内置中文错误占位（错误码 + 修法 + **重试加载** + **刷新页面重试**）。
+- `createHostPages({ pages, remotePrefixes })`：页面表驱动；`component(spec)` 返回异步页面组件（同 spec 复用）；加载/错误占位由插件提供。
+- `loadRemote(spec)`：加载任意 expose（组件或纯 TS 模块），返回模块命名空间。
+
+## 生产构建与部署
+
+```bash
+npm run build        # dist/
+```
+
+部署在站点根 `/`（Nginx SPA fallback 见 [组合说明](../README.md#生产构建与最小-nginx-部署)）。深链 `/remote/detail/7?tab=basic` 刷新后由 fallback 回退 index.html、插件路由解析恢复同一页面。
+
+## 恢复操作（故障演练）
+
+1. 停掉 vue-remote（Ctrl-C 远程终端）。
+2. 刷新宿主页面并进入任一远程页面 → 插件默认错误占位（远程组件加载失败 + 错误码）。
+3. 重启 vue-remote → 点占位上的「重试加载」同页恢复；若浏览器已缓存失败的模块（如远程静态子依赖曾失败），点「刷新页面重试」整页恢复（保留当前地址）。
+
+## HMR
+
+vue-remote 的组件/TS 模块修改会自动热更新到本宿主正在显示的页面（无需手动刷新）；不兼容改动按 Vite/Vue 标准触发 full-reload。

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

@@ -0,0 +1,30 @@
+import type { FederationOptions, PageRouteLike } from '@fulgurjs/federation'
+
+/**
+ * 宿主端联邦配置（唯一需要维护的联邦声明文件）。
+ * - remotes：改远程地址只动这里；dev 与生产可以分别指定。
+ * - hostPages：页面表 + 路由前缀归属，浏览器侧 createHostPages 与 CLI check-pages 共用。
+ */
+export default {
+  name: 'vue-host',
+  remotes: {
+    'vue-remote': {
+      dev: 'http://localhost:5213',
+      prod: '/vue-remote',
+    },
+  },
+  shared: {
+    vue: { 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': 'vue-remote',
+}

package/examples/vue/host/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>vue-host（fulgurjs 演示宿主）</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>