@react-native/dev-middleware 0.73.0

package/README.md

@@ -0,0 +1,11 @@
+# @react-native/dev-middleware
+
+![https://img.shields.io/npm/v/@react-native/dev-middleware?color=brightgreen&label=npm%20package](https://www.npmjs.com/package/@react-native/dev-middleware)
+
+Dev server middleware supporting core React Native development features. This package is preconfigured in all React Native projects.
+
+## Endpoints
+
+### `/open-debugger`
+
+Open the JavaScript debugger for a given CDP target (direct Hermes debugging).

package/dist/createDevMiddleware.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.default = createDevMiddleware;
+var _connect = _interopRequireDefault(require("connect"));
+var _openDebuggerMiddleware = _interopRequireDefault(
+  require("./middleware/openDebuggerMiddleware")
+);
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
+/**
+ * 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
+ * @oncall react_native
+ */
+
+function createDevMiddleware({ logger } = {}) {
+  const middleware = (0, _connect.default)().use(
+    "/open-debugger",
+    (0, _openDebuggerMiddleware.default)({
+      logger,
+    })
+  );
+  return {
+    middleware,
+  };
+}

package/dist/createDevMiddleware.js.flow

@@ -0,0 +1,31 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+import type {NextHandleFunction} from 'connect';
+import type {Logger} from './types/Logger';
+
+import connect from 'connect';
+import openDebuggerMiddleware from './middleware/openDebuggerMiddleware';
+
+type Options = $ReadOnly<{
+  logger?: Logger,
+}>;
+
+export default function createDevMiddleware({logger}: Options = {}): {
+  middleware: NextHandleFunction,
+} {
+  const middleware = connect().use(
+    '/open-debugger',
+    openDebuggerMiddleware({logger}),
+  );
+
+  return {middleware};
+}

package/dist/index.flow.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+Object.defineProperty(exports, "createDevMiddleware", {
+  enumerable: true,
+  get: function () {
+    return _createDevMiddleware.default;
+  },
+});
+var _createDevMiddleware = _interopRequireDefault(
+  require("./createDevMiddleware")
+);
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}

package/dist/index.flow.js.flow

@@ -0,0 +1,12 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+export {default as createDevMiddleware} from './createDevMiddleware';

package/dist/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("./index.flow");

package/dist/index.js.flow

@@ -0,0 +1,20 @@
+/**
+ * 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
+ * @oncall react_native
+ */
+
+/*::
+export type * from './index.flow';
+*/
+
+if (!process.env.BUILD_EXCLUDE_BABEL_REGISTER) {
+  require('../../../scripts/build/babel-register').registerForMonorepo();
+}
+
+module.exports = require('./index.flow');

package/dist/middleware/openDebuggerMiddleware.js

@@ -0,0 +1,82 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.default = openDebuggerMiddleware;
+var _url = _interopRequireDefault(require("url"));
+var _getDevServerUrl = _interopRequireDefault(
+  require("../utils/getDevServerUrl")
+);
+var _launchChromeDevTools = _interopRequireDefault(
+  require("../utils/launchChromeDevTools")
+);
+var _queryInspectorTargets = _interopRequireDefault(
+  require("../utils/queryInspectorTargets")
+);
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
+/**
+ * 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
+ * @oncall react_native
+ */
+
+const debuggerInstances = new Map();
+/**
+ * Open the JavaScript debugger for a given CDP target (direct Hermes debugging).
+ *
+ * Currently supports Hermes targets, opening debugger websocket URL in Chrome
+ * DevTools.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/
+ */
+function openDebuggerMiddleware({ logger }) {
+  return async (req, res, next) => {
+    if (req.method === "POST") {
+      const { query } = _url.default.parse(req.url, true);
+      const { appId } = query;
+      if (typeof appId !== "string") {
+        res.writeHead(400);
+        res.end();
+        return;
+      }
+      const targets = await (0, _queryInspectorTargets.default)(
+        (0, _getDevServerUrl.default)(req)
+      );
+      const target = targets.find((_target) => _target.description === appId);
+      if (!target) {
+        res.writeHead(404);
+        res.end("Unable to find Chrome DevTools inspector target");
+        logger?.warn(
+          "No compatible apps connected. JavaScript debugging can only be used with the Hermes engine."
+        );
+        return;
+      }
+      try {
+        logger?.info("Launching JS debugger...");
+        debuggerInstances.get(appId)?.kill();
+        debuggerInstances.set(
+          appId,
+          await (0, _launchChromeDevTools.default)(target.webSocketDebuggerUrl)
+        );
+        res.end();
+        return;
+      } catch (e) {
+        logger?.error(
+          "Error launching JS debugger: " + e.message ?? "Unknown error"
+        );
+        res.writeHead(500);
+        res.end();
+        return;
+      }
+    }
+    next();
+  };
+}

