@fulgurjs/federation 5.0.3 → 5.1.0

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

@@ -0,0 +1,66 @@
+/**
+ * react-host：一个文件看清 React 宿主的联邦用法。
+ * ① 每个应用根目录一份 fulgurjs.config.ts（纯数据）；vite.config.ts 调 federation(fulgurjsConfig)
+ * ② React 应用统一从 '@fulgurjs/federation/react' 导入（通用运行时 + React 适配 API）
+ * ③ remoteComponent 工厂放模块顶层（首次渲染才加载）；页面用 createReactHostPages + component(spec)
+ */
+import { Link, Route, Routes, useParams, useSearchParams } from 'react-router-dom'
+import {
+  createReactHostPages,
+  remoteComponent,
+  remoteSchema,
+  useLoadRemote,
+} from '@fulgurjs/federation/react'
+import { pages, remotePrefixes } from './federation/pages.data'
+
+// 页面表（纯数据 + dev schema；R1–R5 校验与 Vue 完全一致）
+const hp = createReactHostPages({ pages, remotePrefixes, schema: remoteSchema })
+
+// 普通远程组件：模块顶层创建，不能在 render 内重复调用工厂
+const RemoteButton = remoteComponent<{ label: string; onClick?: () => void }>('remote-react/Button', {
+  fallback: <p>正在加载远程按钮…</p>,
+})
+
+// 页面组件：与 Vue 相同动词 component(spec)；路由层用 element 渲染
+const RemoteHome = hp.component('remote-react/pages/home')
+const RemoteDetail = hp.component<{ id: string; tab?: string }>('remote-react/pages/detail')
+
+/** 普通远程模块：useLoadRemote（data/error/loading/reload；错误无默认占位，由宿主决定 UI） */
+function UtilsPanel() {
+  type Utils = { formatMoney(v: number, currency?: string): string }
+  const { data, error, loading, reload } = useLoadRemote<Utils>('remote-react/utils')
+  if (loading) return <p>utils 加载中…</p>
+  if (error) return <button onClick={() => void reload()}>utils 加载失败，重试</button>
+  return (
+    <p>
+      12.5 → {data?.formatMoney(12.5)}（<button onClick={() => void reload()}>reload</button>）
+    </p>
+  )
+}
+
+function DetailRoute() {
+  const { id } = useParams()
+  const [sp] = useSearchParams()
+  return <RemoteDetail id={id ?? ''} tab={sp.get('tab') ?? undefined} />
+}
+
+export default function App() {
+  return (
+    <div style={{ fontFamily: 'sans-serif', padding: 16 }}>
+      <h1>react-host（fulgurjs example）</h1>
+      <nav>
+        <Link to="/">首页</Link> · <Link to="/remote-react/home">远程首页</Link> ·{' '}
+        <Link to="/remote-react/detail/42?tab=basic">远程参数页</Link>
+      </nav>
+      <Routes>
+        <Route path="/" element={<main>
+          <p>宿主首页（远程组件按需加载）</p>
+          <RemoteButton label="远程按钮" onClick={() => console.log('clicked')} />
+          <UtilsPanel />
+        </main>} />
+        <Route path="/remote-react/home" element={<RemoteHome />} />
+        <Route path="/remote-react/detail/:id" element={<DetailRoute />} />
+      </Routes>
+    </div>
+  )
+}

package/examples/react-host/src/federation/pages.data.ts

@@ -0,0 +1,19 @@
+/**
+ * 页面表数据（纯数据：不 import React/路由库/浏览器对象——CLI 与浏览器适配器共用）。
+ * spec 缺省推导 = 去首段（远程前缀）+ 剥 :参数 段；带参路由建议显式 spec。
+ */
+export interface PageRecord {
+  route: string
+  spec?: string
+  name?: string
+  title?: string
+}
+
+export const pages: PageRecord[] = [
+  { route: '/remote-react/home', spec: 'pages/home', name: 'RemoteHome' },
+  { route: '/remote-react/detail/:id', spec: 'pages/detail', name: 'RemoteDetail' },
+]
+
+export const remotePrefixes: Record<string, string> = {
+  '/remote-react': 'remote-react',
+}

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

@@ -0,0 +1,8 @@
+import { createElement, StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  createElement(StrictMode, null, createElement(BrowserRouter, null, createElement(App))),
+)

package/examples/react-host/tsconfig.json

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

package/examples/react-host/vite.config.ts

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

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

@@ -0,0 +1,17 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+export default {
+  name: 'remote-react',
+  exposes: {
+    './Button': './src/Button.tsx',
+    './utils': './src/utils.ts',
+    './pages/home': './src/pages/Home.tsx',
+    './pages/detail': './src/pages/Detail.tsx',
+  },
+  // 有初始化需求才添加（应用级 setup 一次 + 会话级 onSession 按宿主 sessionKey 去重）：
+  // setup: './src/fulgurjs/setup.ts',
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+} satisfies FederationOptions

