@fulgurjs/federation 5.2.4 → 5.3.0

package/examples/bridge/react-remote/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "fulgurjs-demo-bridge-react-remote",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5303 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5303 --strictPort"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "5.3.0",
+    "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/bridge/react-remote/src/bridge.tsx

@@ -0,0 +1,66 @@
+/**
+ * React 子应用桥接契约（./bridge expose 的默认导出，任务书 §3.3）。
+ *
+ * defineBridgeApp 工厂接收 props 快照、返回 ReactElement；
+ * createRoot/首次提交探测/unmount 由契约实现负责（react-dom/client 在实际 mount 时按需加载）。
+ */
+import { useEffect, useState } from 'react'
+import { MemoryRouter, Route, Routes, useLocation, useNavigate } from 'react-router-dom'
+import { defineBridgeApp } from '@fulgurjs/federation/react'
+
+/** 挂载即回调（宿主验证函数引用跨 root 传递） */
+function OnReady({ onReady }: { onReady?: () => void }) {
+  useEffect(() => {
+    onReady?.()
+    // 挂载回调只触发一次
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+  return null
+}
+
+function Counter() {
+  const [n, setN] = useState(0)
+  return (
+    <button data-testid="demo-react-counter" onClick={() => setN(n + 1)}>
+      本地状态：{n}
+    </button>
+  )
+}
+
+function Shell(props: Record<string, unknown>) {
+  const location = useLocation()
+  const navigate = useNavigate()
+  return (
+    <div style={{ border: '1px solid #61dafb', borderRadius: 8, padding: 12, fontFamily: 'sans-serif' }}>
+      <p style={{ margin: '0 0 6px', fontWeight: 600, color: '#0b7285' }}>React 子应用</p>
+      <p data-testid="demo-react-props" style={{ margin: '0 0 6px' }}>
+        {`appProps.label = ${(props as any).label || '（未传）'}`}
+      </p>
+      <p data-testid="demo-react-route" style={{ margin: '0 0 8px' }}>{`memory 路由：${location.pathname}`}</p>
+      <nav style={{ marginBottom: 8 }}>
+        <button style={{ marginRight: 8 }} onClick={() => navigate('/')}>首页</button>
+        <button onClick={() => navigate('/about')}>关于</button>
+      </nav>
+      <Counter />
+      <Routes>
+        <Route path="/" element={<p data-testid="demo-react-page">页面：首页</p>} />
+        <Route path="/about" element={<p data-testid="demo-react-page">页面：关于</p>} />
+      </Routes>
+    </div>
+  )
+}
+
+export function App() {
+  return (
+    <MemoryRouter>
+      <Shell />
+    </MemoryRouter>
+  )
+}
+
+export default defineBridgeApp((props) => (
+  <MemoryRouter>
+    <OnReady onReady={(props as any).onReady} />
+    <Shell {...props} />
+  </MemoryRouter>
+))

package/examples/bridge/react-remote/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>
+  export default component
+}

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

@@ -0,0 +1,7 @@
+import { createElement } from 'react'
+import { createRoot } from 'react-dom/client'
+import { App } from './bridge'
+
+// 独立运行入口：单独开发/调试子应用自身时使用。
+// 被桥接宿主消费时走 fulgurjs-remoteEntry.js 容器入口与 ./bridge 契约，与本文件无关。
+createRoot(document.getElementById('root')!).render(createElement(App))

package/examples/bridge/react-remote/tsconfig.json

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

package/examples/bridge/react-remote/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { federation } from '@fulgurjs/federation'
+import fulgurjsConfig from './fulgurjs.config'
+
+export default defineConfig(({ command }) => ({
+  base: command === 'build' ? '/bridge-react-remote/' : undefined,
+  plugins: [react(), federation(fulgurjsConfig)],
+}))

package/examples/bridge/vue-host/README.md

@@ -0,0 +1,24 @@
+# bridge-vue-host — Vue 宿主 × React 桥接子应用示例
+
+`@fulgurjs/federation` 跨框架桥接的 **Vue 3 宿主**侧示例：用 `createVueBridgeApp`（`@fulgurjs/federation/bridge/vue`）把 `bridge-react-remote/bridge` 作为受控组件挂载。
+
+## 运行
+
+```bash
+# 1) 先启动 React 子应用（5303）
+cd ../react-remote && npm install && npm run dev
+
+# 2) 再启动本宿主（5314）
+npm install
+npm run dev        # http://localhost:5314
+npm run build      # 产出 /bridge-vue-host/ 子路径产物
+```
+
+## 关键点（对应 README §8.2）
+
+- **双框架安装合同**：本宿主同时安装 `vue` + `react` + `react-dom`，shared 三键全部 `singleton: true`。
+- **入口选择**：`@fulgurjs/federation/bridge/vue` 只携带 Vue 宿主适配器——dev 原生 ESM 与生产构建都不会加载 React 宿主适配代码（聚合入口 `/bridge` 会同时执行两者，仅兼容保留）。
+- **`sessionKey`**：受控登录代次（非业务 props）。置 `null` = 登出态（立即卸载、不再请求）；换账号走「null → `clearAppContext()` → 新代次」顺序，保证 A 的 context 字段零残留。
+- **`getContext`**：同步纯 getter（`src/host-session.ts`），桥接层校验其快照的 `sessionKey` 后才代写 AppContext。
+- **`appProps`**：挂载时浅拷贝快照；函数引用（`onReady`）保留原引用；换顶层引用不重挂，需要重置时用 `:key`。
+- 错误占位默认内置中文诊断 +「重试加载 / 刷新页面重试」；可用 `errorComponent` 完全接管。

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

@@ -0,0 +1,22 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * Vue 桥接宿主联邦配置。
+ * 桥接模式使用合同（README §8.2 / 任务书 §3.5）：宿主必须同时安装 vue + react + react-dom，
+ * 并把两套框架 shared 全部 singleton——缺 singleton 是使用违例（双实例症状见 README 故障表）。
+ * 推荐入口：/bridge/vue（只携带 Vue 宿主适配器，dev 与生产都不加载 React 宿主适配代码）。
+ */
+export default {
+  name: 'bridge-vue-host',
+  remotes: {
+    'bridge-react-remote': {
+      dev: 'http://localhost:5303',
+      prod: '/bridge-react-remote',
+    },
+  },
+  shared: {
+    vue: { singleton: true },
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+} satisfies FederationOptions

package/examples/bridge/vue-host/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <title>bridge-vue-host（Vue 宿主 × React 桥接子应用）</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>