@fulgurjs/federation 4.2.1 → 4.3.1

package/docs//350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -141,17 +141,18 @@ onUnmounted(() => {
 |---|---|---|---|---|
 | 页面保活（多 tab 状态保留） | `keepAlive` | `boolean` | `false` | 页面数据条目（`src/fulgurjs/host/pages.data.ts`） |
 | 页面加载骨架屏 | —（内置，无配置项） | — | delay 200ms 的骨架占位 | 页面工厂内置（`pages.ts`） |
-| 空闲预载 | `PREFETCH_REMOTES`（宿主桥常量） | `string[]` | 全部 remotes 键 | `src/fulgurjs/host/bridge.ts` 顶部 |
+| 空闲预载 | `PREFETCH_REMOTES`（宿主桥常量） | `string[]` | `[]`（关闭整远程预载，按需加载） | `src/fulgurjs/host/bridge.ts` 顶部 |
 | 联邦诊断面板 | —（内置页面） | — | 常驻 | 路由 `/fulgurjs-demo`（prod 为 `/main/fulgurjs-demo`） |
 
 ```ts
 // 保活：按页开启（默认全关——重型组件缓存成本高）
 { route: '/flowable/bpm/task/todo', name: 'BpmTodoTask', title: '待办任务', keepAlive: true }
 
-// 空闲预载三态（bridge.ts）：
-const PREFETCH_REMOTES: string[] = ['mes-bpm', 'mes-lowcode'] // 默认：全部
-const PREFETCH_REMOTES: string[] = ['mes-bpm']                // 部分
-const PREFETCH_REMOTES: string[] = []                         // 关闭
+// 空闲预载三态（bridge.ts）——默认关闭整远程预载（按需加载；四层语义见 README §9.1.3）：
+const PREFETCH_REMOTES: string[] = []                         // 默认：关闭（首访联邦页只下载该页所需）
+const PREFETCH_REMOTES: string[] = ['mes-bpm']                // 显式预热整个远程（下载完整 expose 清单，不执行）
+// 单页预取（推荐：只预取明确下一步页面，低优先级只下载不执行）
+// idle(() => preloadRemote('mes-bpm/pages/bpm/task/todo', { mode: 'prefetch' }))
 ```
 
 边界：保活缓存上限 max=8（LRU）；骨架屏 delay 200ms 防闪、失败走内置错误占位（错误码+根因+修法）；预载失败 MFU-007（fulgurjs:error 事件，不阻断业务）；保活页的 window 级监听/定时器按「三D 清理清单」处理。

package/examples/README.md

@@ -0,0 +1,22 @@
+# examples — 可复制的单项目配置样例
+
+每个目录是一个**独立项目**的 `fulgurjs.config.ts`（4.2.0 单项目契约：默认导出直接可传给 `federation()`）：
+
+- [`remote-a/fulgurjs.config.ts`](./remote-a/fulgurjs.config.ts) — 远程应用：exposes / setup / shared
+- [`host/fulgurjs.config.ts`](./host/fulgurjs.config.ts) — 宿主应用：remotes 消费地址 + 可选 `hostPages` 页面核对数据（仅供 CLI）
+
+复制方式：把对应文件整份复制到**你自己的项目根目录**（两个项目不共享配置文件、不共享父目录配置），再在各自 `vite.config.ts` 的 plugins 里加一次 `federation(fulgurjsConfig)`：
+
+```ts
+import federation from '@fulgurjs/federation'
+import fulgurjsConfig from './fulgurjs.config'
+
+export default defineConfig({
+  plugins: [
+    // ...原有插件,
+    federation(fulgurjsConfig),
+  ],
+})
+```
+
+验证：在复制后的项目根目录运行 `npx fulgurjs explain`（纯本地、无网络），应输出本应用的形态摘要与 `federation(fulgurjsConfig)` 接入块。

package/examples/host/fulgurjs.config.ts