package/examples/react-remote/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <title>react-remote（fulgurjs example）</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/react-remote/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "fulgurjs-example-react-remote",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5203 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5203 --strictPort"
+  },
+  "dependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@fulgurjs/federation": "^5.1.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "typescript": "^5.8.0",
+    "vite": "^6.3.5"
+  }
+}

package/examples/react-remote/src/Button.tsx

@@ -0,0 +1,15 @@
+import { useState } from 'react'
+
+export interface ButtonProps {
+  label: string
+  onClick?: () => void
+}
+
+export default function Button({ label, onClick }: ButtonProps) {
+  const [count, setCount] = useState(0)
+  return (
+    <button type="button" onClick={() => { setCount((c) => c + 1); onClick?.() }}>
+      {label}：已点击 {count} 次
+    </button>
+  )
+}

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

@@ -0,0 +1,6 @@
+import { createElement } from 'react'
+import { createRoot } from 'react-dom/client'
+
+createRoot(document.getElementById('root')!).render(
+  createElement('p', null, 'react-remote 独立运行（联邦消费请从 react-host 访问）'),
+)

package/examples/react-remote/src/pages/Detail.tsx

@@ -0,0 +1,10 @@
+/** 参数页：宿主路由的 params/query 以 props 传入（id 必填） */
+export default function Detail({ id, tab }: { id: string; tab?: string }) {
+  return (
+    <section>
+      <h2>remote-react / Detail</h2>
+      <p>id: {id}</p>
+      <p>tab: {tab ?? '(none)'}</p>
+    </section>
+  )
+}

package/examples/react-remote/src/pages/Home.tsx

@@ -0,0 +1,14 @@
+import { useEffect, useState } from 'react'
+
+export default function Home() {
+  const [now, setNow] = useState('')
+  useEffect(() => {
+    setNow(new Date().toISOString().slice(0, 19))
+  }, [])
+  return (
+    <section>
+      <h2>remote-react / Home</h2>
+      <p>mounted at {now}</p>
+    </section>
+  )
+}

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

@@ -0,0 +1,3 @@
+export function formatMoney(value: number, currency = '¥'): string {
+  return `${currency}${value.toFixed(2)}`
+}

package/examples/react-remote/tsconfig.json

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulgurjs/federation",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "type": "module",
   "description": "Vite Module Federation with full Webpack MF parity. Dev & production, no compromise.",
   "license": "MIT",
@@ -17,6 +17,10 @@
       "types": "./dist/runtime-entry.d.ts",
       "import": "./dist/runtime-entry.js"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
     "./package.json": "./package.json",
     "./internal/context.js": {
       "types": "./dist/context.d.ts",
@@ -32,18 +36,27 @@
       "types": "./dist/vue-adapter.d.ts",
       "import": "./dist/vue-adapter.js",
       "require": "./dist/vue-adapter.cjs"
+    },
+    "./internal/react-adapter.js": {
+      "types": "./dist/react-adapter.d.ts",
+      "import": "./dist/react-adapter.js",
+      "require": "./dist/react-adapter.cjs"
     }
   },
   "typesVersions": {
     "*": {
       "runtime": [
         "dist/runtime-entry.d.ts"
+      ],
+      "react": [
+        "dist/react.d.ts"
       ]
     }
   },
   "files": [
     "dist",
     "README.md",
+    "README.en.md",
     "LICENSE",
     "CHANGELOG.md",
     "DESIGN.md",
@@ -54,7 +67,7 @@
     "docs/P5-vite7-8兼容矩阵.md"
   ],
   "scripts": {
-    "build": "cp ../../README.md README.md && mkdir -p docs && cp ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && rm -rf examples && cp -r ../../examples examples && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/vue-adapter.ts src/context.ts --format esm,cjs --dts --external vite --target node18 --clean && tsup src/runtime-entry.ts --format esm --dts --external vite,vue --target node18 && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime-entry.mjs && node scripts/check-gzip.mjs && node scripts/check-manual-codes.mjs",
+    "build": "cp ../../README.md README.md && cp ../../README.en.md README.en.md && mkdir -p docs && cp ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && rm -rf examples && cp -r ../../examples examples && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/vue-adapter.ts src/react-adapter.ts src/context.ts --format esm,cjs --dts --external vite --target node18 --clean && tsup src/runtime-entry.ts --format esm --dts --external vite,vue --target node18 && tsup src/react.ts --format esm --dts --external vite,react --target node18 && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime-entry.mjs && node scripts/check-gzip.mjs && node scripts/check-manual-codes.mjs",
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
@@ -66,8 +79,14 @@
     "magic-string": "^0.30.17"
   },
   "devDependencies": {
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/react": "16.3.3",
     "@types/node": "^24.0.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "jsdom": "^24.0.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.0",
     "vitest": "^3.1.0",
@@ -75,7 +94,9 @@
   },
   "peerDependencies": {
     "vite": ">=5.1.0",
-    "vue": ">=3.2.0"
+    "vue": ">=3.2.0",
+    "react": ">=18.0.0 <20",
+    "react-dom": ">=18.0.0 <20"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -109,6 +130,12 @@
   "peerDependenciesMeta": {
     "vue": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   }
 }