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

package/src/multi-bundle/routeRegistry.ts

@@ -0,0 +1,118 @@
+/**
+ * routeRegistry - 路由注册系统
+ * 支持动态路由注册，避免硬编码导入
+ */
+
+import React from 'react';
+import { ModuleRegistry } from './ModuleRegistry';
+import { createModuleRouteLoader } from './createModuleRouteLoader';
+
+/**
+ * 路由注册表
+ * 存储已注册的路由组件
+ */
+const routeRegistry: Map<string, React.ComponentType<any>> = new Map();
+
+/**
+ * 路由键格式：`${moduleId}:${routeKey}`
+ */
+function getRouteKey(moduleId: string, routeKey: string): string {
+  return `${moduleId}:${routeKey}`;
+}
+
+/**
+ * 注册模块路由
+ * 
+ * @param moduleId 模块 ID
+ * @param routeKey 路由 key（对应模块 exports.routes[routeKey]）
+ * @param component 路由组件（可选，如果不提供则使用 createModuleRouteLoader 自动生成延迟加载组件）
+ * 
+ * @example
+ * ```typescript
+ * // 方式1：自动从模块 exports 中提取（延迟加载）
+ * registerModuleRoute('home', 'Home');
+ * 
+ * // 方式2：手动提供组件
+ * registerModuleRoute('home', 'Home', MyHomeComponent);
+ * ```
+ */
+export function registerModuleRoute(
+  moduleId: string,
+  routeKey: string,
+  component?: React.ComponentType<any>
+): React.ComponentType<any> {
+  const key = getRouteKey(moduleId, routeKey);
+  
+  if (component) {
+    // 直接注册提供的组件
+    routeRegistry.set(key, component);
+    return component;
+  } else {
+    // 使用 createModuleRouteLoader 自动生成（延迟加载）
+    // 注意：这里返回的是组件，而不是加载器函数
+    // 为了兼容性，我们调用加载器函数获取组件
+    const createLoader = createModuleRouteLoader(moduleId, routeKey);
+    const lazyComponent = createLoader();
+    routeRegistry.set(key, lazyComponent);
+    return lazyComponent;
+  }
+}
+
+/**
+ * 获取已注册的路由组件
+ * 
+ * @param moduleId 模块 ID
+ * @param routeKey 路由 key
+ * @returns 路由组件，如果未注册则返回 undefined
+ */
+export function getModuleRoute(
+  moduleId: string,
+  routeKey: string
+): React.ComponentType<any> | undefined {
+  const key = getRouteKey(moduleId, routeKey);
+  return routeRegistry.get(key);
+}
+
+/**
+ * 检查路由是否已注册
+ */
+export function hasModuleRoute(moduleId: string, routeKey: string): boolean {
+  const key = getRouteKey(moduleId, routeKey);
+  return routeRegistry.has(key);
+}
+
+/**
+ * 批量注册路由
+ * 
+ * @param routes 路由配置数组
+ * 
+ * @example
+ * ```typescript
+ * registerRoutes([
+ *   { moduleId: 'home', routeKey: 'Home' },
+ *   { moduleId: 'details', routeKey: 'Details' },
+ * ]);
+ * ```
+ */
+export function registerRoutes(
+  routes: Array<{ moduleId: string; routeKey: string; component?: React.ComponentType<any> }>
+): void {
+  routes.forEach(({ moduleId, routeKey, component }) => {
+    registerModuleRoute(moduleId, routeKey, component);
+  });
+}
+
+/**
+ * 清除所有已注册的路由（主要用于测试）
+ */
+export function clearRoutes(): void {
+  routeRegistry.clear();
+}
+
+/**
+ * 获取所有已注册的路由键
+ */
+export function getAllRouteKeys(): string[] {
+  return Array.from(routeRegistry.keys());
+}
+

package/src/types/global.d.ts

@@ -0,0 +1,14 @@
+import { ModuleRegistry } from '../multi-bundle/ModuleRegistry';
+export {};
+
+declare global {
+  var __ModuleRegistry: typeof ModuleRegistry;
+  
+  // React Native 环境中的 process.env 类型定义
+  namespace NodeJS {
+    interface ProcessEnv {
+      MODULE_DEBUG?: string;
+      NODE_ENV?: 'development' | 'production' | 'test';
+    }
+  }
+}

package/templates/metro.config.js.template

