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

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

特性

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

安装

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

快速开始

1. 初始化多 Bundle 系统

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

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. 使用模块路由

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

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

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

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

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

包括：

• Metro 配置
• Native 模块集成（Android/iOS）
• 模块配置
• 构建多 Bundle

API 文档

initMultiBundle

初始化多 Bundle 系统。

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

createModuleRouteLoader

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

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

preloadModule

预加载模块。

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

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

示例应用

查看完整示例：examples/demo-app

版本管理

本项目使用 standard-version 进行版本管理，遵循 Conventional Commits 规范。

版本命令

# 自动判断版本类型
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. 确保代码已提交

   git status
   git add .
   git commit -m "chore: prepare release"

2. 运行测试

   npm test

3. 检查打包内容

   npm pack --dry-run

发布 Beta 版本

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

# 方式 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 版本：

npm install @bm-fe/react-native-multi-bundle@beta
# 或安装特定 beta 版本
npm install @bm-fe/[email protected]

发布正式版本

# 方式 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 版本稳定后，发布正式版本：

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

# 2. 发布到 latest
npm publish

开发

# 安装依赖
npm install

# 运行测试
npm test

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

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！