package/dist/middleware/openDebuggerMiddleware.js.flow

@@ -0,0 +1,87 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+import type {LaunchedChrome} from 'chrome-launcher';
+import type {NextHandleFunction} from 'connect';
+import type {IncomingMessage, ServerResponse} from 'http';
+import type {Logger} from '../types/Logger';
+
+import url from 'url';
+import getDevServerUrl from '../utils/getDevServerUrl';
+import launchChromeDevTools from '../utils/launchChromeDevTools';
+import queryInspectorTargets from '../utils/queryInspectorTargets';
+
+const debuggerInstances = new Map<string, LaunchedChrome>();
+
+type Options = $ReadOnly<{
+  logger?: Logger,
+}>;
+
+/**
+ * Open the JavaScript debugger for a given CDP target (direct Hermes debugging).
+ *
+ * Currently supports Hermes targets, opening debugger websocket URL in Chrome
+ * DevTools.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/
+ */
+export default function openDebuggerMiddleware({
+  logger,
+}: Options): NextHandleFunction {
+  return async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: (err?: Error) => void,
+  ) => {
+    if (req.method === 'POST') {
+      const {query} = url.parse(req.url, true);
+      const {appId} = query;
+
+      if (typeof appId !== 'string') {
+        res.writeHead(400);
+        res.end();
+        return;
+      }
+
+      const targets = await queryInspectorTargets(getDevServerUrl(req));
+      const target = targets.find(_target => _target.description === appId);
+
+      if (!target) {
+        res.writeHead(404);
+        res.end('Unable to find Chrome DevTools inspector target');
+        logger?.warn(
+          'No compatible apps connected. JavaScript debugging can only be used with the Hermes engine.',
+        );
+        return;
+      }
+
+      try {
+        logger?.info('Launching JS debugger...');
+        debuggerInstances.get(appId)?.kill();
+        debuggerInstances.set(
+          appId,
+          await launchChromeDevTools(target.webSocketDebuggerUrl),
+        );
+        res.end();
+        return;
+      } catch (e) {
+        logger?.error(
+          'Error launching JS debugger: ' + e.message ?? 'Unknown error',
+        );
+        res.writeHead(500);
+        res.end();
+        return;
+      }
+    }
+
+    next();
+  };
+}

package/dist/types/Logger.js

@@ -0,0 +1 @@
+"use strict";

package/dist/types/Logger.js.flow

@@ -0,0 +1,17 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+export type Logger = $ReadOnly<{
+  error: (...message: Array<string>) => void,
+  info: (...message: Array<string>) => void,
+  warn: (...message: Array<string>) => void,
+  ...
+}>;

package/dist/utils/getDevServerUrl.js

@@ -0,0 +1,37 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.default = getDevServerUrl;
+var _net = _interopRequireDefault(require("net"));
+var _tls = require("tls");
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
+/**
+ * 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
+ * @oncall react_native
+ */
+
+/**
+ * Get the base URL to address the current development server.
+ */
+function getDevServerUrl(req) {
+  const scheme =
+    req.socket instanceof _tls.TLSSocket && req.socket.encrypted === true
+      ? "https"
+      : "http";
+  const { localAddress, localPort } = req.socket;
+  const address =
+    localAddress && _net.default.isIPv6(localAddress)
+      ? `[${localAddress}]`
+      : localAddress;
+  return `${scheme}:${address}:${localPort}`;
+}

package/dist/utils/getDevServerUrl.js.flow