@@ -0,0 +1,45 @@
+/**
+ * Metro 配置模板
+ * 
+ * 使用说明：
+ * 1. 将此文件复制到你的项目根目录，重命名为 metro.config.js
+ * 2. 根据你的项目结构调整 modulePaths 和 sharedDependencies
+ * 3. 确保已安装 @bm-fe/react-native-multi-bundle
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+const baseJSBundle = require('metro/private/DeltaBundler/Serializers/baseJSBundle');
+const bundleToString = require('metro/private/lib/bundleToString');
+const {
+  getConfigFromEnv,
+  isModulePath: isModulePathHelper,
+  isSharedDependencyPath: isSharedDependencyPathHelper,
+  extractModuleNameFromPath: extractModuleNameFromPathHelper,
+  extractModuleNameFromEntry: extractModuleNameFromEntryHelper,
+} = require('@bm-fe/react-native-multi-bundle/src/multi-bundle/metro-config-helper');
+
+const projectRoot = __dirname;
+const defaultConfig = getDefaultConfig(__dirname);
+
+// ⚠️ 重要：根据你的项目结构调整以下配置
+const MULTI_BUNDLE_CONFIG_FILE = path.join(projectRoot, 'multi-bundle.config.json');
+
+// 通过环境变量或默认值配置模块路径和共享依赖
+// 也可以通过环境变量覆盖：
+// RN_MULTI_BUNDLE_MODULE_PATHS='["src/modules/**"]'
+// RN_MULTI_BUNDLE_SHARED_DEPS='["src/multi-bundle/**","src/navigation/**"]'
+const multiBundleConfig = getConfigFromEnv();
+const modulePaths = multiBundleConfig.modulePaths || ['src/modules/**'];
+const sharedDependencies = multiBundleConfig.sharedDependencies || [
+  'node_modules/@bm-fe/react-native-multi-bundle/**',
+  'src/navigation/**'
+];
+
+// ... 其余配置代码与主 metro.config.js 相同
+// 请参考 @bm-fe/react-native-multi-bundle 的完整实现
+
+module.exports = mergeConfig(defaultConfig, {
+  // 你的自定义配置
+});

package/templates/multi-bundle.config.json.template

@@ -0,0 +1,31 @@
+{
+  "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
+    },
+    {
+      "id": "details",
+      "entry": "src/modules/Details/index.ts",
+      "version": "1.0.0",
+      "dependencies": [],
+      "lazy": true
+    },
+    {
+      "id": "settings",
+      "entry": "src/modules/Settings/index.ts",
+      "version": "1.0.0",
+      "dependencies": [],
+      "lazy": true
+    }
+  ]
+}

package/templates/native/android/ModuleLoaderModule.kt

@@ -0,0 +1,227 @@
+package com.yourpackage  // ⚠️ 修改为你的包名
+
+import android.util.Log
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.JSBundleLoader
+import com.facebook.react.module.annotations.ReactModule
+
+/**
+ * ModuleLoader Native 模块
+ * 用于在 React Native 运行时中动态加载子 bundle
+ * 
+ * 支持新架构（ReactHostImpl）和旧架构（CatalystInstance）
+ * 
+ * 集成步骤：
+ * 1. 将此文件复制到你的 Android 项目的 java/com/yourpackage/ 目录
+ * 2. 修改包名为你的实际包名
+ * 3. 在 MainApplication.kt 中注册 ModuleLoaderPackage
+ */
+@ReactModule(name = ModuleLoaderModule.NAME)
+class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+
+    companion object {
+        const val NAME = "ModuleLoader"
+        private const val TAG = "ModuleLoaderModule"
+        
+        // 缓存反射获取的类和方法，避免重复反射
+        private var reactHostImplClass: Class<*>? = null
+        private var reactInstanceClass: Class<*>? = null
+        
+        init {
+            try {
+                reactHostImplClass = Class.forName("com.facebook.react.runtime.ReactHostImpl")
+                reactInstanceClass = Class.forName("com.facebook.react.runtime.ReactInstance")
+            } catch (e: ClassNotFoundException) {
+                Log.w(TAG, "New architecture classes not found, will use old architecture")
+            }
+        }
+    }
+
+    // 记录已加载的 bundle，避免重复加载
+    private val loadedBundles = mutableSetOf<String>()
+
+    override fun getName(): String = NAME
+
+    /**
+     * 加载子 bundle
+     * 
+     * @param bundleId 模块 ID（如 "home", "details", "settings"）
+     * @param bundlePath bundle 文件路径（如 "modules/home.bundle"）
+     * @param promise 加载结果回调
+     */
+    @ReactMethod
+    fun loadBusinessBundle(bundleId: String, bundlePath: String, promise: Promise) {
+        Log.d(TAG, "loadBusinessBundle: bundleId=$bundleId, bundlePath=$bundlePath")
+
+        // 已经加载过的 bundle，直接返回成功
+        if (loadedBundles.contains(bundleId)) {
+            Log.d(TAG, "Bundle already loaded: $bundleId")
+            val result = Arguments.createMap().apply {
+                putBoolean("success", true)
+            }
+            promise.resolve(result)
+            return
+        }
+
+        try {
+            // 获取 ReactApplication
+            val application = reactContext.applicationContext as? android.app.Application
+            val reactApplication = application as? com.facebook.react.ReactApplication
+            
+            if (reactApplication == null) {
+                Log.e(TAG, "Application is not a ReactApplication")
+                val result = Arguments.createMap().apply {
+                    putBoolean("success", false)
+                    putString("errorMessage", "Application is not a ReactApplication")
+                }
+                promise.resolve(result)
+                return
+            }
+
+            val reactHost = reactApplication.reactHost
+            
+            // 构建 assets 路径
+            val assetUrl = "assets://$bundlePath"
+            Log.d(TAG, "Loading bundle from: $assetUrl")
+
+            // 创建 JSBundleLoader
+            val bundleLoader = JSBundleLoader.createAssetLoader(
+                reactContext,
+                assetUrl,
+                false  // 异步加载
+            )
+
+            // 检查是否是新架构（ReactHostImpl）
+            val hostImplClass = reactHostImplClass
+            if (reactHost != null && hostImplClass != null && hostImplClass.isInstance(reactHost)) {
+                loadBundleViaReflection(reactHost, bundleLoader, bundleId, promise)
+            } else {
+                // 旧架构回退方案：使用 CatalystInstance
+                Log.d(TAG, "Falling back to CatalystInstance (old architecture)")
+                loadBundleWithCatalystInstance(bundleId, bundlePath, promise)
+            }
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to load bundle: $bundleId", e)
+            val result = Arguments.createMap().apply {
+                putBoolean("success", false)
+                putString("errorMessage", e.message ?: "Unknown error")
+            }
+            promise.resolve(result)
+        }
+    }
+
+    /**
+     * 新架构方案：完全通过反射获取 ReactInstance 并加载 bundle
+     */
+    private fun loadBundleViaReflection(
+        reactHost: Any,
+        bundleLoader: JSBundleLoader,
+        bundleId: String,
+        promise: Promise
+    ) {
+        try {
+            val hostImplClass = reactHostImplClass ?: throw Exception("ReactHostImpl class not found")
+            val instanceClass = reactInstanceClass ?: throw Exception("ReactInstance class not found")
+            
+            // 通过反射获取 private 的 reactInstance 字段
+            val reactInstanceField = hostImplClass.getDeclaredField("reactInstance")
+            reactInstanceField.isAccessible = true
+            val reactInstance = reactInstanceField.get(reactHost)
+            
+            if (reactInstance == null) {
+                Log.e(TAG, "ReactInstance is null")
+                val result = Arguments.createMap().apply {
+                    putBoolean("success", false)
+                    putString("errorMessage", "ReactInstance not available")
+                }
+                promise.resolve(result)
+                return
+            }
+
+            // 通过反射调用 ReactInstance.loadJSBundle 方法
+            val loadJSBundleMethod = instanceClass.getMethod("loadJSBundle", JSBundleLoader::class.java)
+            loadJSBundleMethod.invoke(reactInstance, bundleLoader)
+            
+            // 标记为已加载
+            loadedBundles.add(bundleId)
+            Log.d(TAG, "Bundle loaded successfully via ReactInstance: $bundleId")
+
+            val result = Arguments.createMap().apply {
+                putBoolean("success", true)
+            }
+            promise.resolve(result)
+            
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to load bundle via ReactInstance: $bundleId", e)
+            val result = Arguments.createMap().apply {
+                putBoolean("success", false)
+                putString("errorMessage", e.message ?: "Unknown error")
+            }
+            promise.resolve(result)
+        }
+    }
+
+    /**
+     * 旧架构回退方案：使用 CatalystInstance 加载 bundle
+     */
+    @Suppress("DEPRECATION")
+    private fun loadBundleWithCatalystInstance(bundleId: String, bundlePath: String, promise: Promise) {
+        try {
+            val catalystInstance = reactContext.catalystInstance
+            if (catalystInstance == null) {
+                Log.e(TAG, "CatalystInstance is null")
+                val result = Arguments.createMap().apply {
+                    putBoolean("success", false)
+                    putString("errorMessage", "CatalystInstance not available")
+                }
+                promise.resolve(result)
+                return
+            }
+
+            val assetPath = "assets://$bundlePath"
+            catalystInstance.loadScriptFromAssets(
+                reactContext.assets,
+                assetPath,
+                false
+            )
+
+            loadedBundles.add(bundleId)
+            Log.d(TAG, "Bundle loaded successfully via CatalystInstance: $bundleId")
+
+            val result = Arguments.createMap().apply {
+                putBoolean("success", true)
+            }
+            promise.resolve(result)
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to load bundle via CatalystInstance: $bundleId", e)
+            val result = Arguments.createMap().apply {
+                putBoolean("success", false)
+                putString("errorMessage", e.message ?: "Unknown error")
+            }
+            promise.resolve(result)
+        }
+    }
+
+    /**
+     * 检查 bundle 是否已加载
+     */
+    @ReactMethod
+    fun isBundleLoaded(bundleId: String, promise: Promise) {
+        promise.resolve(loadedBundles.contains(bundleId))
+    }
+
+    /**
+     * 获取已加载的 bundle 列表
+     */
+    @ReactMethod
+    fun getLoadedBundles(promise: Promise) {
+        val array = Arguments.createArray()
+        loadedBundles.forEach { array.pushString(it) }
+        promise.resolve(array)
+    }
+}

