@bm-fe/react-native-multi-bundle 1.0.0-beta.0

package/INTEGRATION.md

@@ -0,0 +1,371 @@
+# React Native 多 Bundle 系统集成指南
+
+本指南将帮助你将多 Bundle 系统集成到你的 React Native 项目中。
+
+## 目录
+
+- [安装](#安装)
+- [Metro 配置](#metro-配置)
+- [Native 模块集成](#native-模块集成)
+  - [Android](#android)
+  - [iOS](#ios)
+- [初始化多 Bundle 系统](#初始化多-bundle-系统)
+- [配置模块](#配置模块)
+- [构建多 Bundle](#构建多-bundle)
+- [常见问题](#常见问题)
+
+## 安装
+
+```bash
+npm install @bm-fe/react-native-multi-bundle
+# 或
+yarn add @bm-fe/react-native-multi-bundle
+```
+
+## Metro 配置
+
+### 1. 复制 Metro 配置模板
+
+将 `templates/metro.config.js.template` 复制到你的项目根目录，重命名为 `metro.config.js`。
+
+### 2. 调整配置
+
+根据你的项目结构，修改以下配置：
+
+```javascript
+// 模块路径规则（glob 模式）
+const modulePaths = ['src/modules/**'];
+
+// 共享依赖路径（这些代码会被打包到主 bundle）
+const sharedDependencies = [
+  'node_modules/@bm-fe/react-native-multi-bundle/**',
+  'src/navigation/**'
+];
+```
+
+### 3. 环境变量（可选）
+
+你也可以通过环境变量覆盖配置：
+
+```bash
+RN_MULTI_BUNDLE_MODULE_PATHS='["src/modules/**"]' \
+RN_MULTI_BUNDLE_SHARED_DEPS='["src/multi-bundle/**","src/navigation/**"]' \
+npx react-native start
+```
+
+## Native 模块集成
+
+### Android
+
+#### 1. 复制 Native 模块文件
+
+将以下文件从 `templates/native/android/` 复制到你的 Android 项目：
+
+- `ModuleLoaderModule.kt` → `android/app/src/main/java/com/yourpackage/ModuleLoaderModule.kt`
+- `ModuleLoaderPackage.kt` → `android/app/src/main/java/com/yourpackage/ModuleLoaderPackage.kt`
+
+**重要**：修改文件中的包名 `com.yourpackage` 为你的实际包名。
+
+#### 2. 注册 ModuleLoaderPackage
+
+根据你使用的 React Native 架构版本，选择对应的方式：
+
+##### 方式一：新架构（React Native 0.82+，使用 ReactHost）
+
+如果你的 `MainApplication.kt` 使用 `ReactHost`（新架构），在 `PackageList` 中添加：
+
+```kotlin
+package com.yourpackage
+
+import android.app.Application
+import com.yourpackage.ModuleLoaderPackage
+import com.facebook.react.PackageList
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
+import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
+
+class MainApplication : Application(), ReactApplication {
+  override val reactHost: ReactHost by lazy {
+    getDefaultReactHost(
+      context = applicationContext,
+      packageList =
+        PackageList(this).packages.apply {
+          // Packages that cannot be autolinked yet can be added manually here
+          add(ModuleLoaderPackage())
+        },
+    )
+  }
+
+  override fun onCreate() {
+    super.onCreate()
+    loadReactNative(this)
+  }
+}
+```
+
+##### 方式二：旧架构（使用 ReactNativeHost）
+
+如果你的 `MainApplication.kt` 使用 `ReactNativeHost`（旧架构），在 `getPackages()` 方法中添加：
+
+```kotlin
+package com.yourpackage
+
+import android.app.Application
+import com.yourpackage.ModuleLoaderPackage
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactPackage
+import com.facebook.react.PackageList
+import com.facebook.react.ReactNativeHost
+import com.facebook.react.defaults.DefaultReactNativeHost
+
+class MainApplication : Application(), ReactApplication {
+  override val reactNativeHost: ReactNativeHost =
+      object : DefaultReactNativeHost(this) {
+          override fun getPackages(): List<ReactPackage> =
+              PackageList(this).packages.apply {
+                // Packages that cannot be autolinked yet can be added manually here
+                add(ModuleLoaderPackage())
+              }
+
+          override fun getJSMainModuleName(): String = "index"
+          override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
+          // ... 其他配置
+      }
+
+  // ... 其他代码
+}
+```
+
+**注意**：React Native 0.82+ 默认使用新架构（ReactHost），推荐使用方式一。
+
+#### 3. 确保 assets 目录存在
+
+确保 `android/app/src/main/assets/` 目录存在，bundle 文件将放在这里。
+
+### iOS
+
+#### 1. 复制 Native 模块文件
+
+将以下文件从 `templates/native/ios/` 添加到你的 iOS 项目：
+
+- `ModuleLoaderModule.h`
+- `ModuleLoaderModule.m`
+
+在 Xcode 中：
+1. 右键点击项目 → Add Files to "YourProject"
+2. 选择这两个文件
+3. 确保 "Copy items if needed" 已勾选
+
+#### 2. 注册模块
+
+iOS 端的模块会自动注册（通过 `RCT_EXPORT_MODULE`），无需额外配置。
+
+**注意**：iOS 端的 bundle 加载实现可能需要根据你的具体需求调整。当前模板提供了基础框架。
+
+## 初始化多 Bundle 系统
+
+在应用入口（通常是 `App.tsx`）中初始化：
+
+```typescript
+import React, { useEffect, useState } from 'react';
+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({
+        // 模块路径规则（glob 模式）
+        modulePaths: ['src/modules/**'],
+        
+        // 共享依赖路径
+        sharedDependencies: [
+          'node_modules/@bm-fe/react-native-multi-bundle/**',
+          'src/navigation/**'
+        ],
+        
+        // Manifest 提供者（可选，默认使用 LocalBundleManager）
+        manifestProvider: async () => {
+          return await LocalBundleManager.getCurrentBundleManifest();
+        },
+        
+        // 预加载模块列表（可选）
+        preloadModules: ['settings'],
+        
+        // 开发服务器配置（可选）
+        devServer: {
+          host: Platform.OS === 'android' ? '10.0.2.2' : 'localhost',
+          port: 8081,
+        },
+        
+        // 错误处理回调（可选）
+        onError: (error) => {
+          console.error('MultiBundle error:', error);
+        },
+      });
+
+      if (result.success) {
+        setReady(true);
+      }
+    }
+
+    bootstrap();
+  }, []);
+
+  if (!ready) {
+    return <LoadingScreen />;
+  }
+
+  // ... 其余代码
+}
+```
+
+## 配置模块
+
+### 1. 创建 multi-bundle.config.json
+
+将 `templates/multi-bundle.config.json.template` 复制到项目根目录，重命名为 `multi-bundle.config.json`。
+
+### 2. 配置模块
+
+编辑 `multi-bundle.config.json`：
+
+```json
+{
+  "formatVersion": 1,
+  "platforms": ["ios", "android"],
+  "main": {
+    "entry": "src/main-entry.tsx",
+    "version": "1.0.0"
+  },
+  "modules": [
+    {
+      "id": "home",
+      "entry": "src/modules/Home/index.ts",
+      "version": "1.0.0",
+      "dependencies": [],
+      "lazy": true
+    }
+  ]
+}
+```
+
+### 3. 创建模块入口文件
+
+每个模块需要有一个入口文件，例如 `src/modules/Home/index.ts`：
+
+```typescript
+import HomeScreen from './HomeScreen';
+
+const exports = {
+  routes: {
+    Home: HomeScreen,
+  },
+  components: {
+    HomeScreen,
+  },
+};
+
+// 注册模块
+const ModuleRegistry = globalThis.__ModuleRegistry;
+if (ModuleRegistry) {
+  ModuleRegistry.registerModule('home', exports);
+}
+
+export default exports;
+```
+
+## 构建多 Bundle
+
+### 使用 npm 脚本
+
+在 `package.json` 中添加：
+
+```json
+{
+  "scripts": {
+    "bundle:ios": "node node_modules/@bm-fe/react-native-multi-bundle/scripts/build-multi-bundle.js ios",
+    "bundle:android": "node node_modules/@bm-fe/react-native-multi-bundle/scripts/build-multi-bundle.js android",
+    "bundle:ios:prod": "node node_modules/@bm-fe/react-native-multi-bundle/scripts/build-multi-bundle.js ios --env production",
+    "bundle:android:prod": "node node_modules/@bm-fe/react-native-multi-bundle/scripts/build-multi-bundle.js android --env production"
+  }
+}
+```
+
+### 使用 CLI 命令
+
+如果全局安装了包：
+
+```bash
+multi-bundle-build ios
+multi-bundle-build android --env production
+```
+
+### 构建产物
+
+构建完成后，产物位于 `build/bundles/<platform>/` 目录：
+
+- 主 bundle：`index.android.bundle` (Android) 或 `main.jsbundle` (iOS)
+- 模块 bundle：`modules/<moduleId>.bundle` (Android) 或 `modules/<moduleId>.jsbundle` (iOS)
+- Manifest：`bundle-manifest.json`
+
+## 使用模块路由
+
+### 方式一：使用 createModuleRouteLoader（推荐）
+
+```typescript
+import { createModuleRouteLoader } from '@bm-fe/react-native-multi-bundle';
+
+// 创建路由加载器
+export const createHomeScreen = createModuleRouteLoader('home', 'Home');
+
+// 在 React Navigation 中使用
+<Stack.Screen name="Home" getComponent={createHomeScreen} />
+```
+
+### 方式二：使用路由注册系统
+
+```typescript
+import { registerModuleRoute, getModuleRoute } from '@bm-fe/react-native-multi-bundle';
+
+// 注册路由
+registerModuleRoute('home', 'Home');
+
+// 获取路由组件
+const HomeScreen = getModuleRoute('home', 'Home');
+```
+
+## 常见问题
+
+### 1. 模块加载失败
+
+- 检查 manifest 是否正确配置
+- 确认模块 ID 与 manifest 中的 ID 一致
+- 查看控制台错误信息
+
+### 2. Metro 构建问题
+
+- 确认 `metro.config.js` 配置正确
+- 检查模块路径规则是否匹配实际路径
+- 清除 Metro 缓存：`npx react-native start --reset-cache`
+
+### 3. Native 模块未找到
+
+- 确认已正确注册 ModuleLoaderPackage
+- 检查包名是否正确
+- 重新构建原生应用
+
+### 4. 开发环境问题
+
+- 确认开发服务器正在运行
+- 检查 `devServer` 配置是否正确
+- 验证 manifest URL 是否可访问
+
+## 更多信息
+
+- [API 参考](./src/multi-bundle/README.md)
+- [示例应用](./examples/demo-app/README.md)
+- [模块开发规范](./docs/模块%20Bundle%20开发规范.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 @bm-fe/react-native-multi-bundle
+
+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,240 @@
+# @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} />
+```
+
+## 完整集成指南
+
+详细的集成步骤请参考：[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！

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@bm-fe/react-native-multi-bundle",
+  "version": "1.0.0-beta.0",
+  "description": "React Native 多 Bundle 系统 - 支持模块按需加载和独立更新",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.ts",
+  "author": "Max",
+  "license": "MIT",
+  "keywords": [
+    "react-native",
+    "multi-bundle",
+    "code-splitting",
+    "lazy-loading",
+    "module-loader",
+    "bundle",
+    "dynamic-loading"
+  ],
+  "files": [
+    "src",
+    "scripts",
+    "templates",
+    "README.md",
+    "INTEGRATION.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "multi-bundle-build": "./scripts/build-multi-bundle.js"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "test": "jest",
+    "version": "standard-version",
+    "version:patch": "standard-version --release-as patch",
+    "version:minor": "standard-version --release-as minor",
+    "version:major": "standard-version --release-as major",
+    "version:beta": "npm version prerelease --preid=beta --no-git-tag-version",
+    "publish:beta": "npm publish --tag beta",
+    "release:beta": "npm run version:beta && npm run publish:beta",
+    "release": "npm run version && npm publish"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0"
+  },
+  "dependencies": {
+    "@react-navigation/native": "^7.1.21",
+    "@react-navigation/native-stack": "^7.6.4",
+    "react-native-fs": "^2.20.0",
+    "react-native-safe-area-context": "^5.6.2",
+    "react-native-screens": "^4.18.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/runtime": "^7.28.4",
+    "@react-native-community/cli": "20.0.2",
+    "@react-native-community/cli-platform-android": "20.0.2",
+    "@react-native-community/cli-platform-ios": "20.0.2",
+    "@react-native/babel-preset": "0.82.1",
+    "@react-native/eslint-config": "0.82.1",
+    "@react-native/metro-config": "0.82.1",
+    "@react-native/typescript-config": "0.82.1",
+    "@rnx-kit/babel-preset-metro-react-native": "^3.0.0",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.6",
+    "@types/react-test-renderer": "^19.1.0",
+    "babel-jest": "^30.2.0",
+    "babel-plugin-transform-inline-environment-variables": "^0.4.4",
+    "eslint": "^9.39.1",
+    "jest": "^30.2.0",
+    "patch-package": "^8.0.1",
+    "postinstall-postinstall": "^2.1.0",
+    "prettier": "3.6.2",
+    "react-test-renderer": "^19.1.1",
+    "standard-version": "^9.5.0",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}