@seed-fe/mf-adapters 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 XiangHongAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @seed-fe/mf-adapters
+
+React / Vue / 任意前端微应用在 Garfish / qiankun 等微前端宿主中的适配工具集。
+
+> 本包不关心具体 UI 框架，只约定：微应用提供 `initRuntime`、`mountApp`、`startStandalone` 三个函数，适配层负责把它们接成各宿主需要的生命周期和宿主检测。
+
+## 环境要求
+
+- **运行环境**: 仅支持浏览器环境
+  - Garfish / qiankun 是纯浏览器运行时微前端框架
+  - 不支持 SSR / Node.js 环境（这些场景应使用独立 SSR 或 BFF 组合方案）
+  - 代码中直接访问 `window` 全局对象，不提供 SSR 兼容层
+
+- **多实例支持**: 当前为单实例实现
+  - 适配层（Garfish / qiankun adapter）使用 `Map` 结构，从设计上支持多实例
+  - 微应用示例实现为单实例模式（全局唯一 root / standalone instance）
+  - 如需同一微应用多容器挂载，需微应用侧改为 `Map<container, root>` 实现
+
+## 安装
+
+```bash
+pnpm add @seed-fe/mf-adapters
+```
+
+**依赖说明**：
+
+- `@seed-fe/logger` 会作为依赖自动安装
+
+---
+
+## 核心概念：basename
+
+`basename` 是微应用的路由基础路径，用于配置路由库（如 React Router）。
+
+### 特点
+
+- **定义**: 微应用的路由基础路径
+- **来源**: 宿主根据配置计算后通过 `app.basename` 传递
+- **用途**: 配置微应用内部的路由库（如 `<BrowserRouter basename="/products" />`）
+- **示例**: `"/products"`, `"/orders"`, `"/users"`
+- **说明**: 宿主负责处理前后斜杠，微应用直接使用即可
+
+### 使用示例
+
+```typescript
+// 宿主框架传递给微应用
+renderApp({
+  container: document,
+  props: {
+    app: {
+      name: "product-app",
+      basename: "/products",      // ← 路由基础路径
+      version: "1.0.0"
+    }
+  }
+})
+
+// 微应用使用
+function App({ app }: RuntimeProps) {
+  return (
+    <BrowserRouter basename={app?.basename}>
+      <Routes>
+        <Route path="/" element={<ProductList />} />                 // 实际 URL: /products/
+        <Route path="/detail/:id" element={<ProductDetail />} />     // 实际 URL: /products/detail/123
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+---
+
+下面仅展示"在微应用中如何接入"的示例，分别对应当前使用的两个微前端库：
+
+1. Garfish（容器现用）
+2. qiankun（标准生命周期）
+
+---
+
+## 在微应用中统一接入（Garfish + qiankun）
+
+推荐在微应用中创建一个统一的适配入口，例如：`src/mf-adapters/runtime.ts`。
+
+```ts
+// src/mf-adapters/runtime.ts
+import { createMicroAppRuntime } from '@seed-fe/mf-adapters';
+import type { InitRuntimeFn, RenderAppFn, StartStandaloneFn } from '@seed-fe/mf-adapters';
+
+// 使用类型别名，获得完整类型提示
+const initRuntime: InitRuntimeFn = async () => {
+  // 初始化权限、认证、i18n 等
+};
+
+const renderApp: RenderAppFn = ({ container, props }) => {
+  const root = createRoot(container as HTMLElement);
+  root.render(<App {...props} />);
+
+  return {
+    unmount() {
+      root.unmount();
+    }
+  };
+};
+
+const startStandaloneApp: StartStandaloneFn = async (options) => {
+  await initRuntime();
+  return renderApp({
+    container: options?.container ?? document,
+    props: options?.props,
+  });
+};
+
+// 创建运行时适配实例：内部完成 Garfish / qiankun 等宿主的适配与宿主检测
+export const microAppRuntime = createMicroAppRuntime({
+  initRuntime,
+  mountApp: renderApp,
+  startStandalone: startStandaloneApp,
+});
+```
+
+在应用入口中，仅需要引入这一文件即可触发宿主检测与独立模式回退：
+
+```ts
+// src/mf-adapters/index.ts
+import { microAppRuntime } from './runtime';
+
+// 对于 qiankun 场景，按需导出生命周期（Garfish 无需额外导出）
+export const { bootstrap, mount, unmount } = microAppRuntime.qiankun ?? {};
+```
+
+然后在 `main.tsx` 入口中重导出生命周期：
+
+```ts
+// src/main.tsx
+export { bootstrap, mount, unmount } from '@/mf-adapters';
+```
+
+**重要说明**：
+
+- ✅ 必须使用 `export { ... } from '@/mf-adapters'` 导出生命周期函数
+- ❌ 不能使用 `import '@/mf-adapters'`（副作用导入无法导出，qiankun 会报错 `lifecycleHook is not a function`）
+- Garfish 会自动通过 `__GARFISH_EXPORTS__.provider` 获取 provider，无需手动导出
+- qiankun 需要微应用入口模块导出 `bootstrap`/`mount`/`unmount` 函数
+
+这样，微应用侧只需要维护一个接收 `initRuntime` / `mountApp` / `startStandalone` 的函数调用，其余 Garfish / qiankun 的具体适配逻辑都在 `@seed-fe/mf-adapters` 中统一实现。
+
+---
+
+## Garfish 宿主行为（容器现用）
+
+```ts
+// 内部逻辑（无需在微应用中手写）：
+// - 当 window.__GARFISH__ 为 true 且存在 __GARFISH_EXPORTS__ 时：
+//   - 自动创建 Garfish provider
+//   - 将 provider 赋值给 __GARFISH_EXPORTS__.provider
+// - 宿主通过 Garfish 标准机制挂载微应用
+```
+
+- 适配层内部使用 `Map<Document, AppInstance>` 管理实例，支持同一应用在多个容器中挂载
+- 微应用只需要确保 `initRuntime` 幂等、`renderApp` 返回的实例提供 `unmount()` 即可
+
+---
+
+## qiankun 宿主行为（标准生命周期导出）
+
+```ts
+// 微应用侧只需在统一入口中导出生命周期：
+// src/mf-adapters/index.ts
+import { microAppRuntime } from './runtime';
+
+export const { bootstrap, mount, unmount } = microAppRuntime.qiankun ?? {};
+```
+
+- 微应用侧暴露标准的 qiankun 生命周期
+- 每个 `container` 对应一个 `AppInstance`，适配层内部同样用 Map 管理实例，方便宿主做多实例或保活

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var c=require('@seed-fe/logger');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var c__default=/*#__PURE__*/_interopDefault(c);var R=false;async function _(p){if(R)return;let{hosts:o,fallback:i}=p;for(let n of o)if(n.detect()){c__default.default.info(`[mf-runtime] detected micro-frontend host: ${n.name}`);try{await n.activate?.(),R=!0,c__default.default.info(`[mf-runtime] activated micro-frontend host: ${n.name}`);return}catch(s){c__default.default.error(`[mf-runtime] failed to activate ${n.name}, trying fallback`,s);}}R||(c__default.default.info("[mf-runtime] fallback to standalone mode"),await i());}function h(p){let{initRuntime:o,renderApp:i}=p,n=new Map;function s(){return {render(t){return o().then(()=>{let r=i({container:t.dom,props:{...t.props,app:t.props?.app}});n.set(t.dom,r),c__default.default.info(`[mf-runtime][garfish] rendered successfully: ${t.appName}`);}).catch(r=>{throw c__default.default.error(`[mf-runtime][garfish] render failed: ${t.appName}`,r),n.delete(t.dom),r})},destroy(t){try{let r=n.get(t.dom);r&&r.unmount(),n.delete(t.dom),c__default.default.info("[mf-runtime][garfish] destroy completed");}catch(r){c__default.default.error("[mf-runtime][garfish] destroy failed",r);}}}}return {provider:s}}function y(p){let{initRuntime:o,renderApp:i}=p,n=new Map;async function s(){try{await o(),c__default.default.info("[mf-runtime][qiankun] bootstrap completed");}catch(a){throw c__default.default.error("[mf-runtime][qiankun] bootstrap failed",a),a}}function t(a){try{let e=a.container??document,u=i({container:e,props:{...a,app:a.app}});n.set(e,u),c__default.default.info("[mf-runtime][qiankun] mount completed");}catch(e){throw c__default.default.error("[mf-runtime][qiankun] mount failed",e),e}}function r(a){try{let e=a?.container??document;n.get(e)?.unmount(),n.delete(e),c__default.default.info("[mf-runtime][qiankun] unmount completed");}catch(e){throw c__default.default.error("[mf-runtime][qiankun] unmount failed",e),e}}return {bootstrap:s,mount:t,unmount:r}}function M(p){let{initRuntime:o,mountApp:i,startStandalone:n,hosts:s,extraHosts:t}=p,r=s?.garfish??true,a=s?.qiankun??true,e=[];if(r){let{provider:d}=h({initRuntime:o,renderApp:m=>i({container:m.container,props:m.props})});if(typeof window<"u"&&window.__GARFISH__){let m=globalThis;m.__GARFISH_EXPORTS__||(m.__GARFISH_EXPORTS__={}),m.__GARFISH_EXPORTS__.provider=d;}e.push({name:"garfish",detect:()=>!!window.__GARFISH__,activate:()=>{typeof __GARFISH_EXPORTS__<"u"&&(__GARFISH_EXPORTS__.provider=d);}});}let u;if(a){let{bootstrap:d,mount:m,unmount:g}=y({initRuntime:o,renderApp:i});u={bootstrap:d,mount:m,unmount:g},e.push({name:"qiankun",detect:()=>!!window.__POWERED_BY_QIANKUN__,activate:()=>{c__default.default.info("[mf-adapter] qiankun");}});}return t?.length&&e.push(...t),_({hosts:e,fallback:()=>n()}),{startStandaloneApp:n,qiankun:u}}function T(p){let{initRuntime:o,renderApp:i}=p,n=null;return async function(t){return n||(await o(),n=i({container:t?.container??document,props:t?.props}),n)}}exports.createGarfishAdapter=h;exports.createMicroAppRuntime=M;exports.createQiankunAdapter=y;exports.createStandaloneStarter=T;exports.initMicroFrontendHosts=_;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/hostManager.ts","../src/hosts/garfish.ts","../src/hosts/qiankun.ts","../src/core/setup.ts","../src/core/standalone.ts"],"names":["microFrontendResolved","initMicroFrontendHosts","options","hosts","fallback","host","logger","error","createGarfishAdapter","initRuntime","renderApp","instances","provider","params","instance","createQiankunAdapter","bootstrap","mount","props","container","unmount","createMicroAppRuntime","mountApp","startStandalone","extraHosts","garfishEnabled","qiankunEnabled","hostAdapters","garfishOptions","globalWithExports","qiankunRuntime","createStandaloneStarter","standaloneInstance","customOptions"],"mappings":"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","file":"index.cjs","sourcesContent":["import logger from '@seed-fe/logger';\nimport type { AppInstance } from '../types/base';\n\nexport interface HostAdapterConfig {\n  name: string;\n  /**\n   * 返回 true 表示当前宿主命中\n   */\n  detect(): boolean;\n  /**\n   * 命中宿主后调用，用于注册生命周期或执行初始化逻辑\n   */\n  activate?(): void | Promise<void>;\n}\n\nexport interface HostManagerOptions {\n  hosts: HostAdapterConfig[];\n  /**\n   * 当未检测到任何宿主标识时的回退逻辑，一般为 startStandaloneApp\n   */\n  fallback: () => Promise<AppInstance> | Promise<unknown>;\n}\n\nlet microFrontendResolved = false;\n\n/**\n * 根据宿主环境动态选择微前端框架，若未检测到宿主则回退为独立运行模式。\n */\nexport async function initMicroFrontendHosts(options: HostManagerOptions): Promise<void> {\n  if (microFrontendResolved) {\n    return;\n  }\n\n  const { hosts, fallback } = options;\n\n  for (const host of hosts) {\n    if (host.detect()) {\n      logger.info(`[mf-runtime] detected micro-frontend host: ${host.name}`);\n\n      try {\n        await host.activate?.();\n        microFrontendResolved = true;\n        logger.info(`[mf-runtime] activated micro-frontend host: ${host.name}`);\n        return;\n      } catch (error) {\n        logger.error(`[mf-runtime] failed to activate ${host.name}, trying fallback`, error);\n        // 继续尝试下一个宿主或回退到独立模式\n      }\n    }\n  }\n\n  // 如果所有宿主激活失败或未检测到任何宿主，调用 fallback\n  if (!microFrontendResolved) {\n    logger.info('[mf-runtime] fallback to standalone mode');\n    await fallback();\n  }\n}\n","import logger from '@seed-fe/logger';\nimport type { AdapterOptions, AppInstance } from '../types/base';\nimport type { GarfishDestroyParams, GarfishRenderParams } from '../types/garfish';\n\n/**\n * 创建 Garfish 适配器：\n * - 提供 provider() 给 Garfish 宿主使用\n * - 内部通过 Map<Document, AppInstance> 管理实例，支持多容器挂载\n * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）\n */\nexport function createGarfishAdapter(options: AdapterOptions) {\n  const { initRuntime, renderApp } = options;\n\n  const instances = new Map<Document, AppInstance>();\n\n  function provider() {\n    return {\n      render(params: GarfishRenderParams) {\n        return initRuntime()\n          .then(() => {\n            const instance = renderApp({\n              container: params.dom,\n              props: {\n                ...params.props,\n                app: params.props?.app,\n              },\n            });\n            instances.set(params.dom, instance);\n            logger.info(`[mf-runtime][garfish] rendered successfully: ${params.appName}`);\n          })\n          .catch((error: Error) => {\n            logger.error(`[mf-runtime][garfish] render failed: ${params.appName}`, error);\n            // 清理可能的部分状态\n            instances.delete(params.dom);\n            // 重新抛出，让 Garfish 处理\n            throw error;\n          });\n      },\n      destroy(params: GarfishDestroyParams) {\n        try {\n          const instance = instances.get(params.dom);\n          if (instance) {\n            instance.unmount();\n          }\n          instances.delete(params.dom);\n          logger.info('[mf-runtime][garfish] destroy completed');\n        } catch (error) {\n          // 仅记录错误，允许 Garfish 继续清理其他资源\n          logger.error('[mf-runtime][garfish] destroy failed', error);\n        }\n      },\n    };\n  }\n\n  return { provider };\n}\n","import logger from '@seed-fe/logger';\nimport type { AdapterOptions, AppInstance } from '../types/base';\nimport type { QiankunProps } from '../types/qiankun';\n\n/** @deprecated 使用 AdapterOptions 替代 */\nexport type QiankunAdapterOptions = AdapterOptions;\n\n/**\n * 创建 qiankun 适配器：\n * - 提供 bootstrap/mount/unmount 标准生命周期\n * - 内部通过 Map<container, AppInstance> 管理实例，支持多实例挂载\n * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）\n */\nexport function createQiankunAdapter(options: AdapterOptions) {\n  const { initRuntime, renderApp } = options;\n\n  const instances = new Map<Element | Document, AppInstance>();\n\n  async function bootstrap() {\n    try {\n      await initRuntime();\n      logger.info('[mf-runtime][qiankun] bootstrap completed');\n    } catch (error) {\n      logger.error('[mf-runtime][qiankun] bootstrap failed', error);\n      throw error;\n    }\n  }\n\n  function mount(props: QiankunProps) {\n    try {\n      const container = props.container ?? document;\n      const instance = renderApp({\n        container,\n        props: {\n          ...props,\n          app: props.app,\n        },\n      });\n      instances.set(container, instance);\n      logger.info('[mf-runtime][qiankun] mount completed');\n    } catch (error) {\n      logger.error('[mf-runtime][qiankun] mount failed', error);\n      throw error;\n    }\n  }\n\n  function unmount(props?: QiankunProps) {\n    try {\n      const container = props?.container ?? document;\n      const instance = instances.get(container);\n      instance?.unmount();\n      instances.delete(container);\n      logger.info('[mf-runtime][qiankun] unmount completed');\n    } catch (error) {\n      logger.error('[mf-runtime][qiankun] unmount failed', error);\n      throw error;\n    }\n  }\n\n  return { bootstrap, mount, unmount };\n}\n","import logger from '@seed-fe/logger';\nimport { createGarfishAdapter } from '../hosts/garfish';\nimport { createQiankunAdapter } from '../hosts/qiankun';\nimport type { AppInstance, InitRuntimeFn, RenderAppFn, StartStandaloneFn } from '../types/base';\nimport type { GarfishExports } from '../types/garfish';\nimport type { QiankunProps } from '../types/qiankun';\nimport type { HostAdapterConfig } from './hostManager';\nimport { initMicroFrontendHosts } from './hostManager';\nimport type { StandaloneOptions } from './standalone';\n\nexport interface MicroAppRuntimeOptions {\n  /**\n   * 微应用运行时初始化逻辑，由应用侧实现。\n   * 典型职责：权限、认证、i18n 等一次性初始化。\n   */\n  initRuntime: InitRuntimeFn;\n  /**\n   * 微应用渲染逻辑，由应用侧实现。\n   * - 适配层只关心 container / props 约定\n   * - 内部可以是 React / Vue / 纯 DOM 等任意实现\n   */\n  mountApp: RenderAppFn;\n  /**\n   * 独立运行模式入口，由应用侧实现。\n   * - 一般通过 createStandaloneStarter(initRuntime, renderApp) 生成\n   * - 适配层只在未检测到任何宿主时调用\n   */\n  startStandalone: StartStandaloneFn;\n  /**\n   * 内置宿主框架配置\n   *\n   * - 默认全部启用（garfish: true, qiankun: true）\n   * - 设置为 false 可禁用特定框架\n   * - 设置为 {} 等同于全部启用\n   *\n   * @example\n   * ```ts\n   * // 默认全部启用\n   * createMicroAppRuntime({ initRuntime, mountApp, startStandalone });\n   *\n   * // 仅启用 garfish\n   * createMicroAppRuntime({\n   *   initRuntime,\n   *   mountApp,\n   *   startStandalone,\n   *   hosts: { garfish: true, qiankun: false },\n   * });\n   *\n   * // 禁用所有内置框架，仅使用 extraHosts\n   * createMicroAppRuntime({\n   *   initRuntime,\n   *   mountApp,\n   *   startStandalone,\n   *   hosts: { garfish: false, qiankun: false },\n   *   extraHosts: [customHost],\n   * });\n   * ```\n   */\n  hosts?: {\n    garfish?: boolean;\n    qiankun?: boolean;\n  };\n  /**\n   * 额外宿主配置，用于接入其他微前端库\n   * - 适合其他团队维护的宿主，仅需在微应用中传入配置即可\n   */\n  extraHosts?: HostAdapterConfig[];\n}\n\nexport interface MicroAppRuntime {\n  /**\n   * 独立运行模式入口（直接透传应用侧实现）\n   */\n  startStandaloneApp: (options?: StandaloneOptions) => Promise<AppInstance>;\n  /**\n   * qiankun 生命周期适配结果\n   * - 需要在微应用中按需导出：export const { bootstrap, mount, unmount } = runtime.qiankun ?? {};\n   */\n  qiankun?: {\n    bootstrap: () => Promise<void>;\n    mount: (props: QiankunProps) => void;\n    unmount: (props?: QiankunProps) => void;\n  };\n}\n\n/**\n * 创建微应用运行时适配：\n * - 接收应用侧的 initRuntime / mountApp / startStandalone\n * - 内部完成 Garfish / qiankun 等宿主的适配与检测\n * - 返回 qiankun 生命周期供微应用按需导出\n *\n * 微应用层只需要：\n * 1. 提供 initRuntime / mountApp / startStandalone\n * 2. 在入口处调用 createMicroAppRuntime(...)\n * 3. 若需要支持 qiankun，再将 runtime.qiankun 的三个生命周期导出\n */\nexport function createMicroAppRuntime(options: MicroAppRuntimeOptions): MicroAppRuntime {\n  const { initRuntime, mountApp, startStandalone, hosts, extraHosts } = options;\n\n  // 默认全部启用\n  const garfishEnabled = hosts?.garfish ?? true;\n  const qiankunEnabled = hosts?.qiankun ?? true;\n\n  const hostAdapters: HostAdapterConfig[] = [];\n\n  // Garfish：通过 __GARFISH__ / __GARFISH_EXPORTS__ 适配 provider\n  if (garfishEnabled) {\n    const { provider } = createGarfishAdapter({\n      initRuntime,\n      renderApp: (garfishOptions) =>\n        mountApp({\n          container: garfishOptions.container,\n          props: garfishOptions.props,\n        }),\n    });\n\n    // 宿主模式下：若检测到 Garfish 标识，则立即挂载 provider。\n    // 兼容两种注入方式：\n    // - 宿主预先创建 __GARFISH_EXPORTS__\n    // - 子应用自行创建 __GARFISH_EXPORTS__\n    if (typeof window !== 'undefined' && (window as Window & { __GARFISH__?: boolean }).__GARFISH__) {\n      const globalWithExports = globalThis as typeof globalThis & { __GARFISH_EXPORTS__?: GarfishExports };\n      if (!globalWithExports.__GARFISH_EXPORTS__) {\n        globalWithExports.__GARFISH_EXPORTS__ = {} as GarfishExports;\n      }\n      globalWithExports.__GARFISH_EXPORTS__.provider = provider;\n    }\n\n    hostAdapters.push({\n      name: 'garfish',\n      detect: () => Boolean(window.__GARFISH__),\n      activate: () => {\n        if (typeof __GARFISH_EXPORTS__ !== 'undefined') {\n          __GARFISH_EXPORTS__.provider = provider;\n        }\n      },\n    });\n  }\n\n  // qiankun：返回标准生命周期，由微应用按需导出\n  let qiankunRuntime: MicroAppRuntime['qiankun'];\n\n  if (qiankunEnabled) {\n    const { bootstrap, mount, unmount } = createQiankunAdapter({\n      initRuntime,\n      renderApp: mountApp,\n    });\n\n    qiankunRuntime = {\n      bootstrap,\n      mount,\n      unmount,\n    };\n\n    // 将 qiankun 添加到 hosts 数组用于检测\n    // 虽然 qiankun 不需要 activate（宿主会主动调用生命周期），\n    // 但仍需要 detect 以防止错误地进入独立运行模式\n    hostAdapters.push({\n      name: 'qiankun',\n      detect: () => Boolean(window.__POWERED_BY_QIANKUN__),\n      activate: () => {\n        logger.info(`[mf-adapter] qiankun`);\n        // qiankun 宿主会主动调用生命周期，无需额外激活\n      },\n    });\n  }\n\n  if (extraHosts?.length) {\n    hostAdapters.push(...extraHosts);\n  }\n\n  // 初始化宿主检测 + 独立运行回退\n  void initMicroFrontendHosts({\n    hosts: hostAdapters,\n    fallback: () => startStandalone(),\n  });\n\n  return {\n    startStandaloneApp: startStandalone,\n    qiankun: qiankunRuntime,\n  };\n}\n","import type { AppInstance, InitRuntimeFn, RenderAppFn, RuntimeProps } from '../types/base';\n\nexport interface StandaloneOptions {\n  container?: Document;\n  props?: RuntimeProps;\n}\n\nexport interface StandaloneStarterOptions {\n  initRuntime: InitRuntimeFn;\n  renderApp: RenderAppFn;\n}\n\n/**\n * 创建独立运行模式启动器：\n * - 统一处理非微前端宿主环境下的初始化逻辑\n * - 内部保证单例实例，避免重复挂载\n */\nexport function createStandaloneStarter(options: StandaloneStarterOptions) {\n  const { initRuntime, renderApp } = options;\n\n  let standaloneInstance: AppInstance | null = null;\n\n  return async function startStandaloneApp(customOptions?: StandaloneOptions): Promise<AppInstance> {\n    if (standaloneInstance) {\n      return standaloneInstance;\n    }\n\n    await initRuntime();\n\n    standaloneInstance = renderApp({\n      container: customOptions?.container ?? document,\n      props: customOptions?.props,\n    });\n\n    return standaloneInstance;\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,352 @@
+/**
+ * 主应用传递给微应用的配置约定：
+ * - 与容器工程的 ProjectConfig.microapps[] 结构保持兼容
+ * - 但不直接依赖容器工程的类型定义，避免跨工程路径耦合
+ */
+interface MicroAppConfig {
+    /** 微应用唯一标识（如 "product-app"） */
+    name?: string;
+    /**
+     * 微应用的路由基础路径
+     *
+     * - **来源**: 由主应用根据配置计算后传递（如从 pathname 计算得到）
+     * - **用途**: 配置路由库（如 React Router 的 `<BrowserRouter basename="/products" />`）
+     * - **示例**: `"/products"`, `"/orders"`, `"/users"`
+     * - **说明**: 主应用负责处理前后斜杠，微应用直接使用即可
+     */
+    basename: string;
+    /** 微应用版本号 */
+    version?: string;
+    [key: string]: unknown;
+}
+/**
+ * 微应用运行时初始化参数
+ *
+ * 说明：
+ * - 仅作为适配层与微应用之间的契约类型
+ * - 不关心具体实现细节（权限 / 认证 / i18n 等）
+ * - 支持宿主透传扩展字段
+ */
+interface RuntimeProps {
+    /**
+     * 主应用传递的微应用配置信息
+     *
+     * - **来源**: 主应用根据配置构建并传递
+     * - **内容**: 包含 basename（必需）, name, version 等配置
+     */
+    app?: MicroAppConfig;
+    /**
+     * 宿主扩展字段
+     *
+     * 允许宿主透传专有字段，避免类型冲突
+     */
+    [key: string]: unknown;
+}
+/**
+ * 微应用实例：用于统一卸载逻辑
+ *
+ * 由微应用自行决定实例内部结构，这里只约定必须提供 unmount 方法。
+ */
+interface AppInstance {
+    unmount(): void;
+}
+/**
+ * 微应用运行时初始化函数类型
+ *
+ * 职责：权限、认证、i18n 等一次性初始化
+ * 约定：必须是幂等的（可被多次调用）
+ *
+ * @example
+ * ```ts
+ * import type { InitRuntimeFn } from '@seed-fe/mf-adapters';
+ *
+ * export const initRuntime: InitRuntimeFn = async () => {
+ *   // 初始化权限、认证、i18n 等
+ * };
+ * ```
+ */
+type InitRuntimeFn = () => Promise<void>;
+/**
+ * 微应用渲染函数类型
+ *
+ * 不关心具体框架（React / Vue / 纯 DOM），仅约定返回包含 unmount() 的实例
+ *
+ * @example
+ * ```ts
+ * import type { RenderAppFn } from '@seed-fe/mf-adapters';
+ *
+ * export const renderApp: RenderAppFn = ({ container, props }) => {
+ *   const root = createRoot(container as HTMLElement);
+ *   root.render(<App {...props} />);
+ *
+ *   return {
+ *     unmount() {
+ *       root.unmount();
+ *     }
+ *   };
+ * };
+ * ```
+ */
+type RenderAppFn = (options: {
+    container: Element | Document;
+    props?: RuntimeProps;
+}) => AppInstance;
+/**
+ * 独立运行模式启动函数类型
+ *
+ * 用于非微前端宿主环境下的独立运行
+ *
+ * @example
+ * ```ts
+ * import type { StartStandaloneFn } from '@seed-fe/mf-adapters';
+ *
+ * export const startStandalone: StartStandaloneFn = async (options) => {
+ *   await initRuntime();
+ *   return renderApp({
+ *     container: options?.container ?? document,
+ *     props: options?.props,
+ *   });
+ * };
+ * ```
+ */
+type StartStandaloneFn = (options?: {
+    container?: Document;
+    props?: RuntimeProps;
+}) => Promise<AppInstance>;
+/**
+ * 宿主适配器选项契约
+ *
+ * - 适用于所有微前端宿主（Garfish / qiankun / 未来扩展）
+ * - 定义了微应用侧必须实现的两个核心函数
+ */
+interface AdapterOptions {
+    /**
+     * 微应用运行时初始化逻辑
+     *
+     * - 职责：权限、认证、i18n 等一次性初始化
+     * - 约定：必须是幂等的（可被多次调用）
+     */
+    initRuntime: InitRuntimeFn;
+    /**
+     * 微应用渲染函数
+     *
+     * - 不关心具体框架（React / Vue / 纯 DOM）
+     * - 仅约定返回包含 unmount() 的实例
+     */
+    renderApp: RenderAppFn;
+}
+
+interface HostAdapterConfig {
+    name: string;
+    /**
+     * 返回 true 表示当前宿主命中
+     */
+    detect(): boolean;
+    /**
+     * 命中宿主后调用，用于注册生命周期或执行初始化逻辑
+     */
+    activate?(): void | Promise<void>;
+}
+interface HostManagerOptions {
+    hosts: HostAdapterConfig[];
+    /**
+     * 当未检测到任何宿主标识时的回退逻辑，一般为 startStandaloneApp
+     */
+    fallback: () => Promise<AppInstance> | Promise<unknown>;
+}
+/**
+ * 根据宿主环境动态选择微前端框架，若未检测到宿主则回退为独立运行模式。
+ */
+declare function initMicroFrontendHosts(options: HostManagerOptions): Promise<void>;
+
+/**
+ * qiankun 相关类型声明与全局接口扩展。
+ *
+ * 注意：
+ * - 此处只声明类型，不做任何运行时代码
+ * - 运行时适配逻辑在 hosts/qiankun.ts 中实现
+ */
+
+declare global {
+    interface Window {
+        __POWERED_BY_QIANKUN__?: boolean;
+    }
+}
+/** qiankun 生命周期 props */
+interface QiankunProps extends RuntimeProps {
+    container?: Element;
+}
+
+interface StandaloneOptions {
+    container?: Document;
+    props?: RuntimeProps;
+}
+interface StandaloneStarterOptions {
+    initRuntime: InitRuntimeFn;
+    renderApp: RenderAppFn;
+}
+/**
+ * 创建独立运行模式启动器：
+ * - 统一处理非微前端宿主环境下的初始化逻辑
+ * - 内部保证单例实例，避免重复挂载
+ */
+declare function createStandaloneStarter(options: StandaloneStarterOptions): (customOptions?: StandaloneOptions) => Promise<AppInstance>;
+
+interface MicroAppRuntimeOptions {
+    /**
+     * 微应用运行时初始化逻辑，由应用侧实现。
+     * 典型职责：权限、认证、i18n 等一次性初始化。
+     */
+    initRuntime: InitRuntimeFn;
+    /**
+     * 微应用渲染逻辑，由应用侧实现。
+     * - 适配层只关心 container / props 约定
+     * - 内部可以是 React / Vue / 纯 DOM 等任意实现
+     */
+    mountApp: RenderAppFn;
+    /**
+     * 独立运行模式入口，由应用侧实现。
+     * - 一般通过 createStandaloneStarter(initRuntime, renderApp) 生成
+     * - 适配层只在未检测到任何宿主时调用
+     */
+    startStandalone: StartStandaloneFn;
+    /**
+     * 内置宿主框架配置
+     *
+     * - 默认全部启用（garfish: true, qiankun: true）
+     * - 设置为 false 可禁用特定框架
+     * - 设置为 {} 等同于全部启用
+     *
+     * @example
+     * ```ts
+     * // 默认全部启用
+     * createMicroAppRuntime({ initRuntime, mountApp, startStandalone });
+     *
+     * // 仅启用 garfish
+     * createMicroAppRuntime({
+     *   initRuntime,
+     *   mountApp,
+     *   startStandalone,
+     *   hosts: { garfish: true, qiankun: false },
+     * });
+     *
+     * // 禁用所有内置框架，仅使用 extraHosts
+     * createMicroAppRuntime({
+     *   initRuntime,
+     *   mountApp,
+     *   startStandalone,
+     *   hosts: { garfish: false, qiankun: false },
+     *   extraHosts: [customHost],
+     * });
+     * ```
+     */
+    hosts?: {
+        garfish?: boolean;
+        qiankun?: boolean;
+    };
+    /**
+     * 额外宿主配置，用于接入其他微前端库
+     * - 适合其他团队维护的宿主，仅需在微应用中传入配置即可
+     */
+    extraHosts?: HostAdapterConfig[];
+}
+interface MicroAppRuntime {
+    /**
+     * 独立运行模式入口（直接透传应用侧实现）
+     */
+    startStandaloneApp: (options?: StandaloneOptions) => Promise<AppInstance>;
+    /**
+     * qiankun 生命周期适配结果
+     * - 需要在微应用中按需导出：export const { bootstrap, mount, unmount } = runtime.qiankun ?? {};
+     */
+    qiankun?: {
+        bootstrap: () => Promise<void>;
+        mount: (props: QiankunProps) => void;
+        unmount: (props?: QiankunProps) => void;
+    };
+}
+/**
+ * 创建微应用运行时适配：
+ * - 接收应用侧的 initRuntime / mountApp / startStandalone
+ * - 内部完成 Garfish / qiankun 等宿主的适配与检测
+ * - 返回 qiankun 生命周期供微应用按需导出
+ *
+ * 微应用层只需要：
+ * 1. 提供 initRuntime / mountApp / startStandalone
+ * 2. 在入口处调用 createMicroAppRuntime(...)
+ * 3. 若需要支持 qiankun，再将 runtime.qiankun 的三个生命周期导出
+ */
+declare function createMicroAppRuntime(options: MicroAppRuntimeOptions): MicroAppRuntime;
+
+/**
+ * Garfish 相关类型声明与全局接口扩展。
+ *
+ * 注意：
+ * - 此处只声明类型，不做任何运行时代码
+ * - 运行时适配逻辑在 hosts/garfish.ts 中实现
+ */
+
+declare global {
+    interface Window {
+        /** Garfish 在 window 上注入的宿主标识 */
+        __GARFISH__?: boolean;
+    }
+    /** Garfish 在运行时注入的全局导出对象 */
+    var __GARFISH_EXPORTS__: GarfishExports;
+}
+/** Garfish render 钩子参数 */
+interface GarfishRenderParams {
+    appName: string;
+    dom: Document;
+    basename?: string;
+    appRenderInfo: GarfishAppRenderInfo;
+    props?: RuntimeProps;
+}
+/** Garfish destroy 钩子参数 */
+interface GarfishDestroyParams {
+    appName: string;
+    dom: Document;
+    appRenderInfo: GarfishAppRenderInfo;
+    props?: RuntimeProps;
+}
+/** Garfish 应用渲染信息 */
+interface GarfishAppRenderInfo {
+    isMount?: boolean;
+    isUnmount?: boolean;
+}
+/** Garfish 导出对象接口 */
+interface GarfishExports {
+    provider: () => {
+        render: (params: GarfishRenderParams) => void;
+        destroy: (params: GarfishDestroyParams) => void;
+    };
+}
+
+/**
+ * 创建 Garfish 适配器：
+ * - 提供 provider() 给 Garfish 宿主使用
+ * - 内部通过 Map<Document, AppInstance> 管理实例，支持多容器挂载
+ * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）
+ */
+declare function createGarfishAdapter(options: AdapterOptions): {
+    provider: () => {
+        render(params: GarfishRenderParams): Promise<void>;
+        destroy(params: GarfishDestroyParams): void;
+    };
+};
+
+/** @deprecated 使用 AdapterOptions 替代 */
+type QiankunAdapterOptions = AdapterOptions;
+/**
+ * 创建 qiankun 适配器：
+ * - 提供 bootstrap/mount/unmount 标准生命周期
+ * - 内部通过 Map<container, AppInstance> 管理实例，支持多实例挂载
+ * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）
+ */
+declare function createQiankunAdapter(options: AdapterOptions): {
+    bootstrap: () => Promise<void>;
+    mount: (props: QiankunProps) => void;
+    unmount: (props?: QiankunProps) => void;
+};
+
+export { type AdapterOptions, type AppInstance, type GarfishAppRenderInfo, type GarfishDestroyParams, type GarfishExports, type GarfishRenderParams, type HostAdapterConfig, type HostManagerOptions, type InitRuntimeFn, type MicroAppConfig, type MicroAppRuntime, type MicroAppRuntimeOptions, type QiankunAdapterOptions, type QiankunProps, type RenderAppFn, type RuntimeProps, type StandaloneOptions, type StandaloneStarterOptions, type StartStandaloneFn, createGarfishAdapter, createMicroAppRuntime, createQiankunAdapter, createStandaloneStarter, initMicroFrontendHosts };

