@fulgurjs/federation 0.6.1 → 0.7.0

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

@@ -36,7 +36,7 @@
 - [ ] 零兜底：联邦不可用显式报错（杀 remote 故障注入）
 - [ ] 装后可用：npm pack → 干净项目 dev+prod（e2e/h7-install-test.sh）
 
-> **目录约定说明（0.6.0 起）**：联邦相关产物统一收在 **`src/fulgurjs/`** 一个文件夹——`types/`（插件每次 dev 自动生成的类型直连与运行时垫片，**勿手改**；src 布局 tsconfig 零配置生效，无 src 布局回退根目录 `.fulgurjs/types/`）与 `exposes/`（联邦启动引导 federatedBoot + 供外部加载的组件，**你的代码**）。宿主侧桥接文件（fulgurjsBridge/fulgurjsPages）同属迁移工具脚手架约定而非插件要求，可按团队习惯重组，只要 vite `exposes` 映射与调用点跟着改。
+> **目录约定说明（0.6.0 起）**：联邦相关产物统一收在 **`src/fulgurjs/`** 一个文件夹（每个应用一份，内附 README 说明归属）——`types/`（插件每次 dev 自动生成的类型直连与运行时类型垫片，**勿手改**；src 布局 tsconfig 零配置生效，无 src 布局回退根目录 `.fulgurjs/types/`）与按角色划分的代码子目录：远程应用为 `exposes/`（联邦启动引导 federatedBoot + 供外部加载的组件），宿主应用为 `host/`（桥接 bridge.ts + 页面路由表 pages.ts）。均为迁移工具脚手架约定而非插件要求，可按团队习惯重组，只要 vite `exposes` 映射与调用点跟着改。
 
 ## 三B、首次使用避坑清单（真实迁移踩坑实录，全文见仓库 README「避坑指南」节）
 
@@ -51,28 +51,30 @@
 | 7 | 登录异步链未完成就断言 | e2e 偶发被弹回登录页 | 等「登录表单消失」而非固定秒数；后台慢链 ≥15s |
 | 8 | 多版本组件库 CSS | 后加载覆盖 `:root` 变量 | 主流版本变量一致则无感；升级时留意 |
 | 9 | 后端缺端点 | 404/401 资源报错 | 代理/NGINX 层加诚实空响应垫片（不伪造业务数据） |
-| 10 | 远程页面（exposes 目标文件）静态导入 `virtual:fulgurjs-runtime` | 宿主跨源加载后渲染上下文破坏：resolveComponent / withDirectives / "Missing ref owner" 告警、内容区静默空白 | 改走宿主单例（见下节）；插件 dev 下已对此显式报错拦截 |
+| 10 | ~~远程页面（exposes 目标文件）静态导入 `virtual:fulgurjs-runtime`~~ | —— | **0.4.1 起规则已废除**：插件自动把该导入改写为惰性单例代理，远程页面可直接静态导入，写法与宿主一致（详见下节三B-1） |
 
-### 三B-1、远程页面如何取宿主运行时（跨源单例契约）
+### 三B-1、远程页面如何取宿主运行时（0.7.0 起更新）
 
-exposes 目标文件（被宿主跨源加载的远程页面/组件）**禁止静态 `import 'virtual:fulgurjs-runtime'`**——
-该导入会改由远程 dev server 求值，在远程模块图内实例化第二份运行时副本，破坏渲染上下文
-（插件 dev 下已对此显式报错，错误信息即指向本节）。
-
-正确写法（二选一，取到的是同一份页面级单例）：
+0.4.1 起，exposes 目标文件（被宿主跨源加载的远程页面/组件）**可以直接静态导入**
+`virtual:fulgurjs-runtime`——插件自动把远程页面里的该导入改写为**惰性单例代理**：
+求值期零副作用、调用期转发页面级运行时单例。宿主与远程写法完全一致，无需区分。
 
 ```ts
-// ① 直接读全局单例（bpm detail 页先例）
-const runtime = (globalThis as any).__FULGURJS_RUNTIME__
-const mod = await runtime.loadRemote('host-app/UserProfile')
+// 远程页面内，与宿主页面写法完全一致
+import { loadRemote } from 'virtual:fulgurjs-runtime'
+```
 
-// ② 经独立产物 getRuntime()（最小宿主/无构建场景，见 manual §5.1）
-import { getRuntime, version } from '/fulgurjs-runtime.js'
-const mod = await getRuntime().loadRemote('mes-bpm/./TaskCard')
+组件直渲染（**0.7.0 起推荐**）用 `@fulgurjs/federation/vue` 子路径的 `remoteComponent`——
+`defineAsyncComponent + loadRemote` 的标准封装，加载失败显式错误占位（错误码+根因+修法），无任何兜底：
+
+```ts
+import { remoteComponent } from '@fulgurjs/federation/vue'
+const FederatedBusinessForm = remoteComponent('cku-mes-admin/FormRouterPage')
 ```
 
-运行时单例带 `version` 字段（与插件包版本同源）用于跨源副本一致性诊断；
-宿主页面（非 exposes 目标）不受此限，可正常静态导入虚拟模块。
+~~早期版本（≤0.3.x）曾要求远程页面禁静态导入、手工读 `globalThis.__FULGURJS_RUNTIME__`~~——该规则已废除。
+`(globalThis as any).__FULGURJS_RUNTIME__` 直取全局单例仅剩"独立访问远程页 vs 联邦加载"的 realm
+检测等特殊场景（0.7.0 删除 iframe 乾坤旧通道后，常规集成已无此类需求）。
 
 ## 四、乾坤下线顺序
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulgurjs/federation",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Vite Module Federation with full Webpack MF parity. Dev & production, no compromise.",
   "license": "MIT",
@@ -23,6 +23,11 @@
       "import": "./dist/config.js",
       "require": "./dist/config.cjs"
     },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js",
+      "require": "./dist/vue.cjs"
+    },
     "./client": {
       "types": "./client.d.ts"
     },
@@ -44,7 +49,7 @@
     "docs/vite-upstream-issue-irregexp.md"
   ],
   "scripts": {
-    "build": "cp ../../README.md README.md && mkdir -p docs && cp ../../docs/manual.html ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md ../../docs/vite-upstream-issue-irregexp.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/config.ts --format esm,cjs --dts --external vite --target node18 --clean && 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",
+    "build": "cp ../../README.md README.md && mkdir -p docs && cp ../../docs/manual.html ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md ../../docs/vite-upstream-issue-irregexp.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/config.ts src/vue.ts --format esm,cjs --dts --external vite --target node18 --clean && 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",
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
@@ -55,12 +60,15 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "jsdom": "^24.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.1.0"
+    "vitest": "^3.1.0",
+    "vue": "^3.5.22"
   },
   "peerDependencies": {
-    "vite": ">=5.0.0"
+    "vite": ">=5.0.0",
+    "vue": ">=3.2.0"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -90,5 +98,10 @@
   },
   "bin": {
     "fulgurjs": "./dist/cli.js"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
   }
 }