@react-native/debugger-shell 0.81.0-nightly-20250531-cddfe4a03

package/README.md

@@ -0,0 +1,13 @@
+# @react-native/debugger-shell
+
+![npm package](https://img.shields.io/npm/v/@react-native/debugger-shell?color=brightgreen&label=npm%20package)
+
+Experimental Electron-based shell for React Native DevTools. This package is not part of React Native's public API.
+
+## Why Electron?
+
+The React Native DevTools frontend is based on Chrome DevTools, which is a web app, but is not particularly portable: it's designed to run in Chromium, and Chromium only. Prior to `@react-native/debugger-shell`, we would run it in [hosted mode](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/get_the_code.md#running-in-hosted-mode) in an instance of Chrome or Edge.
+
+Relying on hosted mode presents a variety of UX issues in the debugging workflow, such as the need to ask developers to install a particular browser before they can debug in React Native, and the inability to foreground/reuse existing debugger windows when relaunching the debugger for the same app. In order to address these issues effectively, we fundamentally need to leave the browser sandbox and run the debugger in a shell we can bundle with React Native, and whose behavior we can control.
+
+Electron is a tried-and-tested framework for the *specific* task of embedding a Chromium browser in a portable, customized shell. As a rule we'll hold a high bar for performance and reliability, and we'll only add features to the shell if they are strictly necessary to complement the DevTools frontend's built-in capabilities.

package/__tests__/electron-dependency-test.js

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+const semver = require('semver');
+
+// This test ensures that the electron dependency declared in our package.json
+// is semver-satisfied by the actual version of the electron package we're using.
+// While this is normally the job of a package manager like Yarn, in our case we
+// may use Yarn forced resolutions that defeat versioning, so we want additional
+// safety to ensure the target of the resolution is in sync with the declared dependency.
+describe('Electron dependency', () => {
+  test('should be semver-satisfied by the actual electron version', () => {
+    // $FlowIssue[untyped-import] - package.json is not typed
+    const ourPackageJson = require('../package.json');
+
+    const declaredElectronVersion = ourPackageJson.dependencies.electron;
+    expect(declaredElectronVersion).toBeTruthy();
+
+    // $FlowIssue[untyped-import] - package.json is not typed
+    const electronPackageJson = require('electron/package.json');
+
+    const actualElectronVersion = electronPackageJson.version;
+    expect(actualElectronVersion).toBeTruthy();
+
+    const isSatisfied = semver.satisfies(
+      actualElectronVersion,
+      declaredElectronVersion,
+    );
+
+    expect(isSatisfied).toBe(true);
+  });
+});

package/dist/electron/MainInstanceEntryPoint.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */

package/dist/electron/MainInstanceEntryPoint.js

@@ -0,0 +1,76 @@
+"use strict";
+
+const { BrowserWindow, app, shell } = require("electron");
+const util = require("util");
+const windowMetadata = new WeakMap();
+function handleLaunchArgs(argv) {
+  const {
+    values: { frontendUrl, windowKey },
+  } = util.parseArgs({
+    options: {
+      frontendUrl: {
+        type: "string",
+      },
+      windowKey: {
+        type: "string",
+      },
+    },
+    args: argv,
+  });
+  const existingWindow = BrowserWindow.getAllWindows().find((window) => {
+    const metadata = windowMetadata.get(window);
+    if (!metadata) {
+      return false;
+    }
+    return metadata.windowKey === windowKey;
+  });
+  if (existingWindow) {
+    if (existingWindow.isVisible()) {
+      existingWindow.flashFrame(true);
+      setTimeout(() => {
+        existingWindow.flashFrame(false);
+      }, 1000);
+    }
+    if (process.platform === "darwin") {
+      app.focus({
+        steal: true,
+      });
+    }
+    existingWindow.focus();
+    return;
+  }
+  const frontendWindow = new BrowserWindow({
+    width: 1200,
+    height: 600,
+    webPreferences: {
+      partition: "persist:react-native-devtools",
+    },
+  });
+  frontendWindow.webContents.setWindowOpenHandler(({ url }) => {
+    shell.openExternal(url);
+    return {
+      action: "deny",
+    };
+  });
+  frontendWindow.loadURL(frontendUrl);
+  windowMetadata.set(frontendWindow, {
+    windowKey,
+  });
+  if (process.platform === "darwin") {
+    app.focus({
+      steal: true,
+    });
+  }
+}
+app.whenReady().then(() => {
+  handleLaunchArgs(process.argv.slice(2));
+  app.on(
+    "second-instance",
+    (event, electronArgv, workingDirectory, additionalData) => {
+      handleLaunchArgs(additionalData.argv);
+    }
+  );
+});
+app.on("window-all-closed", function () {
+  app.quit();
+});

package/dist/electron/MainInstanceEntryPoint.js.flow

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */

package/dist/electron/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */

package/dist/electron/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+const { app } = require("electron");
+const gotTheLock = app.requestSingleInstanceLock({
+  argv: process.argv.slice(2),
+});
+if (!gotTheLock) {
+  app.quit();
+} else {
+  require("./MainInstanceEntryPoint.js");
+}

package/dist/electron/index.js.flow

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */

package/dist/node/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ * @format
+ */
+
+declare function unstable_spawnDebuggerShellWithArgs(
+  args: string[],
+  $$PARAM_1$$?: Readonly<{ mode?: "syncThenExit" | "detached" }>
+): Promise<void>;
+export { unstable_spawnDebuggerShellWithArgs };

package/dist/node/index.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.unstable_spawnDebuggerShellWithArgs =
+  unstable_spawnDebuggerShellWithArgs;
+const { spawn } = require("cross-spawn");
+async function unstable_spawnDebuggerShellWithArgs(
+  args,
+  { mode = "detached" } = {}
+) {
+  const electronPath = require("electron");
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      electronPath,
+      [require.resolve("../electron"), ...args],
+      {
+        stdio: "inherit",
+        windowsHide: true,
+        detached: mode === "detached",
+      }
+    );
+    if (mode === "detached") {
+      child.on("spawn", () => {
+        resolve();
+      });
+      child.on("close", (code) => {
+        if (code !== 0) {
+          reject(
+            new Error(
+              `Failed to open debugger shell: ${electronPath} exited with code ${code}`
+            )
+          );
+        }
+      });
+      child.unref();
+    } else if (mode === "syncThenExit") {
+      child.on("close", function (code, signal) {
+        if (code === null) {
+          console.error(electronPath, "exited with signal", signal);
+          process.exit(1);
+        }
+        process.exit(code);
+      });
+      const handleTerminationSignal = function (signal) {
+        process.on(signal, function signalHandler() {
+          if (!child.killed) {
+            child.kill(signal);
+          }
+        });
+      };
+      handleTerminationSignal("SIGINT");
+      handleTerminationSignal("SIGTERM");
+    }
+  });
+}