package/templates/native/android/ModuleLoaderPackage.kt

@@ -0,0 +1,26 @@
+package com.yourpackage  // ⚠️ 修改为你的包名
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * ModuleLoader ReactPackage
+ * 注册 ModuleLoaderModule 到 React Native
+ * 
+ * 集成步骤：
+ * 1. 将此文件复制到你的 Android 项目的 java/com/yourpackage/ 目录
+ * 2. 修改包名为你的实际包名
+ * 3. 在 MainApplication.kt 的 getPackages() 方法中添加：
+ *    packages.add(ModuleLoaderPackage())
+ */
+class ModuleLoaderPackage : ReactPackage {
+    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+        return listOf(ModuleLoaderModule(reactContext))
+    }
+
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}

package/templates/native/ios/ModuleLoaderModule.h

@@ -0,0 +1,13 @@
+#import <React/RCTBridgeModule.h>
+
+/**
+ * ModuleLoader iOS Native 模块
+ * 
+ * 集成步骤：
+ * 1. 将此文件添加到你的 iOS 项目
+ * 2. 在 Xcode 中创建对应的 .m 实现文件
+ * 3. 在 AppDelegate.m 中注册模块
+ */
+@interface ModuleLoaderModule : NSObject <RCTBridgeModule>
+
+@end

