feat: configurable Metro port (#79)

Adds support for configuring the Metro port in Harness, including CLI overrides via `--metroPort`. Harness now also restores Android and iOS simulator Metro connection settings on cleanup so normal dev-mode launches keep working after a test run.

Author: mfazekas

.changeset/configurable-metro-port.md

@@ -0,0 +1,7 @@
+---
+'@react-native-harness/jest': patch
+'@react-native-harness/platform-android': patch
+'@react-native-harness/platform-apple': patch
+---
+
+Adds support for configuring the Metro port in Harness, including CLI overrides via `--metroPort`. Harness now also restores Android and iOS simulator Metro connection settings on cleanup so normal dev-mode launches keep working after a test run.

actions/shared/index.cjs

@@ -4209,6 +4209,7 @@ var coerce = {
 var NEVER = INVALID;
 
 // ../config/dist/types.js
+var DEFAULT_METRO_PORT = 8081;
 var RunnerSchema = external_exports.object({
   name: external_exports.string().min(1, "Runner name is required").regex(/^[a-zA-Z0-9._-]+$/, "Runner name can only contain alphanumeric characters, dots, underscores, and hyphens"),
   config: external_exports.record(external_exports.any()),
@@ -4221,6 +4222,7 @@ var ConfigSchema = external_exports.object({
   runners: external_exports.array(RunnerSchema).min(1, "At least one runner is required"),
   defaultRunner: external_exports.string().optional(),
   host: external_exports.string().min(1, "Host is required").optional(),
+  metroPort: external_exports.number().int("Metro port must be an integer").min(1, "Metro port must be at least 1").max(65535, "Metro port must be at most 65535").optional().default(DEFAULT_METRO_PORT),
   webSocketPort: external_exports.number().optional().default(3001),
   bridgeTimeout: external_exports.number().min(1e3, "Bridge timeout must be at least 1 second").default(6e4),
   /** @deprecated Removed in favor of crash supervisor. Accepted for backwards compatibility. */

packages/bundler-metro/src/constants.ts

@@ -6,7 +6,6 @@ import connect from 'connect';
 import nocache from 'nocache';
 import { isPortAvailable, getMetroPackage } from './utils.js';
 import { MetroPortUnavailableError } from './errors.js';
-import { METRO_PORT } from './constants.js';
 import type { MetroInstance, MetroOptions } from './types.js';
 import {
   type Reporter,
@@ -41,18 +40,19 @@ export const getMetroInstance = async (
   abortSignal: AbortSignal
 ): Promise<MetroInstance> => {
   const { projectRoot, harnessConfig } = options;
-  const isDefaultPortAvailable = await isPortAvailable(METRO_PORT);
+  const metroPort = harnessConfig.metroPort;
+  const isMetroPortAvailable = await isPortAvailable(metroPort);
 
-  if (!isDefaultPortAvailable) {
-    throw new MetroPortUnavailableError(METRO_PORT);
+  if (!isMetroPortAvailable) {
+    throw new MetroPortUnavailableError(metroPort);
   }
 
   const Metro = getMetroPackage(projectRoot);
 
   process.env.RN_HARNESS = 'true';
 
   const projectMetroConfig = await Metro.loadConfig({
-    port: METRO_PORT,
+    port: metroPort,
     projectRoot,
   });
   const config = await withRnHarness(projectMetroConfig, true)();
@@ -62,7 +62,7 @@ export const getMetroInstance = async (
 
   const middleware = connect()
     .use(nocache())
-    .use('/', getExpoMiddleware(projectRoot, harnessConfig.entryPoint))
+    .use('/', getExpoMiddleware(projectRoot, harnessConfig))
     .use('/status', getStatusMiddleware(projectRoot));
 
   const ready = waitForBundler(reporter, abortSignal);

packages/bundler-metro/src/factory.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { NextFunction } from 'connect';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
 import crypto from 'node:crypto';
 import { getResolvedEntryPointWithoutExtension } from '../entry-point-utils.js';
 
 export const getExpoMiddleware =
-  (projectRoot: string, entryPoint: string) =>
+  (projectRoot: string, harnessConfig: HarnessConfig) =>
   (req: IncomingMessage, res: ServerResponse, next: NextFunction) => {
     if (req.url !== '/') {
       next();
@@ -14,7 +15,7 @@ export const getExpoMiddleware =
     const platform = req.headers['expo-platform'] as string;
     const resolvedEntryPoint = getResolvedEntryPointWithoutExtension(
       projectRoot,
-      entryPoint
+      harnessConfig.entryPoint
     );
 
     const manifestJson = JSON.stringify({
@@ -24,7 +25,7 @@ export const getExpoMiddleware =
       launchAsset: {
         key: 'bundle',
         contentType: 'application/javascript',
-        url: `http://localhost:8081/${resolvedEntryPoint}.bundle?platform=${platform}&dev=true&hot=false&lazy=true&transform.engine=hermes&transform.bytecode=1&transform.routerRoot=app&transform.reactCompiler=true&unstable_transformProfile=hermes-stable`,
+        url: `http://localhost:${harnessConfig.metroPort}/${resolvedEntryPoint}.bundle?platform=${platform}&dev=true&hot=false&lazy=true&transform.engine=hermes&transform.bytecode=1&transform.routerRoot=app&transform.reactCompiler=true&unstable_transformProfile=hermes-stable`,
       },
       assets: [],
       metadata: {},
@@ -35,7 +36,7 @@ export const getExpoMiddleware =
           version: '1.0.0',
         },
         expoGo: {
-          debuggerHost: 'localhost:8081',
+          debuggerHost: `localhost:${harnessConfig.metroPort}`,
           developer: {
             tool: 'expo-cli',
             projectRoot,

packages/bundler-metro/src/middlewares/expo-middleware.ts

@@ -1,9 +1,9 @@
-import { METRO_PORT } from './constants.js';
 import { getResolvedEntryPointWithoutExtension } from './entry-point-utils.js';
 
 type PrewarmOptions = {
   projectRoot: string;
   entryPoint: string;
+  port: number;
   platform: string;
   dev: boolean;
   minify: boolean;
@@ -13,7 +13,8 @@ type PrewarmOptions = {
 export const prewarmMetroBundle = async (
   options: PrewarmOptions
 ): Promise<void> => {
-  const { projectRoot, entryPoint, platform, dev, minify, signal } = options;
+  const { projectRoot, entryPoint, port, platform, dev, minify, signal } =
+    options;
   const resolvedEntryPoint = getResolvedEntryPointWithoutExtension(
     projectRoot,
     entryPoint
@@ -23,7 +24,7 @@ export const prewarmMetroBundle = async (
     dev: String(dev),
     minify: String(minify),
   });
-  const url = `http://localhost:${METRO_PORT}/${resolvedEntryPoint}.bundle?${searchParams.toString()}`;
+  const url = `http://localhost:${port}/${resolvedEntryPoint}.bundle?${searchParams.toString()}`;
 
   const response = await fetch(url, { signal });
 

packages/bundler-metro/src/prewarm.ts

@@ -1,5 +1,6 @@
 export { getConfig } from './reader.js';
 export type { Config } from './types.js';
+export { ConfigSchema, DEFAULT_METRO_PORT } from './types.js';
 export {
   ConfigValidationError,
   ConfigNotFoundError,

packages/config/src/index.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+export const DEFAULT_METRO_PORT = 8081;
+
 const RunnerSchema = z.object({
   name: z
     .string()
@@ -22,6 +24,13 @@ export const ConfigSchema = z
     runners: z.array(RunnerSchema).min(1, 'At least one runner is required'),
     defaultRunner: z.string().optional(),
     host: z.string().min(1, 'Host is required').optional(),
+    metroPort: z
+      .number()
+      .int('Metro port must be an integer')
+      .min(1, 'Metro port must be at least 1')
+      .max(65535, 'Metro port must be at most 65535')
+      .optional()
+      .default(DEFAULT_METRO_PORT),
     webSocketPort: z.number().optional().default(3001),
     bridgeTimeout: z
       .number()

packages/config/src/types.ts

@@ -3,6 +3,7 @@ import { hideBin } from 'yargs/helpers';
 
 export type HarnessCliArgs = {
   harnessRunner?: string;
+  metroPort?: number;
 };
 
 export const getAdditionalCliArgs = (): HarnessCliArgs => {
@@ -11,6 +12,10 @@ export const getAdditionalCliArgs = (): HarnessCliArgs => {
       type: 'string',
       description: 'Specify which Harness runner to use',
     })
+    .option('metroPort', {
+      type: 'number',
+      description: 'Override the Metro bundler port',
+    })
     .strict(false)
     .help(false)
     .version(false)
@@ -19,5 +24,6 @@ export const getAdditionalCliArgs = (): HarnessCliArgs => {
 
   return {
     harnessRunner: argv.harnessRunner,
+    metroPort: argv.metroPort,
   };
 };

packages/jest/src/cli-args.ts

@@ -178,6 +178,7 @@ const getHarnessInternal = async (
     await prewarmMetroBundle({
       projectRoot,
       entryPoint: config.entryPoint,
+      port: config.metroPort,
       platform: platform.platformId,
       dev: true,
       minify: false,