package/dist/node/index.js.flow

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+declare function unstable_spawnDebuggerShellWithArgs(
+  args: string[],
+  $$PARAM_1$$?: $ReadOnly<{
+    // In 'syncAndExit' mode, the current process will block until the spawned process exits, and then it will exit
+    // with the same exit code as the spawned process.
+    // In 'detached' mode, the spawned process will be detached from the current process and the current process will
+    // continue to run normally.
+    mode?: "syncThenExit" | "detached",
+  }>
+): Promise<void>;
+
+export { unstable_spawnDebuggerShellWithArgs };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@react-native/debugger-shell",
+  "version": "0.81.0-nightly-20250531-cddfe4a03",
+  "description": "Experimental debugger shell for React Native for use with @react-native/debugger-frontend",
+  "keywords": [
+    "react-native",
+    "tools"
+  ],
+  "homepage": "https://github.com/facebook/react-native/tree/HEAD/packages/debugger-shell#readme",
+  "bugs": "https://github.com/facebook/react-native/issues",
+  "main": "./dist/node/index.js",
+  "exports": {
+    ".": {
+      "node": "./dist/node/index.js",
+      "electron": "./dist/electron/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "electron src/electron"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facebook/react-native.git",
+    "directory": "packages/debugger-shell"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18",
+    "electron": ">=36.2.0"
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "electron": "36.2.0"
+  },
+  "devDependencies": {
+    "semver": "^7.1.3"
+  }
+}

