# @bm-fe/react-native-multi-bundle

React Native 多 Bundle 系统 - 支持模块按需加载和独立更新

## 特性

- ✅ **模块按需加载**：支持懒加载，减少初始包体积
- ✅ **模块依赖管理**：自动处理模块间的依赖关系
- ✅ **模块状态管理**：完整的生命周期管理（idle/loading/loaded/failed）
- ✅ **路由加载器**：`createModuleRouteLoader`，完美支持 React Navigation `getComponent` API
- ✅ **错误处理与重试**：自动错误处理，支持重试机制和自定义错误组件
- ✅ **预加载支持**：`preloadModule` 支持关键模块预加载
- ✅ **开发环境 Mock**：开发环境无需 Native 模块即可运行
- ✅ **TypeScript 支持**：完整的类型定义

## 安装

```bash
npm install @bm-fe/react-native-multi-bundle
# 或
yarn add @bm-fe/react-native-multi-bundle
```

## 快速开始

### 1. 初始化多 Bundle 系统

在应用入口（通常是 `App.tsx`）中调用 `initMultiBundle`：

```typescript
import { initMultiBundle, LocalBundleManager } from '@bm-fe/react-native-multi-bundle';
import { Platform } from 'react-native';

function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    async function bootstrap() {
      const result = await initMultiBundle({
        modulePaths: ['src/modules/**'],
        sharedDependencies: [
          'node_modules/@bm-fe/react-native-multi-bundle/**',
          'src/navigation/**'
        ],
        manifestProvider: async () => {
          return await LocalBundleManager.getCurrentBundleManifest();
        },
        preloadModules: ['settings'],
        devServer: {
          host: Platform.OS === 'android' ? '10.0.2.2' : 'localhost',
          port: 8081,
        },
      });

      if (result.success) {
        setReady(true);
      }
    }

    bootstrap();
  }, []);

  if (!ready) {
    return <LoadingScreen />;
  }

  // ... 其余代码
}
```

### 2. 使用模块路由

```typescript
import { createModuleRouteLoader } from '@bm-fe/react-native-multi-bundle';

// 创建路由加载器
export const createHomeScreen = createModuleRouteLoader('home', 'Home');

// 在 React Navigation 中使用
<Stack.Screen name="Home" getComponent={createHomeScreen} />
```

### 3. 自定义错误处理（可选）

```typescript
import { createModuleLoader, type ErrorFallbackProps } from '@bm-fe/react-native-multi-bundle';

// 自定义错误组件
function MyErrorFallback({ moduleId, error, onRetry }: ErrorFallbackProps) {
  return (
    <View>
      <Text>模块 {moduleId} 加载失败</Text>
      <Button title="重试" onPress={onRetry} />
    </View>
  );
}

// 使用自定义错误组件
const createHomeScreen = createModuleLoader(
  'home',
  (exports) => exports.routes.Home,
  {
    ErrorFallback: MyErrorFallback,
    onError: (error) => console.error('加载失败:', error),
  }
);
```

## 完整集成指南

详细的集成步骤请参考：[INTEGRATION.md](./INTEGRATION.md)

包括：
- Metro 配置
- Native 模块集成（Android/iOS）
- 模块配置
- 构建多 Bundle

## API 文档

### initMultiBundle

初始化多 Bundle 系统。

```typescript
function initMultiBundle(config?: MultiBundleConfig): Promise<InitResult>
```

### createModuleRouteLoader

创建模块路由加载器函数（推荐，用于 React Navigation `getComponent` API）。

```typescript
function createModuleRouteLoader(
  moduleId: string,
  routeKey: string
): () => React.ComponentType<any>
```

### preloadModule

预加载模块。

```typescript
function preloadModule(moduleId: string): Promise<void>
```

更多 API 文档请参考：[src/multi-bundle/README.md](./src/multi-bundle/README.md)

## 示例应用

查看完整示例：[examples/demo-app](./examples/demo-app/README.md)

## 版本管理

本项目使用 [standard-version](https://github.com/conventional-changelog/standard-version) 进行版本管理，遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。

### 版本命令

```bash
# 自动判断版本类型
npm run version

# 指定版本类型
npm run version:patch  # 1.0.0 -> 1.0.1
npm run version:minor  # 1.0.0 -> 1.1.0
npm run version:major  # 1.0.0 -> 2.0.0
npm run version:beta   # 1.0.0 -> 1.0.1-beta.0
```

## 发布流程

### 发布前检查

1. **确保代码已提交**
   ```bash
   git status
   git add .
   git commit -m "chore: prepare release"
   ```

2. **运行测试**
   ```bash
   npm test
   ```

3. **检查打包内容**
   ```bash
   npm pack --dry-run
   ```

### 发布 Beta 版本

Beta 版本用于测试新功能，不会影响 `latest` 标签。

```bash
# 方式 1：使用便捷脚本（推荐）
npm run release:beta

# 方式 2：分步执行
npm run version:beta    # 更新版本号为 beta（如：1.0.0 -> 1.0.1-beta.0）
npm run publish:beta    # 发布到 beta 标签
```

**安装 Beta 版本：**
```bash
npm install @bm-fe/react-native-multi-bundle@beta
# 或安装特定 beta 版本
npm install @bm-fe/react-native-multi-bundle@1.0.1-beta.0
```

### 发布正式版本

```bash
# 方式 1：使用便捷脚本（推荐）
npm run release

# 方式 2：分步执行
npm run version        # 自动判断版本类型并更新 CHANGELOG
npm publish            # 发布到 latest 标签
```

**发布流程说明：**
1. `npm run version` 会根据提交信息自动判断版本类型（patch/minor/major）
2. 自动更新 `CHANGELOG.md`
3. 自动创建 git tag
4. `npm publish` 发布到 npm（默认 `latest` 标签）

### 版本标签说明

- **latest**：稳定版本，用户通过 `npm install @bm-fe/react-native-multi-bundle` 安装
- **beta**：测试版本，需要显式指定 `@beta` 标签安装

### 从 Beta 升级到正式版

当 beta 版本稳定后，发布正式版本：

```bash
# 1. 更新版本号为正式版本（移除 beta 后缀）
npm version 1.0.1 --no-git-tag-version

# 2. 发布到 latest
npm publish
```

## 开发

```bash
# 安装依赖
npm install

# 运行测试
npm test

# 运行示例应用
cd examples/demo-app
npm install
npm start
```

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！