package/dist/index.d.ts

@@ -0,0 +1,352 @@
+/**
+ * 主应用传递给微应用的配置约定：
+ * - 与容器工程的 ProjectConfig.microapps[] 结构保持兼容
+ * - 但不直接依赖容器工程的类型定义，避免跨工程路径耦合
+ */
+interface MicroAppConfig {
+    /** 微应用唯一标识（如 "product-app"） */
+    name?: string;
+    /**
+     * 微应用的路由基础路径
+     *
+     * - **来源**: 由主应用根据配置计算后传递（如从 pathname 计算得到）
+     * - **用途**: 配置路由库（如 React Router 的 `<BrowserRouter basename="/products" />`）
+     * - **示例**: `"/products"`, `"/orders"`, `"/users"`
+     * - **说明**: 主应用负责处理前后斜杠，微应用直接使用即可
+     */
+    basename: string;
+    /** 微应用版本号 */
+    version?: string;
+    [key: string]: unknown;
+}
+/**
+ * 微应用运行时初始化参数
+ *
+ * 说明：
+ * - 仅作为适配层与微应用之间的契约类型
+ * - 不关心具体实现细节（权限 / 认证 / i18n 等）
+ * - 支持宿主透传扩展字段
+ */
+interface RuntimeProps {
+    /**
+     * 主应用传递的微应用配置信息
+     *
+     * - **来源**: 主应用根据配置构建并传递
+     * - **内容**: 包含 basename（必需）, name, version 等配置
+     */
+    app?: MicroAppConfig;
+    /**
+     * 宿主扩展字段
+     *
+     * 允许宿主透传专有字段，避免类型冲突
+     */
+    [key: string]: unknown;
+}
+/**
+ * 微应用实例：用于统一卸载逻辑
+ *
+ * 由微应用自行决定实例内部结构，这里只约定必须提供 unmount 方法。
+ */
+interface AppInstance {
+    unmount(): void;
+}
+/**
+ * 微应用运行时初始化函数类型
+ *
+ * 职责：权限、认证、i18n 等一次性初始化
+ * 约定：必须是幂等的（可被多次调用）
+ *
+ * @example
+ * ```ts
+ * import type { InitRuntimeFn } from '@seed-fe/mf-adapters';
+ *
+ * export const initRuntime: InitRuntimeFn = async () => {
+ *   // 初始化权限、认证、i18n 等
+ * };
+ * ```
+ */
+type InitRuntimeFn = () => Promise<void>;
+/**
+ * 微应用渲染函数类型
+ *
+ * 不关心具体框架（React / Vue / 纯 DOM），仅约定返回包含 unmount() 的实例
+ *
+ * @example
+ * ```ts
+ * import type { RenderAppFn } from '@seed-fe/mf-adapters';
+ *
+ * export const renderApp: RenderAppFn = ({ container, props }) => {
+ *   const root = createRoot(container as HTMLElement);
+ *   root.render(<App {...props} />);
+ *
+ *   return {
+ *     unmount() {
+ *       root.unmount();
+ *     }
+ *   };
+ * };
+ * ```
+ */
+type RenderAppFn = (options: {
+    container: Element | Document;
+    props?: RuntimeProps;
+}) => AppInstance;
+/**
+ * 独立运行模式启动函数类型
+ *
+ * 用于非微前端宿主环境下的独立运行
+ *
+ * @example
+ * ```ts
+ * import type { StartStandaloneFn } from '@seed-fe/mf-adapters';
+ *
+ * export const startStandalone: StartStandaloneFn = async (options) => {
+ *   await initRuntime();
+ *   return renderApp({
+ *     container: options?.container ?? document,
+ *     props: options?.props,
+ *   });
+ * };
+ * ```
+ */
+type StartStandaloneFn = (options?: {
+    container?: Document;
+    props?: RuntimeProps;
+}) => Promise<AppInstance>;
+/**
+ * 宿主适配器选项契约
+ *
+ * - 适用于所有微前端宿主（Garfish / qiankun / 未来扩展）
+ * - 定义了微应用侧必须实现的两个核心函数
+ */
+interface AdapterOptions {
+    /**
+     * 微应用运行时初始化逻辑
+     *
+     * - 职责：权限、认证、i18n 等一次性初始化
+     * - 约定：必须是幂等的（可被多次调用）
+     */
+    initRuntime: InitRuntimeFn;
+    /**
+     * 微应用渲染函数
+     *
+     * - 不关心具体框架（React / Vue / 纯 DOM）
+     * - 仅约定返回包含 unmount() 的实例
+     */
+    renderApp: RenderAppFn;
+}
+
+interface HostAdapterConfig {
+    name: string;
+    /**
+     * 返回 true 表示当前宿主命中
+     */
+    detect(): boolean;
+    /**
+     * 命中宿主后调用，用于注册生命周期或执行初始化逻辑
+     */
+    activate?(): void | Promise<void>;
+}
+interface HostManagerOptions {
+    hosts: HostAdapterConfig[];
+    /**
+     * 当未检测到任何宿主标识时的回退逻辑，一般为 startStandaloneApp
+     */
+    fallback: () => Promise<AppInstance> | Promise<unknown>;
+}
+/**
+ * 根据宿主环境动态选择微前端框架，若未检测到宿主则回退为独立运行模式。
+ */
+declare function initMicroFrontendHosts(options: HostManagerOptions): Promise<void>;
+
+/**
+ * qiankun 相关类型声明与全局接口扩展。
+ *
+ * 注意：
+ * - 此处只声明类型，不做任何运行时代码
+ * - 运行时适配逻辑在 hosts/qiankun.ts 中实现
+ */
+
+declare global {
+    interface Window {
+        __POWERED_BY_QIANKUN__?: boolean;
+    }
+}
+/** qiankun 生命周期 props */
+interface QiankunProps extends RuntimeProps {
+    container?: Element;
+}
+
+interface StandaloneOptions {
+    container?: Document;
+    props?: RuntimeProps;
+}
+interface StandaloneStarterOptions {
+    initRuntime: InitRuntimeFn;
+    renderApp: RenderAppFn;
+}
+/**
+ * 创建独立运行模式启动器：
+ * - 统一处理非微前端宿主环境下的初始化逻辑
+ * - 内部保证单例实例，避免重复挂载
+ */
+declare function createStandaloneStarter(options: StandaloneStarterOptions): (customOptions?: StandaloneOptions) => Promise<AppInstance>;
+
+interface MicroAppRuntimeOptions {
+    /**
+     * 微应用运行时初始化逻辑，由应用侧实现。
+     * 典型职责：权限、认证、i18n 等一次性初始化。
+     */
+    initRuntime: InitRuntimeFn;
+    /**
+     * 微应用渲染逻辑，由应用侧实现。
+     * - 适配层只关心 container / props 约定
+     * - 内部可以是 React / Vue / 纯 DOM 等任意实现
+     */
+    mountApp: RenderAppFn;
+    /**
+     * 独立运行模式入口，由应用侧实现。
+     * - 一般通过 createStandaloneStarter(initRuntime, renderApp) 生成
+     * - 适配层只在未检测到任何宿主时调用
+     */
+    startStandalone: StartStandaloneFn;
+    /**
+     * 内置宿主框架配置
+     *
+     * - 默认全部启用（garfish: true, qiankun: true）
+     * - 设置为 false 可禁用特定框架
+     * - 设置为 {} 等同于全部启用
+     *
+     * @example
+     * ```ts
+     * // 默认全部启用
+     * createMicroAppRuntime({ initRuntime, mountApp, startStandalone });
+     *
+     * // 仅启用 garfish
+     * createMicroAppRuntime({
+     *   initRuntime,
+     *   mountApp,
+     *   startStandalone,
+     *   hosts: { garfish: true, qiankun: false },
+     * });
+     *
+     * // 禁用所有内置框架，仅使用 extraHosts
+     * createMicroAppRuntime({
+     *   initRuntime,
+     *   mountApp,
+     *   startStandalone,
+     *   hosts: { garfish: false, qiankun: false },
+     *   extraHosts: [customHost],
+     * });
+     * ```
+     */
+    hosts?: {
+        garfish?: boolean;
+        qiankun?: boolean;
+    };
+    /**
+     * 额外宿主配置，用于接入其他微前端库
+     * - 适合其他团队维护的宿主，仅需在微应用中传入配置即可
+     */
+    extraHosts?: HostAdapterConfig[];
+}
+interface MicroAppRuntime {
+    /**
+     * 独立运行模式入口（直接透传应用侧实现）
+     */
+    startStandaloneApp: (options?: StandaloneOptions) => Promise<AppInstance>;
+    /**
+     * qiankun 生命周期适配结果
+     * - 需要在微应用中按需导出：export const { bootstrap, mount, unmount } = runtime.qiankun ?? {};
+     */
+    qiankun?: {
+        bootstrap: () => Promise<void>;
+        mount: (props: QiankunProps) => void;
+        unmount: (props?: QiankunProps) => void;
+    };
+}
+/**
+ * 创建微应用运行时适配：
+ * - 接收应用侧的 initRuntime / mountApp / startStandalone
+ * - 内部完成 Garfish / qiankun 等宿主的适配与检测
+ * - 返回 qiankun 生命周期供微应用按需导出
+ *
+ * 微应用层只需要：
+ * 1. 提供 initRuntime / mountApp / startStandalone
+ * 2. 在入口处调用 createMicroAppRuntime(...)
+ * 3. 若需要支持 qiankun，再将 runtime.qiankun 的三个生命周期导出
+ */
+declare function createMicroAppRuntime(options: MicroAppRuntimeOptions): MicroAppRuntime;
+
+/**
+ * Garfish 相关类型声明与全局接口扩展。
+ *
+ * 注意：
+ * - 此处只声明类型，不做任何运行时代码
+ * - 运行时适配逻辑在 hosts/garfish.ts 中实现
+ */
+
+declare global {
+    interface Window {
+        /** Garfish 在 window 上注入的宿主标识 */
+        __GARFISH__?: boolean;
+    }
+    /** Garfish 在运行时注入的全局导出对象 */
+    var __GARFISH_EXPORTS__: GarfishExports;
+}
+/** Garfish render 钩子参数 */
+interface GarfishRenderParams {
+    appName: string;
+    dom: Document;
+    basename?: string;
+    appRenderInfo: GarfishAppRenderInfo;
+    props?: RuntimeProps;
+}
+/** Garfish destroy 钩子参数 */
+interface GarfishDestroyParams {
+    appName: string;
+    dom: Document;
+    appRenderInfo: GarfishAppRenderInfo;
+    props?: RuntimeProps;
+}
+/** Garfish 应用渲染信息 */
+interface GarfishAppRenderInfo {
+    isMount?: boolean;
+    isUnmount?: boolean;
+}
+/** Garfish 导出对象接口 */
+interface GarfishExports {
+    provider: () => {
+        render: (params: GarfishRenderParams) => void;
+        destroy: (params: GarfishDestroyParams) => void;
+    };
+}
+
+/**
+ * 创建 Garfish 适配器：
+ * - 提供 provider() 给 Garfish 宿主使用
+ * - 内部通过 Map<Document, AppInstance> 管理实例，支持多容器挂载
+ * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）
+ */
+declare function createGarfishAdapter(options: AdapterOptions): {
+    provider: () => {
+        render(params: GarfishRenderParams): Promise<void>;
+        destroy(params: GarfishDestroyParams): void;
+    };
+};
+
+/** @deprecated 使用 AdapterOptions 替代 */
+type QiankunAdapterOptions = AdapterOptions;
+/**
+ * 创建 qiankun 适配器：
+ * - 提供 bootstrap/mount/unmount 标准生命周期
+ * - 内部通过 Map<container, AppInstance> 管理实例，支持多实例挂载
+ * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）
+ */
+declare function createQiankunAdapter(options: AdapterOptions): {
+    bootstrap: () => Promise<void>;
+    mount: (props: QiankunProps) => void;
+    unmount: (props?: QiankunProps) => void;
+};
+
+export { type AdapterOptions, type AppInstance, type GarfishAppRenderInfo, type GarfishDestroyParams, type GarfishExports, type GarfishRenderParams, type HostAdapterConfig, type HostManagerOptions, type InitRuntimeFn, type MicroAppConfig, type MicroAppRuntime, type MicroAppRuntimeOptions, type QiankunAdapterOptions, type QiankunProps, type RenderAppFn, type RuntimeProps, type StandaloneOptions, type StandaloneStarterOptions, type StartStandaloneFn, createGarfishAdapter, createMicroAppRuntime, createQiankunAdapter, createStandaloneStarter, initMicroFrontendHosts };