package/src/electron/MainInstanceEntryPoint.js

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+// $FlowFixMe[unclear-type] We have no Flow types for the Electron API.
+const {BrowserWindow, app, shell} = require('electron') as any;
+const util = require('util');
+
+const windowMetadata = new WeakMap<
+  typeof BrowserWindow,
+  $ReadOnly<{
+    windowKey: string,
+  }>,
+>();
+
+function handleLaunchArgs(argv: string[]) {
+  const {
+    values: {frontendUrl, windowKey},
+  } = util.parseArgs({
+    options: {
+      frontendUrl: {
+        type: 'string',
+      },
+      windowKey: {
+        type: 'string',
+      },
+    },
+    args: argv,
+  });
+
+  // Find an existing window for this app and launch configuration.
+  const existingWindow = BrowserWindow.getAllWindows().find(window => {
+    const metadata = windowMetadata.get(window);
+    if (!metadata) {
+      return false;
+    }
+    return metadata.windowKey === windowKey;
+  });
+
+  if (existingWindow) {
+    // If the window is already visible, flash it.
+    if (existingWindow.isVisible()) {
+      existingWindow.flashFrame(true);
+      setTimeout(() => {
+        existingWindow.flashFrame(false);
+      }, 1000);
+    }
+    if (process.platform === 'darwin') {
+      app.focus({
+        steal: true,
+      });
+    }
+    existingWindow.focus();
+    return;
+  }
+
+  // Create the browser window.
+  const frontendWindow = new BrowserWindow({
+    width: 1200,
+    height: 600,
+    webPreferences: {
+      partition: 'persist:react-native-devtools',
+    },
+  });
+
+  // Open links in the default browser instead of in new Electron windows.
+  frontendWindow.webContents.setWindowOpenHandler(({url}) => {
+    shell.openExternal(url);
+    return {action: 'deny'};
+  });
+
+  frontendWindow.loadURL(frontendUrl);
+
+  windowMetadata.set(frontendWindow, {
+    windowKey,
+  });
+
+  if (process.platform === 'darwin') {
+    app.focus({
+      steal: true,
+    });
+  }
+}
+
+app.whenReady().then(() => {
+  handleLaunchArgs(process.argv.slice(2));
+
+  app.on(
+    'second-instance',
+    (event, electronArgv, workingDirectory, additionalData) => {
+      handleLaunchArgs(additionalData.argv);
+    },
+  );
+});
+
+app.on('window-all-closed', function () {
+  app.quit();
+});

package/src/electron/index.flow.js

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+// $FlowFixMe[unclear-type] We have no Flow types for the Electron API.
+const {app} = require('electron') as any;
+
+const gotTheLock = app.requestSingleInstanceLock({
+  argv: process.argv.slice(2),
+});
+
+if (!gotTheLock) {
+  app.quit();
+} else {
+  require('./MainInstanceEntryPoint.js');
+}

package/src/electron/index.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+/*::
+export type * from './index.flow';
+*/
+
+if (!process.env.BUILD_EXCLUDE_BABEL_REGISTER) {
+  require('../../../../scripts/babel-register').registerForMonorepo();
+}
+
+module.exports = require('./index.flow');

package/src/node/index.flow.js

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+const {spawn} = require('cross-spawn');
+
+async function unstable_spawnDebuggerShellWithArgs(
+  args: string[],
+  {
+    mode = 'detached',
+  }: $ReadOnly<{
+    // In 'syncAndExit' mode, the current process will block until the spawned process exits, and then it will exit
+    // with the same exit code as the spawned process.
+    // In 'detached' mode, the spawned process will be detached from the current process and the current process will
+    // continue to run normally.
+    mode?: 'syncThenExit' | 'detached',
+  }> = {},
+): Promise<void> {
+  // NOTE: Internally at Meta, this is aliased to a workspace that is
+  // API-compatible with the 'electron' package, but contains prebuilt binaries
+  // that do not need to be downloaded in a postinstall action.
+  const electronPath = require('electron');
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      electronPath,
+      [require.resolve('../electron'), ...args],
+      {
+        stdio: 'inherit',
+        windowsHide: true,
+        detached: mode === 'detached',
+      },
+    );
+    if (mode === 'detached') {
+      child.on('spawn', () => {
+        resolve();
+      });
+      child.on('close', (code /*: number */) => {
+        if (code !== 0) {
+          reject(
+            new Error(
+              `Failed to open debugger shell: ${electronPath} exited with code ${code}`,
+            ),
+          );
+        }
+      });
+      child.unref();
+    } else if (mode === 'syncThenExit') {
+      child.on('close', function (code, signal) {
+        if (code === null) {
+          console.error(electronPath, 'exited with signal', signal);
+          process.exit(1);
+        }
+        process.exit(code);
+      });
+
+      const handleTerminationSignal = function (signal: string) {
+        process.on(signal, function signalHandler() {
+          if (!child.killed) {
+            child.kill(signal);
+          }
+        });
+      };
+
+      handleTerminationSignal('SIGINT');
+      handleTerminationSignal('SIGTERM');
+    }
+  });
+}
+
+export {unstable_spawnDebuggerShellWithArgs};

package/src/node/index.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+/*::
+export type * from './index.flow';
+*/
+
+if (!process.env.BUILD_EXCLUDE_BABEL_REGISTER) {
+  require('../../../../scripts/babel-register').registerForMonorepo();
+}
+
+export * from './index.flow';