@fulgurjs/federation 5.2.5 → 5.3.0

package/examples/bridge/vue-host/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "fulgurjs-demo-bridge-vue-host",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5314 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5314 --strictPort"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "5.3.0",
+    "vue": "^3.5.13",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "typescript": "^5.8.0",
+    "vite": "^6.3.5"
+  }
+}

package/examples/bridge/vue-host/src/App.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+/**
+ * Vue 宿主 × React 桥接子应用（examples 版，含全部关键语义注释）。
+ * 先启动 examples/bridge/react-remote（5303）再启动本宿主。
+ */
+import { ref } from 'vue'
+import { clearAppContext } from '@fulgurjs/federation/runtime'
+import { createVueBridgeApp } from '@fulgurjs/federation/bridge/vue'
+import { getLatestHostContext, login, logout } from './host-session'
+
+// 工厂选项：retries 透传 loadRemote；getContext 在每次实际加载前同步取最新快照
+const RemoteReactApp = createVueBridgeApp('bridge-react-remote/bridge', {
+  retries: 1,
+  getContext: () => getLatestHostContext(),
+})
+
+// sessionKey 是桥接控制参数（非敏感登录代次 ID），不是业务 props
+const sessionKey = ref<string | null>('login-1-alice')
+const userName = ref('Alice')
+const label = ref('来自 Vue 宿主')
+const readyCount = ref(0)
+
+function handleReady(): void {
+  readyCount.value++
+}
+
+function nextFrame(): Promise<void> {
+  return new Promise((r) => requestAnimationFrame(() => r(null)))
+}
+
+// 换账号推荐顺序（§4.3）：受控 prop 置 null → 等卸载 → clearAppContext 清 A 残留
+// → 登录 B → 更新受控 prop 触发新代次（getContext + loadRemote + onSession 全走一遍）
+async function switchUser(): Promise<void> {
+  sessionKey.value = null
+  await nextFrame()
+  clearAppContext()
+  login('login-2-bob', { id: 2, name: 'Bob' })
+  userName.value = 'Bob'
+  sessionKey.value = 'login-2-bob'
+}
+
+// 登出：prop 置 null → 桥接立即卸载且不再请求 → 宿主清理全局 context
+async function doLogout(): Promise<void> {
+  sessionKey.value = null
+  await nextFrame()
+  clearAppContext()
+  logout()
+  userName.value = ''
+}
+</script>
+
+<template>
+  <div style="font-family: sans-serif; padding: 16px; max-width: 720px">
+    <h1>Vue 宿主 × React 子应用（@fulgurjs/federation/bridge/vue）</h1>
+    <p data-testid="demo-session">会话：{{ sessionKey ?? '未登录' }}（{{ userName || '—' }}）· onReady 次数：{{ readyCount }}</p>
+
+    <p>
+      <button data-testid="demo-switch" @click="switchUser">切换到 Bob（clearAppContext → 重挂）</button>
+      <button data-testid="demo-logout" @click="doLogout">登出（sessionKey → null）</button>
+    </p>
+
+    <!-- 外层元素控制桥接区域外观；appProps 是挂载时浅拷贝快照，换引用不重挂，重挂用 :key -->
+    <section style="margin-top: 12px">
+      <RemoteReactApp
+        :session-key="sessionKey"
+        :app-props="{ label, onReady: handleReady }"
+      />
+    </section>
+  </div>
+</template>

package/examples/bridge/vue-host/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/vue-host/src/host-session.ts

@@ -0,0 +1,29 @@
+/**
+ * 宿主自有会话源（示例实现）：返回「当前登录用户」的完整 AppContext 快照。
+ * 要求（任务书 §4.3）：纯同步、无副作用、不调 provideAppContext、不返回 Promise。
+ * 真实项目里通常读登录 store / token 管理器——只要保持「同步快照 getter」语义即可。
+ */
+export interface HostSession {
+  key: string | null
+  user: { id: number; name: string }
+}
+
+let current: HostSession = { key: 'login-1-alice', user: { id: 1, name: 'Alice' } }
+
+export function getLatestHostContext(): Record<string, unknown> & { sessionKey: string } {
+  if (current.key === null) throw new Error('已登出：此刻不应有桥接代次请求 context')
+  return {
+    sessionKey: current.key,
+    user: current.user,
+    // 取最新 token 用拉取式函数引用，防止快照过期（README §9）
+    getToken: () => `token-for-${current.key}`,
+  }
+}
+
+export function login(key: string, user: { id: number; name: string }): void {
+  current = { key, user }
+}
+
+export function logout(): void {
+  current = { key: null, user: { id: 0, name: '' } }
+}

package/examples/bridge/vue-host/src/main.ts

@@ -0,0 +1,4 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')

package/examples/bridge/vue-host/tsconfig.json

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

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

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

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

@@ -0,0 +1,19 @@
+# bridge-vue-remote — Vue 桥接子应用示例
+
+`@fulgurjs/federation` 跨框架桥接的 **Vue 3 子应用**侧示例：以 `defineBridgeApp`（`@fulgurjs/federation/runtime`）导出 `mount/unmount` 契约，可被 **React 宿主**（配合 `examples/bridge/react-host`）整站挂载。
+
+## 运行
+
+```bash
+npm install
+npm run dev        # http://localhost:5313（独立运行态）
+npm run build      # 产出 /bridge-vue-remote/ 子路径产物
+```
+
+## 关键点
+
+- `src/bridge.ts`：`defineBridgeApp((props) => VueApp)` 工厂——自行装配 memory 路由（vue-router），作为 `./bridge` expose 的默认导出。
+- 子应用只安装并共享 `vue`（+ `vue-router` 为直接依赖），**不安装 React**。
+- `sessionKey`/`getContext` 等会话语义由宿主侧控制，见 `examples/bridge/react-host`。
+
+配套阅读：根目录 README §8.2「跨框架桥接 API — /bridge」。

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

@@ -0,0 +1,16 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * Vue 子应用联邦配置：`./bridge` expose = defineBridgeApp 契约模块（任务书 §3.3）。
+ * 子应用只安装并共享自己的框架（vue），不为桥接安装对方框架。
+ */
+export default {
+  name: 'bridge-vue-remote',
+  filename: 'fulgurjs-remoteEntry.js',
+  exposes: {
+    './bridge': './src/bridge.ts',
+  },
+  shared: {
+    vue: { singleton: true, requiredVersion: '^3.4.0' },
+  },
+} satisfies FederationOptions

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

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