package/dist/index.js

@@ -0,0 +1,2 @@
+import u from'@seed-fe/logger';var _=false;async function h(p){if(_)return;let{hosts:o,fallback:i}=p;for(let n of o)if(n.detect()){u.info(`[mf-runtime] detected micro-frontend host: ${n.name}`);try{await n.activate?.(),_=!0,u.info(`[mf-runtime] activated micro-frontend host: ${n.name}`);return}catch(s){u.error(`[mf-runtime] failed to activate ${n.name}, trying fallback`,s);}}_||(u.info("[mf-runtime] fallback to standalone mode"),await i());}function y(p){let{initRuntime:o,renderApp:i}=p,n=new Map;function s(){return {render(t){return o().then(()=>{let r=i({container:t.dom,props:{...t.props,app:t.props?.app}});n.set(t.dom,r),u.info(`[mf-runtime][garfish] rendered successfully: ${t.appName}`);}).catch(r=>{throw u.error(`[mf-runtime][garfish] render failed: ${t.appName}`,r),n.delete(t.dom),r})},destroy(t){try{let r=n.get(t.dom);r&&r.unmount(),n.delete(t.dom),u.info("[mf-runtime][garfish] destroy completed");}catch(r){u.error("[mf-runtime][garfish] destroy failed",r);}}}}return {provider:s}}function g(p){let{initRuntime:o,renderApp:i}=p,n=new Map;async function s(){try{await o(),u.info("[mf-runtime][qiankun] bootstrap completed");}catch(a){throw u.error("[mf-runtime][qiankun] bootstrap failed",a),a}}function t(a){try{let e=a.container??document,d=i({container:e,props:{...a,app:a.app}});n.set(e,d),u.info("[mf-runtime][qiankun] mount completed");}catch(e){throw u.error("[mf-runtime][qiankun] mount failed",e),e}}function r(a){try{let e=a?.container??document;n.get(e)?.unmount(),n.delete(e),u.info("[mf-runtime][qiankun] unmount completed");}catch(e){throw u.error("[mf-runtime][qiankun] unmount failed",e),e}}return {bootstrap:s,mount:t,unmount:r}}function D(p){let{initRuntime:o,mountApp:i,startStandalone:n,hosts:s,extraHosts:t}=p,r=s?.garfish??true,a=s?.qiankun??true,e=[];if(r){let{provider:l}=y({initRuntime:o,renderApp:m=>i({container:m.container,props:m.props})});if(typeof window<"u"&&window.__GARFISH__){let m=globalThis;m.__GARFISH_EXPORTS__||(m.__GARFISH_EXPORTS__={}),m.__GARFISH_EXPORTS__.provider=l;}e.push({name:"garfish",detect:()=>!!window.__GARFISH__,activate:()=>{typeof __GARFISH_EXPORTS__<"u"&&(__GARFISH_EXPORTS__.provider=l);}});}let d;if(a){let{bootstrap:l,mount:m,unmount:P}=g({initRuntime:o,renderApp:i});d={bootstrap:l,mount:m,unmount:P},e.push({name:"qiankun",detect:()=>!!window.__POWERED_BY_QIANKUN__,activate:()=>{u.info("[mf-adapter] qiankun");}});}return t?.length&&e.push(...t),h({hosts:e,fallback:()=>n()}),{startStandaloneApp:n,qiankun:d}}function N(p){let{initRuntime:o,renderApp:i}=p,n=null;return async function(t){return n||(await o(),n=i({container:t?.container??document,props:t?.props}),n)}}export{y as createGarfishAdapter,D as createMicroAppRuntime,g as createQiankunAdapter,N as createStandaloneStarter,h as initMicroFrontendHosts};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/hostManager.ts","../src/hosts/garfish.ts","../src/hosts/qiankun.ts","../src/core/setup.ts","../src/core/standalone.ts"],"names":["microFrontendResolved","initMicroFrontendHosts","options","hosts","fallback","host","logger","error","createGarfishAdapter","initRuntime","renderApp","instances","provider","params","instance","createQiankunAdapter","bootstrap","mount","props","container","unmount","createMicroAppRuntime","mountApp","startStandalone","extraHosts","garfishEnabled","qiankunEnabled","hostAdapters","garfishOptions","globalWithExports","qiankunRuntime","createStandaloneStarter","standaloneInstance","customOptions"],"mappings":"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","file":"index.js","sourcesContent":["import logger from '@seed-fe/logger';\nimport type { AppInstance } from '../types/base';\n\nexport interface HostAdapterConfig {\n  name: string;\n  /**\n   * 返回 true 表示当前宿主命中\n   */\n  detect(): boolean;\n  /**\n   * 命中宿主后调用，用于注册生命周期或执行初始化逻辑\n   */\n  activate?(): void | Promise<void>;\n}\n\nexport interface HostManagerOptions {\n  hosts: HostAdapterConfig[];\n  /**\n   * 当未检测到任何宿主标识时的回退逻辑，一般为 startStandaloneApp\n   */\n  fallback: () => Promise<AppInstance> | Promise<unknown>;\n}\n\nlet microFrontendResolved = false;\n\n/**\n * 根据宿主环境动态选择微前端框架，若未检测到宿主则回退为独立运行模式。\n */\nexport async function initMicroFrontendHosts(options: HostManagerOptions): Promise<void> {\n  if (microFrontendResolved) {\n    return;\n  }\n\n  const { hosts, fallback } = options;\n\n  for (const host of hosts) {\n    if (host.detect()) {\n      logger.info(`[mf-runtime] detected micro-frontend host: ${host.name}`);\n\n      try {\n        await host.activate?.();\n        microFrontendResolved = true;\n        logger.info(`[mf-runtime] activated micro-frontend host: ${host.name}`);\n        return;\n      } catch (error) {\n        logger.error(`[mf-runtime] failed to activate ${host.name}, trying fallback`, error);\n        // 继续尝试下一个宿主或回退到独立模式\n      }\n    }\n  }\n\n  // 如果所有宿主激活失败或未检测到任何宿主，调用 fallback\n  if (!microFrontendResolved) {\n    logger.info('[mf-runtime] fallback to standalone mode');\n    await fallback();\n  }\n}\n","import logger from '@seed-fe/logger';\nimport type { AdapterOptions, AppInstance } from '../types/base';\nimport type { GarfishDestroyParams, GarfishRenderParams } from '../types/garfish';\n\n/**\n * 创建 Garfish 适配器：\n * - 提供 provider() 给 Garfish 宿主使用\n * - 内部通过 Map<Document, AppInstance> 管理实例，支持多容器挂载\n * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）\n */\nexport function createGarfishAdapter(options: AdapterOptions) {\n  const { initRuntime, renderApp } = options;\n\n  const instances = new Map<Document, AppInstance>();\n\n  function provider() {\n    return {\n      render(params: GarfishRenderParams) {\n        return initRuntime()\n          .then(() => {\n            const instance = renderApp({\n              container: params.dom,\n              props: {\n                ...params.props,\n                app: params.props?.app,\n              },\n            });\n            instances.set(params.dom, instance);\n            logger.info(`[mf-runtime][garfish] rendered successfully: ${params.appName}`);\n          })\n          .catch((error: Error) => {\n            logger.error(`[mf-runtime][garfish] render failed: ${params.appName}`, error);\n            // 清理可能的部分状态\n            instances.delete(params.dom);\n            // 重新抛出，让 Garfish 处理\n            throw error;\n          });\n      },\n      destroy(params: GarfishDestroyParams) {\n        try {\n          const instance = instances.get(params.dom);\n          if (instance) {\n            instance.unmount();\n          }\n          instances.delete(params.dom);\n          logger.info('[mf-runtime][garfish] destroy completed');\n        } catch (error) {\n          // 仅记录错误，允许 Garfish 继续清理其他资源\n          logger.error('[mf-runtime][garfish] destroy failed', error);\n        }\n      },\n    };\n  }\n\n  return { provider };\n}\n","import logger from '@seed-fe/logger';\nimport type { AdapterOptions, AppInstance } from '../types/base';\nimport type { QiankunProps } from '../types/qiankun';\n\n/** @deprecated 使用 AdapterOptions 替代 */\nexport type QiankunAdapterOptions = AdapterOptions;\n\n/**\n * 创建 qiankun 适配器：\n * - 提供 bootstrap/mount/unmount 标准生命周期\n * - 内部通过 Map<container, AppInstance> 管理实例，支持多实例挂载\n * - 不关心具体渲染实现细节（React/Vue/纯 DOM 等）\n */\nexport function createQiankunAdapter(options: AdapterOptions) {\n  const { initRuntime, renderApp } = options;\n\n  const instances = new Map<Element | Document, AppInstance>();\n\n  async function bootstrap() {\n    try {\n      await initRuntime();\n      logger.info('[mf-runtime][qiankun] bootstrap completed');\n    } catch (error) {\n      logger.error('[mf-runtime][qiankun] bootstrap failed', error);\n      throw error;\n    }\n  }\n\n  function mount(props: QiankunProps) {\n    try {\n      const container = props.container ?? document;\n      const instance = renderApp({\n        container,\n        props: {\n          ...props,\n          app: props.app,\n        },\n      });\n      instances.set(container, instance);\n      logger.info('[mf-runtime][qiankun] mount completed');\n    } catch (error) {\n      logger.error('[mf-runtime][qiankun] mount failed', error);\n      throw error;\n    }\n  }\n\n  function unmount(props?: QiankunProps) {\n    try {\n      const container = props?.container ?? document;\n      const instance = instances.get(container);\n      instance?.unmount();\n      instances.delete(container);\n      logger.info('[mf-runtime][qiankun] unmount completed');\n    } catch (error) {\n      logger.error('[mf-runtime][qiankun] unmount failed', error);\n      throw error;\n    }\n  }\n\n  return { bootstrap, mount, unmount };\n}\n","import logger from '@seed-fe/logger';\nimport { createGarfishAdapter } from '../hosts/garfish';\nimport { createQiankunAdapter } from '../hosts/qiankun';\nimport type { AppInstance, InitRuntimeFn, RenderAppFn, StartStandaloneFn } from '../types/base';\nimport type { GarfishExports } from '../types/garfish';\nimport type { QiankunProps } from '../types/qiankun';\nimport type { HostAdapterConfig } from './hostManager';\nimport { initMicroFrontendHosts } from './hostManager';\nimport type { StandaloneOptions } from './standalone';\n\nexport interface MicroAppRuntimeOptions {\n  /**\n   * 微应用运行时初始化逻辑，由应用侧实现。\n   * 典型职责：权限、认证、i18n 等一次性初始化。\n   */\n  initRuntime: InitRuntimeFn;\n  /**\n   * 微应用渲染逻辑，由应用侧实现。\n   * - 适配层只关心 container / props 约定\n   * - 内部可以是 React / Vue / 纯 DOM 等任意实现\n   */\n  mountApp: RenderAppFn;\n  /**\n   * 独立运行模式入口，由应用侧实现。\n   * - 一般通过 createStandaloneStarter(initRuntime, renderApp) 生成\n   * - 适配层只在未检测到任何宿主时调用\n   */\n  startStandalone: StartStandaloneFn;\n  /**\n   * 内置宿主框架配置\n   *\n   * - 默认全部启用（garfish: true, qiankun: true）\n   * - 设置为 false 可禁用特定框架\n   * - 设置为 {} 等同于全部启用\n   *\n   * @example\n   * ```ts\n   * // 默认全部启用\n   * createMicroAppRuntime({ initRuntime, mountApp, startStandalone });\n   *\n   * // 仅启用 garfish\n   * createMicroAppRuntime({\n   *   initRuntime,\n   *   mountApp,\n   *   startStandalone,\n   *   hosts: { garfish: true, qiankun: false },\n   * });\n   *\n   * // 禁用所有内置框架，仅使用 extraHosts\n   * createMicroAppRuntime({\n   *   initRuntime,\n   *   mountApp,\n   *   startStandalone,\n   *   hosts: { garfish: false, qiankun: false },\n   *   extraHosts: [customHost],\n   * });\n   * ```\n   */\n  hosts?: {\n    garfish?: boolean;\n    qiankun?: boolean;\n  };\n  /**\n   * 额外宿主配置，用于接入其他微前端库\n   * - 适合其他团队维护的宿主，仅需在微应用中传入配置即可\n   */\n  extraHosts?: HostAdapterConfig[];\n}\n\nexport interface MicroAppRuntime {\n  /**\n   * 独立运行模式入口（直接透传应用侧实现）\n   */\n  startStandaloneApp: (options?: StandaloneOptions) => Promise<AppInstance>;\n  /**\n   * qiankun 生命周期适配结果\n   * - 需要在微应用中按需导出：export const { bootstrap, mount, unmount } = runtime.qiankun ?? {};\n   */\n  qiankun?: {\n    bootstrap: () => Promise<void>;\n    mount: (props: QiankunProps) => void;\n    unmount: (props?: QiankunProps) => void;\n  };\n}\n\n/**\n * 创建微应用运行时适配：\n * - 接收应用侧的 initRuntime / mountApp / startStandalone\n * - 内部完成 Garfish / qiankun 等宿主的适配与检测\n * - 返回 qiankun 生命周期供微应用按需导出\n *\n * 微应用层只需要：\n * 1. 提供 initRuntime / mountApp / startStandalone\n * 2. 在入口处调用 createMicroAppRuntime(...)\n * 3. 若需要支持 qiankun，再将 runtime.qiankun 的三个生命周期导出\n */\nexport function createMicroAppRuntime(options: MicroAppRuntimeOptions): MicroAppRuntime {\n  const { initRuntime, mountApp, startStandalone, hosts, extraHosts } = options;\n\n  // 默认全部启用\n  const garfishEnabled = hosts?.garfish ?? true;\n  const qiankunEnabled = hosts?.qiankun ?? true;\n\n  const hostAdapters: HostAdapterConfig[] = [];\n\n  // Garfish：通过 __GARFISH__ / __GARFISH_EXPORTS__ 适配 provider\n  if (garfishEnabled) {\n    const { provider } = createGarfishAdapter({\n      initRuntime,\n      renderApp: (garfishOptions) =>\n        mountApp({\n          container: garfishOptions.container,\n          props: garfishOptions.props,\n        }),\n    });\n\n    // 宿主模式下：若检测到 Garfish 标识，则立即挂载 provider。\n    // 兼容两种注入方式：\n    // - 宿主预先创建 __GARFISH_EXPORTS__\n    // - 子应用自行创建 __GARFISH_EXPORTS__\n    if (typeof window !== 'undefined' && (window as Window & { __GARFISH__?: boolean }).__GARFISH__) {\n      const globalWithExports = globalThis as typeof globalThis & { __GARFISH_EXPORTS__?: GarfishExports };\n      if (!globalWithExports.__GARFISH_EXPORTS__) {\n        globalWithExports.__GARFISH_EXPORTS__ = {} as GarfishExports;\n      }\n      globalWithExports.__GARFISH_EXPORTS__.provider = provider;\n    }\n\n    hostAdapters.push({\n      name: 'garfish',\n      detect: () => Boolean(window.__GARFISH__),\n      activate: () => {\n        if (typeof __GARFISH_EXPORTS__ !== 'undefined') {\n          __GARFISH_EXPORTS__.provider = provider;\n        }\n      },\n    });\n  }\n\n  // qiankun：返回标准生命周期，由微应用按需导出\n  let qiankunRuntime: MicroAppRuntime['qiankun'];\n\n  if (qiankunEnabled) {\n    const { bootstrap, mount, unmount } = createQiankunAdapter({\n      initRuntime,\n      renderApp: mountApp,\n    });\n\n    qiankunRuntime = {\n      bootstrap,\n      mount,\n      unmount,\n    };\n\n    // 将 qiankun 添加到 hosts 数组用于检测\n    // 虽然 qiankun 不需要 activate（宿主会主动调用生命周期），\n    // 但仍需要 detect 以防止错误地进入独立运行模式\n    hostAdapters.push({\n      name: 'qiankun',\n      detect: () => Boolean(window.__POWERED_BY_QIANKUN__),\n      activate: () => {\n        logger.info(`[mf-adapter] qiankun`);\n        // qiankun 宿主会主动调用生命周期，无需额外激活\n      },\n    });\n  }\n\n  if (extraHosts?.length) {\n    hostAdapters.push(...extraHosts);\n  }\n\n  // 初始化宿主检测 + 独立运行回退\n  void initMicroFrontendHosts({\n    hosts: hostAdapters,\n    fallback: () => startStandalone(),\n  });\n\n  return {\n    startStandaloneApp: startStandalone,\n    qiankun: qiankunRuntime,\n  };\n}\n","import type { AppInstance, InitRuntimeFn, RenderAppFn, RuntimeProps } from '../types/base';\n\nexport interface StandaloneOptions {\n  container?: Document;\n  props?: RuntimeProps;\n}\n\nexport interface StandaloneStarterOptions {\n  initRuntime: InitRuntimeFn;\n  renderApp: RenderAppFn;\n}\n\n/**\n * 创建独立运行模式启动器：\n * - 统一处理非微前端宿主环境下的初始化逻辑\n * - 内部保证单例实例，避免重复挂载\n */\nexport function createStandaloneStarter(options: StandaloneStarterOptions) {\n  const { initRuntime, renderApp } = options;\n\n  let standaloneInstance: AppInstance | null = null;\n\n  return async function startStandaloneApp(customOptions?: StandaloneOptions): Promise<AppInstance> {\n    if (standaloneInstance) {\n      return standaloneInstance;\n    }\n\n    await initRuntime();\n\n    standaloneInstance = renderApp({\n      container: customOptions?.container ?? document,\n      props: customOptions?.props,\n    });\n\n    return standaloneInstance;\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@seed-fe/mf-adapters",
+  "version": "1.0.0-alpha.1",
+  "description": "微前端适配工具库，支持 React/Vue/任意框架在 Garfish/qiankun 等宿主中运行",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "micro-frontend",
+    "microfrontend",
+    "garfish",
+    "qiankun",
+    "react",
+    "runtime"
+  ],
+  "author": "xianghongai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xianghongai/seed-fe-mf-adapters.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xianghongai/seed-fe-mf-adapters/issues"
+  },
+  "homepage": "https://github.com/xianghongai/seed-fe-mf-adapters#readme",
+  "dependencies": {
+    "@seed-fe/logger": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "jsdom": "^27.4.0",
+    "npm-check-updates": "^19.1.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm typecheck && biome check --write",
+    "format": "biome format --write",
+    "lint": "biome check --write",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}