@kookapp/mf-runtime-sdk/README.md

模块联邦运行时SDK

## 运行时模块共享中心

`mf-runtime-sdk` 是一个基于 [@module-federation/runtime](https://github.com/module-federation/universe/tree/main/packages/runtime) 构建的库，旨在提供一个运行时的模块共享中心。它允许您在应用程序中动态加载和管理来自其他独立部署的模块联邦应用（Remotes）的模块（如组件、工具函数等），实现灵活的应用间代码共享和微前端架构。

## 功能特性

- **运行时加载:** 在应用运行时动态加载远程模块，无需在构建时确定所有依赖。
- **模块缓存:** 内置缓存机制，提高模块访问效率。
- **本地模块管理:** 支持注册和访问当前应用内部的模块。
- **灵活的配置:** 支持配置远程模块的开发和生产环境入口。
- **类型安全:** 提供 TypeScript 类型定义，增强开发体验。

## 安装

```bash
npm install mf-runtime-sdk
# 或者使用 yarn
yarn add mf-runtime-sdk
```

## 使用方法

### 初始化

在使用任何功能之前，需要先初始化 SDK。通常在应用的入口文件或启动阶段进行初始化。

```typescript
import MF, { MFConfig } from 'mf-runtime-sdk';

const config: MFConfig = {
  isDev: process.env.NODE_ENV === 'development', // 可选，是否为开发环境，影响远程入口的选择，默认为 true
  modules: { // 可选，注册本地模块
    'request': import('@utils/request'), // 支持 Promise 形式的懒加载
    'Button': () => import('./components/Button'), // 支持函数形式的懒加载
    // ...更多本地模块
  },
  share: { // 可选，Module Federation 的共享模块配置
    react: { singleton: true, eager: true },
    'react-dom': { singleton: true, eager: true },
    // TODO: 添加 Mf-runtime-sdk 的共享，这个是必要的
    // ...其他共享库
  },
  remotes: { // 可选，预配置的远程模块
    discover: { // remoteKey
      key: 'discover', // Module Federation name
      description: '发现页模块',
      provider: {
        dev: () => ({ name: 'discover', entry: 'http://localhost:3007/remoteEntry.js' }),
        prod: () => ({ name: 'discover_prod', entry: 'https://kookapp.cn/discover/remoteEntry.js' }),
      },
    },
    // ...更多远程模块配置
  },
};

MF.init(config);
```

// TODO: 在 remote 配置中需要添加 mf-runtime-sdk 的共享配置

### 动态添加远程模块

可以在应用运行时动态添加新的远程模块配置。

```typescript
import MF, { RemoteConfig } from 'mf-runtime-sdk';

const newRemoteConfig: RemoteConfig = {
  key: 'gift',
  description: '福利模块',
  provider: {
    dev: () => ({ name: 'gift', entry: 'http://localhost:3008/remoteEntry.js' }),
    prod: () => ({ name: 'gift_prod', entry: 'https://gift.m.163.com/remoteEntry.js' }),
  },
};

MF.add(newRemoteConfig);
```

### 获取模块

使用 `MF.get` 获取模块（支持本地和远程模块）。这是一个异步操作，因为远程模块可能需要下载。

```typescript
import MF from 'mf-runtime-sdk';

// 获取远程模块中的组件
async function loadRemoteComponent() {
  try {
    // 格式: 'remoteKey/moduleName'
    const { MyComponent } = await MF.get('discover/MyComponent');
    // 使用 MyComponent...
  } catch (error) {
    console.error('加载远程组件失败:', error);
  }
}

loadRemoteComponent();
```

### 同步获取模块

`MF.getSync` 只能获取已加载或已缓存的模块（包括本地模块和已经通过 `get` 成功加载的远程模块）。如果模块尚未加载或加载失败，将返回 `null`。

```typescript
import MF from 'mf-runtime-sdk';

// 获取已同步注册的 Host模块
const { request } = MF.getSync('host');
// 使用 request

// 获取已缓存的远程模块组件 (谨慎使用，只在确定已加载时)
const { MyComponent } = MF.getSync('discover/MyComponent') as any;
if (MyComponent) {
  // 使用 MyComponent...
}

```

### 手动设置缓存

可以使用 `MF.set` 手动将任何值缓存到模块中心，之后可以通过 `get` 或 `getSync` 获取。

```typescript
import MF from 'mf-runtime-sdk';

// 缓存一个配置对象
MF.set('my-settings', { theme: 'dark', language: 'en' });

// 获取缓存的值
const settings = MF.getSync('my-settings');
console.log(settings); // { theme: 'dark', language: 'en' }

// 也可以使用 providerKey 形式，例如 'manual/my-settings'
MF.set('manual/user-info', { name: 'Alice' });
const userInfo = MF.getSync('manual/user-info');
console.log(userInfo); // { name: 'Alice' }
```

## API 参考

请参考导出的 TypeScript 类型定义 (`MFConfig`, `RemoteConfig`, `RemoteProviderConfig`) 和 `MF` 对象上的方法签名获取完整的 API 信息。

```typescript
// 从 'mf-runtime-sdk' 导入类型
export type { MFConfig, RemoteConfig, RemoteProviderConfig }

interface MF {
  init: (config: MFConfig) => void;
  add: (remoteConfig: RemoteConfig) => void;
  get: (modulePath: string) => Promise<any | null>;
  getSync: (modulePath: string) => any | null;
  set: (modulePath: string, value: any) => void;
}

const MF: MF;
export default MF;
```

## 贡献

欢迎提交 Issue 或 Pull Request。

## 许可证

ISC License