@@ -0,0 +1,26 @@
+// host/fulgurjs.config.ts —— 宿主应用自己的配置（一项目一份；整文件可复制到你的宿主项目根目录）
+//
+// 宿主只写自己的 name / remotes / shared；页面核对数据以具名导出 hostPages 提供给 CLI。
+// Vite 接入（本项目 vite.config.ts 只需两行联邦相关代码）：
+//   import federation from '@fulgurjs/federation'
+//   import fulgurjsConfig from './fulgurjs.config'
+//   // plugins: [ ...原有插件, federation(fulgurjsConfig) ]
+import type { FederationOptions } from '@fulgurjs/federation'
+
+export default {
+  name: 'host-app',
+  // 消费的远程（键 = import 前缀；dev/prod 地址二段式，单地址字符串也行）
+  remotes: {
+    'remote-a': { dev: 'http://localhost:5174/remote-a', prod: '/remote-a' },
+  },
+  shared: {
+    vue: { singleton: true },
+  },
+} satisfies FederationOptions
+
+// ── 以下仅供 CLI explain/check-pages 读取（不是 federation() 的参数）──
+// 页面数据与运行时 createHostPages 消费同一份纯数据模块（唯一手工维护位置）
+export const hostPages = {
+  remotePrefixes: { '/remote-a/': 'remote-a' },
+  pages: [{ route: '/remote-a/home', name: 'RemoteAHome', title: '首页' }],
+}

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

@@ -0,0 +1,24 @@
+// remote-a/fulgurjs.config.ts —— 远程应用自己的配置（一项目一份；整文件可复制到你的远程项目根目录）
+//
+// Vite 接入（本项目 vite.config.ts 只需两行联邦相关代码）：
+//   import federation from '@fulgurjs/federation'
+//   import fulgurjsConfig from './fulgurjs.config'
+//   // plugins: [ ...原有插件, federation(fulgurjsConfig) ]
+//
+// CLI（纯本地，无网络）：npx fulgurjs explain
+import type { FederationOptions } from '@fulgurjs/federation'
+
+export default {
+  // 联邦容器名（宿主引用它时用这个名；同一页面内唯一）
+  name: 'remote-a',
+  // 对外暴露的模块：'./键' → 相对本项目根的源文件路径
+  exposes: {
+    './pages/remote-a/home': './src/views/Home.vue',
+    './pages/remote-a/detail': './src/views/Detail.vue',
+  },
+  // 可选：远程需要启动期初始化（全局样式/组件/locale）时声明入口文件
+  // setup: './src/fulgurjs/setup.ts',
+  shared: {
+    vue: { singleton: true },
+  },
+} satisfies FederationOptions

package/examples/remote-a/src/views/Detail.vue

@@ -0,0 +1,3 @@
+<template>
+  <div>remote-a detail</div>
+</template>

package/examples/remote-a/src/views/Home.vue

@@ -0,0 +1,3 @@
+<template>
+  <div>remote-a home</div>
+</template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulgurjs/federation",
-  "version": "4.2.1",
+  "version": "4.3.1",
   "type": "module",
   "description": "Vite Module Federation with full Webpack MF parity. Dev & production, no compromise.",
   "license": "MIT",
@@ -75,6 +75,7 @@
   },
   "dependencies": {
     "es-module-lexer": "^1.6.0",
+    "esbuild": "^0.27.0",
     "magic-string": "^0.30.17"
   },
   "devDependencies": {

package/examples/fulgurjs.config.example.ts

@@ -1,33 +0,0 @@
-/**
- * 通用起步样例（4.2.0 单项目契约形态）：一个远程 + 一个宿主各一份配置。
- * 完整字段说明见 `fulgurjs init` 生成的起步模板（fulgurjs init --template fulgurjs.config.ts）。
- */
-import type { FederationOptions } from '@fulgurjs/federation'
-
-// ── remote-a/fulgurjs.config.ts（远程应用自己的配置）──
-export const remoteAConfig = {
-  name: 'remote-a',
-  exposes: {
-    './pages/remote-a/home': './src/views/Home.vue',
-    './pages/remote-a/detail': './src/views/Detail.vue',
-  },
-  shared: { vue: { singleton: true } },
-} satisfies FederationOptions
-
-// ── host/fulgurjs.config.ts（宿主应用自己的配置：消费地址 + 可选页面核对数据）──
-export const hostConfig = {
-  name: 'host-app',
-  remotes: {
-    'remote-a': { dev: 'http://localhost:5174/remote-a', prod: '/remote-a' },
-  },
-  shared: { vue: { singleton: true } },
-} satisfies FederationOptions
-
-// 宿主页面核对数据（具名导出 hostPages，仅供 CLI explain/check-pages；不是 federation() 参数）：
-// export const hostPages = { pages: [{ route: '/remote-a/home', name: 'RemoteAHome', title: '首页' }],
-//                            remotePrefixes: { '/remote-a/': 'remote-a' } }
-
-// 各自 vite.config.ts 里：
-//   import federation from '@fulgurjs/federation'
-//   import fulgurjsConfig from './fulgurjs.config'
-//   plugins: [ ..., federation(fulgurjsConfig) ]