@@ -0,0 +1,32 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+import type {IncomingMessage} from 'http';
+
+import net from 'net';
+import {TLSSocket} from 'tls';
+
+/**
+ * Get the base URL to address the current development server.
+ */
+export default function getDevServerUrl(req: IncomingMessage): string {
+  const scheme =
+    req.socket instanceof TLSSocket && req.socket.encrypted === true
+      ? 'https'
+      : 'http';
+  const {localAddress, localPort} = req.socket;
+  const address =
+    localAddress && net.isIPv6(localAddress)
+      ? `[${localAddress}]`
+      : localAddress;
+
+  return `${scheme}:${address}:${localPort}`;
+}

package/dist/utils/launchChromeDevTools.js

@@ -0,0 +1,44 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.default = launchChromeDevTools;
+var _launchDebuggerAppWindow = _interopRequireDefault(
+  require("./launchDebuggerAppWindow")
+);
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
+/**
+ * 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
+ * @oncall react_native
+ */
+
+/**
+ * The Chrome DevTools frontend revision to use. This should be set to the
+ * latest version known to be compatible with Hermes.
+ *
+ * Revision should be the full identifier from:
+ * https://chromium.googlesource.com/chromium/src.git
+ */
+const DEVTOOLS_FRONTEND_REV = "d9568d04d7dd79269c5a655d7ada69650c5a8336"; // Chrome 100.0.4896.75
+
+/**
+ * Attempt to launch Chrome DevTools on the host machine for a given CDP target.
+ */
+async function launchChromeDevTools(webSocketDebuggerUrl) {
+  const ws = webSocketDebuggerUrl.replace(/^ws:\/\//, "");
+  return (0, _launchDebuggerAppWindow.default)(
+    `${`https://chrome-devtools-frontend.appspot.com/serve_rev/@${DEVTOOLS_FRONTEND_REV}/devtools_app.html`}?panel=console&ws=${encodeURIComponent(
+      ws
+    )}`,
+    "open-debugger"
+  );
+}

package/dist/utils/launchChromeDevTools.js.flow

@@ -0,0 +1,38 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+import type {LaunchedChrome} from 'chrome-launcher';
+
+import launchDebuggerAppWindow from './launchDebuggerAppWindow';
+
+/**
+ * The Chrome DevTools frontend revision to use. This should be set to the
+ * latest version known to be compatible with Hermes.
+ *
+ * Revision should be the full identifier from:
+ * https://chromium.googlesource.com/chromium/src.git
+ */
+const DEVTOOLS_FRONTEND_REV = 'd9568d04d7dd79269c5a655d7ada69650c5a8336'; // Chrome 100.0.4896.75
+
+/**
+ * Attempt to launch Chrome DevTools on the host machine for a given CDP target.
+ */
+export default async function launchChromeDevTools(
+  webSocketDebuggerUrl: string,
+): Promise<LaunchedChrome> {
+  const urlBase = `https://chrome-devtools-frontend.appspot.com/serve_rev/@${DEVTOOLS_FRONTEND_REV}/devtools_app.html`;
+  const ws = webSocketDebuggerUrl.replace(/^ws:\/\//, '');
+
+  return launchDebuggerAppWindow(
+    `${urlBase}?panel=console&ws=${encodeURIComponent(ws)}`,
+    'open-debugger',
+  );
+}

package/dist/utils/launchDebuggerAppWindow.js

@@ -0,0 +1,58 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.default = launchDebuggerAppWindow;
+var _fs = require("fs");
+var _path = _interopRequireDefault(require("path"));
+var _tempDir = _interopRequireDefault(require("temp-dir"));
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
+/**
+ * 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
+ * @oncall react_native
+ */
+
+const ChromeLauncher = require("chrome-launcher");
+
+/**
+ * Attempt to open a debugger frontend URL as a Google Chrome app window.
+ */
+async function launchDebuggerAppWindow(
+  url,
+  /**
+   * Used to construct the temp browser dir to preserve settings such as window
+   * position.
+   */
+  intent
+) {
+  const userDataDir = await createTempDir(`react-native-${intent}-${"chrome"}`);
+  try {
+    return ChromeLauncher.launch({
+      chromeFlags: [
+        `--app=${url}`,
+        `--user-data-dir=${userDataDir}`,
+        "--window-size=1200,600",
+      ],
+    });
+  } catch (e) {
+    throw new Error(
+      "Unable to find a browser on the host to open the debugger. Supported browsers: Google Chrome"
+    );
+  }
+}
+async function createTempDir(dirName) {
+  const tempDir = _path.default.join(_tempDir.default, dirName);
+  await _fs.promises.mkdir(tempDir, {
+    recursive: true,
+  });
+  return tempDir;
+}

package/dist/utils/launchDebuggerAppWindow.js.flow

@@ -0,0 +1,56 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+import type {LaunchedChrome} from 'chrome-launcher';
+import {promises as fs} from 'fs';
+import path from 'path';
+import osTempDir from 'temp-dir';
+
+const ChromeLauncher = require('chrome-launcher');
+
+/**
+ * Attempt to open a debugger frontend URL as a Google Chrome app window.
+ */
+export default async function launchDebuggerAppWindow(
+  url: string,
+  /**
+   * Used to construct the temp browser dir to preserve settings such as window
+   * position.
+   */
+  intent: 'open-debugger',
+): Promise<LaunchedChrome> {
+  const browserType = 'chrome';
+  const userDataDir = await createTempDir(
+    `react-native-${intent}-${browserType}`,
+  );
+
+  try {
+    return ChromeLauncher.launch({
+      chromeFlags: [
+        `--app=${url}`,
+        `--user-data-dir=${userDataDir}`,
+        '--window-size=1200,600',
+      ],
+    });
+  } catch (e) {
+    throw new Error(
+      'Unable to find a browser on the host to open the debugger. Supported browsers: Google Chrome',
+    );
+  }
+}
+
+async function createTempDir(dirName: string): Promise<string> {
+  const tempDir = path.join(osTempDir, dirName);
+
+  await fs.mkdir(tempDir, {recursive: true});
+
+  return tempDir;
+}

package/dist/utils/queryInspectorTargets.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.default = queryInspectorTargets;
+var _nodeFetch = _interopRequireDefault(require("node-fetch"));
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
+/**
+ * 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
+ * @oncall react_native
+ */
+
+/**
+ * Get the list of available debug targets from the React Native dev server.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/
+ */
+async function queryInspectorTargets(devServerUrl) {
+  const res = await (0, _nodeFetch.default)(`${devServerUrl}/json/list`);
+  const apps = await res.json();
+
+  // Only use targets with better reloading support
+  return apps.filter(
+    (app) => app.title === "React Native Experimental (Improved Chrome Reloads)"
+  );
+}

package/dist/utils/queryInspectorTargets.js.flow

@@ -0,0 +1,40 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+import fetch from 'node-fetch';
+
+type ReactNativeCDPTarget = {
+  id: string,
+  description: string,
+  title: string,
+  type: string,
+  devtoolsFrontendUrl: string,
+  webSocketDebuggerUrl: string,
+  vm: string,
+  deviceName?: string,
+};
+
+/**
+ * Get the list of available debug targets from the React Native dev server.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/
+ */
+export default async function queryInspectorTargets(
+  devServerUrl: string,
+): Promise<ReactNativeCDPTarget[]> {
+  const res = await fetch(`${devServerUrl}/json/list`);
+  const apps = (await res.json(): Array<ReactNativeCDPTarget>);
+
+  // Only use targets with better reloading support
+  return apps.filter(
+    app => app.title === 'React Native Experimental (Improved Chrome Reloads)',
+  );
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@react-native/dev-middleware",
+  "version": "0.73.0",
+  "description": "Dev server middleware for React Native",
+  "keywords": ["react-native", "tools"],
+  "homepage": "https://github.com/facebook/react-native/tree/HEAD/packages/dev-middleware#readme",
+  "bugs": "https://github.com/facebook/react-native/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/react-native.git",
+    "directory": "packages/dev-middleware"
+  },
+  "license": "MIT",
+  "exports": { ".": "./dist/index.js", "./package.json": "./package.json" },
+  "files": ["dist"],
+  "dependencies": {
+    "chrome-launcher": "^0.15.2",
+    "connect": "^3.6.5",
+    "node-fetch": "^2.2.0",
+    "temp-dir": "^2.0.0"
+  },
+  "engines": { "node": ">=18" }
+}