@fulgurjs/federation

让一个 Vite 应用使用另一个应用提供的组件、页面、函数或完整子应用。

例如：主系统加载独立部署的审批页面，Vue 页面中嵌入 React 子应用，多个应用共享同一套依赖版本。提供方与使用方可以分仓库开发、独立构建部署。支持 Vue 3 与 React 18/19，Vite 5.1–8。

English ｜ 完整文档中心（中文 docs/zh · English docs/en）

第一次接入完整应用，从一条完整接入流程开始；保留原启动、复用初始化与预检参考已有应用接入。

已有组件直接 expose 原文件；完整应用保留原业务入口并复用初始化，不默认搬 main、重复注册 UI 库或新建 Provider 包装。

已有工程可先用 fulgurjs init --plan 预览接线，审查后再用 --write；复杂业务装配会明确列出人工待办。统一 /vue、/react 入口支持按使用裁剪，不需要改用内部路径。

快速开始

新建工程（推荐）：用 CLI 从完整模板创建可独立运行的联邦工程：

npx @fulgurjs/federation create vue-vue --dir my-federation
cd my-federation
pnpm dev

已有工程接入：安装后在 vite.config.ts 注册插件，应用代码按框架从统一入口导入：

npm add @fulgurjs/federation

// vite.config.ts —— 构建配置用包根
import federation from '@fulgurjs/federation'

export default {
  plugins: [
    // Keep the existing framework plugins.
    federation({
      name: 'host',
      remotes: { 'remote-a': { dev: 'http://localhost:5174', prod: '/remote-a' } },
      shared: { vue: { singleton: true } },
    }),
  ],
}

// Vue 应用代码统一入口 @fulgurjs/federation/vue
import { loadRemote, remoteComponent } from '@fulgurjs/federation/vue'
const RemoteButton = remoteComponent('remote-a/Button')
const math = await loadRemote('remote-a/math')

// React 应用代码统一入口 @fulgurjs/federation/react
import { remoteComponent, useLoadRemote, RemoteErrorBoundary } from '@fulgurjs/federation/react'

// 框架无关的浏览器模块 @fulgurjs/federation/runtime（零 Vue/React 依赖）
import { loadRemote, loadShare } from '@fulgurjs/federation/runtime'

上面配置是已有 Vue 消费方的接线示意，保留原 Vite/Vue 插件和业务配置；remote-a 必须真实暴露 ./Button、./math，并在开发地址启动或生产路径部署。地址按实际 base 替换。React 消费方使用自己的框架 shared 配置与 /react API；跨框架 UI 使用完整应用桥接，不把另一框架组件直接交给 remoteComponent。需要整套可运行工程时直接使用上方 create。

导入入口

记忆口诀：应用跑什么框架，就从哪个框架入口导入；两者都要用的纯 TS 模块从 /runtime；Vite 配置从包根。

能力地图

• 组件与模块：remoteComponent（Vue/React）、useLoadRemote、RemoteErrorBoundary、loadRemote —— 失败显式错误态可重试，不静默兜底。
• 逐页接入：definePages + createHostPages（宿主页面路由表 → 远程页面），CLI check-pages 启动期契约核对。
• 完整子应用桥接：defineApplication（独立/嵌入共用装配；自定义契约可用 defineBridgeApp）+ createVueBridgeApp / createReactBridgeApp（宿主）；挂载/卸载、会话代次、卸载失败封锁。
• URL 同步：createVueBridgeNavigation / createReactBridgeNavigation（宿主）+ Vue 工厂返回 { app, router } / createReactBridgeRouter（子应用）；深链刷新、守卫取消、query/hash 保留。
• 共享依赖：singleton / requiredVersion / strictVersion / shareScope / eager，同步与异步裁决，React 18/19 多版本隔离。
• 远程类型：提供方随构建产出可分发声明（SFC 真实 props/泛型/重载），宿主 dev 自动同步——普通 import 与 loadRemote/remoteComponent/桥接工厂共用一套类型，拼错入口编译期报错；CLI types 供 CI 在 typecheck 前同步校验。 开发期默认只在公开合同边界内生成，不能安全提取或超预算时明确停止，不自动完整扫描；dts.devCheck: "implementation" 可启用完整静态实现检查；生产构建和 CLI 始终检查真实源码，类型就绪不代表业务实现检查通过。
• CLI：create / init / explain / types / check-pages / doctor / port。

文档

示例

五个完整模板（vue-vue / react-react / vue-host-react-remote / react-host-vue-remote / showcase）与功能 Demo 统一维护在 examples/，均可整目录复制后独立安装运行。

贡献与安全

• 贡献流程见 CONTRIBUTING.md；架构与发布见 docs/maintainers/。
• 安全问题请按 SECURITY.md 的渠道私下报告。

License

MIT