react-native-debug-toolkit 3.3.2 → 3.3.4

package/README.md

@@ -77,7 +77,46 @@ In the app, open Debug Panel -> `DevConnect` -> `Send Once` or `Start Live Sync`
 
 DevConnect auto-detects simulator/emulator and uses local host settings automatically. On real devices, enter your computer IP to connect.
 
-For Remote JS Bundle, run Metro on your computer, enter computer IP and Metro port in `DevConnect`, then tap `Use Metro Bundle`. DevConnect writes React Native's native dev-server host setting and reloads the app. The IP and ports are persisted through AsyncStorage when installed, or through the native module after rebuild.
+### Embedded Debug Bundle
+
+Debug builds need an embedded JS bundle for cold start when Metro is off.
+
+Bare React Native:
+
+```bash
+npx debug-toolkit setup-bundle
+git diff
+git commit -am "chore: enable debug bundle embedding"
+```
+
+Expo dev-client:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-debug-toolkit/dev-client", { "embedBundle": true }]
+    ]
+  }
+}
+```
+
+Verify built artifacts:
+
+```bash
+npx debug-toolkit doctor-bundle --platform ios --app path/to/App.app
+npx debug-toolkit doctor-bundle --platform android --apk path/to/app-debug.apk
+```
+
+After setup, build machines run normal Xcode, Gradle, React Native, or EAS commands. Do not run a separate mutation command on every build.
+
+For Remote JS Bundle, run Metro on your computer, enter computer IP and Metro port in `DevConnect`, then tap `Use Metro Bundle`. DevConnect persists the host and hot-reloads from Metro. Use **Reset** to go back to the embedded bundle.
+
+> **Debug builds only.** Metro host switching works in Debug builds. Release builds load the embedded bundle and the controls are disabled (`release: disabled` badge).
+
+**iOS — no AppDelegate changes required.** On install, DevConnect hooks `RCTBundleURLProvider` so the app **cold-starts from the embedded `main.jsbundle`** and only connects to Metro after you apply a host in the panel (fixes Expo `.expo/.virtual-metro-entry` red screens when Metro is off).
+
+The IP and ports are persisted through AsyncStorage when installed, or through the native module after rebuild.
 
 QR scan is optional. Install `react-native-camera-kit` or `expo-camera` in the app to enable the scan button. The app must request camera permission before scanning.
 

package/README.zh-CN.md

@@ -77,7 +77,46 @@ App 内打开 Debug Panel -> `DevConnect` -> `Send Once` 或 `Start Live Sync`
 
 DevConnect 自动识别模拟器/真机，模拟器下自动使用本机 Metro/daemon 地址。真机需输入电脑 IP 地址。
 
-Remote JS Bundle：先在电脑启动 Metro，在 `DevConnect` 输入电脑 IP 和 Metro 端口，然后点 `Use Metro Bundle`。DevConnect 会写入 React Native 原生 dev-server host 设置并 reload App。IP 和端口会通过 AsyncStorage 持久化；如果没装 AsyncStorage，则在重建后通过本库原生模块持久化。
+### Debug 包内置 Bundle
+
+Debug 包要在 Metro 关闭时冷启动，必须内置 JS bundle。
+
+Bare React Native:
+
+```bash
+npx debug-toolkit setup-bundle
+git diff
+git commit -am "chore: enable debug bundle embedding"
+```
+
+Expo dev-client:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-debug-toolkit/dev-client", { "embedBundle": true }]
+    ]
+  }
+}
+```
+
+验证产物：
+
+```bash
+npx debug-toolkit doctor-bundle --platform ios --app path/to/App.app
+npx debug-toolkit doctor-bundle --platform android --apk path/to/app-debug.apk
+```
+
+setup 后配置进仓库，打包机继续跑正常 Xcode、Gradle、React Native 或 EAS 命令。不要每次打包再跑额外修改命令。
+
+Remote JS Bundle：先在电脑启动 Metro，在 `DevConnect` 输入电脑 IP 和 Metro 端口，然后点 `Use Metro Bundle`。DevConnect 会持久化 host 并从 Metro 热重载。点 **Reset** 可回到内置 bundle。
+
+> **仅 Debug 包可用。** Release 包控件会显示 `release: disabled` 并禁用。
+
+**iOS — 无需改 AppDelegate。** 安装本库后会 hook `RCTBundleURLProvider`：**未配置 IP 时冷启动走内置 `main.jsbundle`**，只有在面板里应用 host 后才连 Metro（可避免 Metro 未开时的 `.expo/.virtual-metro-entry` 红屏）。
+
+IP 和端口会通过 AsyncStorage 持久化；如果没装 AsyncStorage，则在重建后通过本库原生模块持久化。
 
 扫码是可选能力。App 安装 `react-native-camera-kit` 或 `expo-camera` 后，DevConnect 才显示扫码按钮。App 仍需自己配置相机权限文案，并在使用扫码前申请相机权限。
 

