@fulgurjs/federation 5.1.4 → 5.2.1

package/examples/vue/host/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "fulgurjs-demo-vue-host",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5214 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5214 --strictPort"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "5.2.0",
+    "vue": "^3.5.13",
+    "vue-router": "^4.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "typescript": "^5.8.0",
+    "vite": "^6.3.5"
+  }
+}

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

@@ -0,0 +1,12 @@
+<template>
+  <div style="font-family: sans-serif; padding: 16px; max-width: 860px">
+    <h1>vue-host（fulgurjs 联邦宿主）</h1>
+    <nav style="display: flex; gap: 16px; margin-bottom: 16px">
+      <RouterLink to="/">首页</RouterLink>
+      <RouterLink to="/remote/home">远程首页</RouterLink>
+      <RouterLink to="/remote/detail/7?tab=basic">远程详情（id=7）</RouterLink>
+      <RouterLink to="/utils-demo">TS 模块调用</RouterLink>
+    </nav>
+    <RouterView />
+  </div>
+</template>

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

@@ -0,0 +1,44 @@
+import { createApp, h } from 'vue'
+import { createRouter, createWebHistory, useRoute } from 'vue-router'
+import { createHostPages } from '@fulgurjs/federation/runtime'
+import App from './App.vue'
+import HomePage from './pages/HomePage.vue'
+import UtilsDemo from './pages/UtilsDemo.vue'
+import { pages, remotePrefixes } from '../fulgurjs.config.ts'
+
+// 页面适配器：URL 解析、最长前缀远程归属、异步组件缓存、
+// 加载/错误占位（含「重试加载 / 刷新页面重试」）全部由插件完成。
+const hostPages = createHostPages({
+  pages,
+  remotePrefixes,
+})
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: HomePage },
+    { path: '/utils-demo', component: UtilsDemo },
+    {
+      // 远程页面：spec 经 hostPages.component(spec) 取异步组件（spec = 远程名 + exposes 键）；
+      // route.params + route.query 作为 props 透传给远程页面组件
+      path: '/remote/home',
+      component: { render: () => h(hostPages.component('vue-remote/pages/HomePage')) },
+    },
+    {
+      path: '/remote/detail/:id',
+      // params + query 全量透传给远程页面组件（响应式：路由变化即重渲染）
+      component: {
+        setup() {
+          const route = useRoute()
+          return () =>
+            h(hostPages.component('vue-remote/pages/DetailPage'), {
+              id: route.params.id as string,
+              tab: (route.query.tab as string | undefined) ?? undefined,
+            })
+        },
+      },
+    },
+  ],
+})
+
+createApp(App).use(router).mount('#app')

package/examples/vue/host/src/pages/HomePage.vue

@@ -0,0 +1,16 @@
+<template>
+  <div>
+    <h2>宿主首页</h2>
+    <p>下面的按钮来自 vue-remote（<code>./ClickButton</code> expose）。
+      仅在进入本页时按需加载——首页不会批量预取未访问的远程页面。</p>
+    <RemoteButton />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { remoteComponent } from '@fulgurjs/federation/runtime'
+
+// remoteComponent：首次渲染才真正加载远程模块；失败时插件呈现默认错误占位
+// （含「重试加载 / 刷新页面重试」），无需自己实现错误组件。
+const RemoteButton = remoteComponent('vue-remote/ClickButton')
+</script>

package/examples/vue/host/src/pages/UtilsDemo.vue

@@ -0,0 +1,45 @@
+<template>
+  <div>
+    <h2>普通 TS 模块调用</h2>
+    <p>调用 vue-remote 暴露的 <code>./utils</code> 模块（loadRemote 返回模块命名空间，显式调用其导出）：</p>
+    <p v-if="error" data-testid="demo-utils-error" style="color: #c45656">调用失败：{{ error }}</p>
+    <ul v-else-if="result" data-testid="demo-utils-result">
+      <li>sumNumbers(2, 3, 7) = {{ result.sum }}</li>
+      <li>DEMO_ANSWER = {{ result.answer }}</li>
+      <li>formatPrice(12.5) = {{ result.price }}</li>
+    </ul>
+    <p v-else>加载中…</p>
+    <button data-testid="demo-utils-reload" @click="load">重新调用</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import { loadRemote } from '@fulgurjs/federation/runtime'
+
+// 普通 TS 模块同样走 loadRemote：拿到命名空间后像本地模块一样调用
+interface RemoteUtils {
+  DEMO_ANSWER: number
+  sumNumbers: (...numbers: number[]) => number
+  formatPrice: (yuan: number) => string
+}
+
+const result = ref<{ sum: number; answer: number; price: string } | null>(null)
+const error = ref('')
+
+async function load(): Promise<void> {
+  error.value = ''
+  try {
+    const utils = await loadRemote<RemoteUtils>('vue-remote/utils')
+    result.value = {
+      sum: utils.sumNumbers(2, 3, 7),
+      answer: utils.DEMO_ANSWER,
+      price: utils.formatPrice(12.5),
+    }
+  } catch (e) {
+    error.value = String((e as Error)?.message ?? e)
+  }
+}
+
+onMounted(load)
+</script>

package/examples/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/vue/host/vite.config.ts

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

package/examples/vue/remote/README.md

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

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

@@ -0,0 +1,20 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * 远程端联邦配置（唯一需要维护的联邦声明文件）。
+ * exposes：宿主将按这里的键加载模块；改键名时宿主页面表/引用需同步。
+ */
+export default {
+  name: 'vue-remote',
+  // 生产构建的容器入口文件名（部署后宿主 prod 地址指向它所在目录）
+  filename: 'fulgurjs-remoteEntry.js',
+  exposes: {
+    './ClickButton': './src/exposes/ClickButton.vue',
+    './utils': './src/exposes/utils.ts',
+    './pages/HomePage': './src/exposes/pages/HomePage.vue',
+    './pages/DetailPage': './src/exposes/pages/DetailPage.vue',
+  },
+  shared: {
+    vue: { singleton: true, requiredVersion: '^3.4.0' },
+  },
+} satisfies FederationOptions

package/examples/vue/remote/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-remote（fulgurjs 演示远程）</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>