package/templates/native/ios/ModuleLoaderModule.m

@@ -0,0 +1,60 @@
+#import "ModuleLoaderModule.h"
+#import <React/RCTBridge.h>
+#import <React/RCTBundleURLProvider.h>
+
+/**
+ * ModuleLoader iOS Native 模块实现
+ * 
+ * 注意：iOS 端的 bundle 加载方式与 Android 不同
+ * 这里提供一个基础实现，你可能需要根据实际需求调整
+ */
+@implementation ModuleLoaderModule
+
+RCT_EXPORT_MODULE(ModuleLoader);
+
+// 记录已加载的 bundle
+static NSMutableSet<NSString *> *loadedBundles;
+
++ (void)initialize {
+    if (self == [ModuleLoaderModule class]) {
+        loadedBundles = [NSMutableSet set];
+    }
+}
+
+RCT_EXPORT_METHOD(loadBusinessBundle:(NSString *)bundleId
+                  bundlePath:(NSString *)bundlePath
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+    // 检查是否已加载
+    if ([loadedBundles containsObject:bundleId]) {
+        resolve(@{@"success": @YES});
+        return;
+    }
+    
+    // TODO: 实现 iOS bundle 加载逻辑
+    // iOS 端的 bundle 加载方式与 Android 不同
+    // 你可能需要使用 RCTBridge 的相关 API 来加载 bundle
+    
+    NSLog(@"[ModuleLoader] Loading bundle: %@ from %@", bundleId, bundlePath);
+    
+    // 标记为已加载
+    [loadedBundles addObject:bundleId];
+    
+    resolve(@{@"success": @YES});
+}
+
+RCT_EXPORT_METHOD(isBundleLoaded:(NSString *)bundleId
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+    resolve(@([loadedBundles containsObject:bundleId]));
+}
+
+RCT_EXPORT_METHOD(getLoadedBundles:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+    resolve([loadedBundles allObjects]);
+}
+
+@end