package/app.plugin.js

@@ -0,0 +1,51 @@
+'use strict';
+
+function markTestConfig(config) {
+  config.extra = config.extra || {};
+  config.extra.reactNativeDebugToolkit = {
+    ...(config.extra.reactNativeDebugToolkit || {}),
+    embedBundle: true,
+  };
+  return config;
+}
+
+function loadConfigPlugins() {
+  try {
+    return require('@expo/config-plugins');
+  } catch {
+    throw new Error(
+      'react-native-debug-toolkit/dev-client requires @expo/config-plugins during Expo prebuild.',
+    );
+  }
+}
+
+function withDebugToolkitDevClient(config, props = {}) {
+  if (!props.embedBundle) {
+    return config;
+  }
+
+  if (props._testOnly) {
+    return markTestConfig(config);
+  }
+
+  const { withDangerousMod } = loadConfigPlugins();
+  const { setupIosBundle } = require('./scripts/bundle/ios');
+  const { setupAndroidBundle } = require('./scripts/bundle/android');
+
+  config = withDangerousMod(config, ['ios', async (modConfig) => {
+    setupIosBundle({
+      cwd: modConfig.modRequest.projectRoot,
+      iosTarget: props.iosTarget,
+    });
+    return modConfig;
+  }]);
+
+  config = withDangerousMod(config, ['android', async (modConfig) => {
+    setupAndroidBundle({ cwd: modConfig.modRequest.projectRoot });
+    return modConfig;
+  }]);
+
+  return config;
+}
+
+module.exports = withDebugToolkitDevClient;

package/bin/debug-toolkit.js

@@ -27,12 +27,19 @@ function hasHelpFlag(args) {
 function printHelp() {
   process.stderr.write(
     'Usage: debug-toolkit [--host 0.0.0.0] [--port 3799] [--token dev-token] [--store ~/.react-native-debug-toolkit/daemon-devices.json] [--daemon-only]\n'
+  + '       debug-toolkit setup-bundle [--platform ios|android] [--undo] [--check] [--ios-target <name>]\n'
+  + '       debug-toolkit doctor-bundle --platform ios --app <path-to.app>\n'
+  + '       debug-toolkit doctor-bundle --platform android --apk <path-to.apk>\n'
   + '\n'
   + 'Starts the debug toolkit: daemon (HTTP + Web Console) and MCP stdio server.\n'
   + '\n'
-  + 'Options:\n'
+  + 'Commands:\n'
+  + '  setup-bundle    Persistently configure host app debug builds to embed JS bundle\n'
+  + '  doctor-bundle   Verify source config or built app package contains embedded bundle\n'
+  + '\n'
+  + 'Daemon options:\n'
   + '  --host <addr>   Host to bind (default: 0.0.0.0)\n'
-    + '  --port <port>   Port to bind (default: 3799)\n'
+  + '  --port <port>   Port to bind (default: 3799)\n'
   + '  --token <str>   Auth token for daemon endpoints\n'
   + '  --store <path>  Device log store path\n'
   + '  --daemon-only   Start only the HTTP daemon and Web Console\n'
@@ -57,6 +64,15 @@ async function main() {
     return;
   }
 
+  if (['setup-bundle', 'doctor-bundle', 'embed'].includes(args[0])) {
+    const { runBundleCli } = require('../scripts/bundle/cli');
+    const code = await runBundleCli(args);
+    if (code !== 0) {
+      process.exitCode = code;
+    }
+    return;
+  }
+
   const host = readOption(args, '--host', process.env.DEBUG_TOOLKIT_DAEMON_HOST || DEFAULT_HOST);
   const port = Number(readOption(args, '--port', process.env.DEBUG_TOOLKIT_DAEMON_PORT || DEFAULT_PORT));
   const token = readOption(args, '--token', process.env.DEBUG_TOOLKIT_DAEMON_TOKEN || '');

package/dev-client.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./app.plugin');

package/ios/DebugToolkitDevConnect.h

@@ -0,0 +1,17 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Returns a Metro bundle URL when the user has applied a host via DevConnect; otherwise nil.
+
+ Zero-config: installing this pod hooks RCTBundleURLProvider so cold start uses the embedded
+ main.jsbundle until DevConnect applies a host. You do not need to change AppDelegate.
+
+ Optional override for custom bundleURL() implementations:
+
+     if let metro = DebugToolkitMetroBundleURL() { return metro }
+ */
+FOUNDATION_EXPORT NSURL * _Nullable DebugToolkitMetroBundleURL(void);
+
+NS_ASSUME_NONNULL_END