feat: improve Metro caching support

V3RON · V3RON · commit de5b0b7e3dfd · 2026-03-17T10:59:57.000+01:00
diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
@@ -59,10 +59,10 @@ jobs:
       - name: Metro cache
         uses: actions/cache@v4
         with:
-          path: apps/playground/node_modules/.cache/rn-harness/metro-cache
-          key: metro-cache-${{ hashFiles('apps/playground/node_modules/.cache/rn-harness/metro-cache/**/*') }}
+          path: apps/playground/.harness/metro-cache
+          key: ${{ runner.os }}-metro-cache-${{ hashFiles('**/bun.lock', '**/bun.lockb', '**/package-lock.json', '**/npm-shrinkwrap.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/metro.config.js', '**/metro.config.cjs', '**/metro.config.mjs', '**/metro.config.ts', '**/babel.config.js', '**/babel.config.cjs', '**/babel.config.mjs', '**/babel.config.ts', '**/babel.config.json') }}
           restore-keys: |
-            metro-cache
+            ${{ runner.os }}-metro-cache-
 
       - name: Install dependencies
         run: |
@@ -131,10 +131,10 @@ jobs:
       - name: Metro cache
         uses: actions/cache@v4
         with:
-          path: apps/playground/node_modules/.cache/rn-harness/metro-cache
-          key: metro-cache-${{ hashFiles('apps/playground/node_modules/.cache/rn-harness/metro-cache/**/*') }}
+          path: apps/playground/.harness/metro-cache
+          key: ${{ runner.os }}-metro-cache-${{ hashFiles('**/bun.lock', '**/bun.lockb', '**/package-lock.json', '**/npm-shrinkwrap.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/metro.config.js', '**/metro.config.cjs', '**/metro.config.mjs', '**/metro.config.ts', '**/babel.config.js', '**/babel.config.cjs', '**/babel.config.mjs', '**/babel.config.ts', '**/babel.config.json') }}
           restore-keys: |
-            metro-cache
+            ${{ runner.os }}-metro-cache-
 
       - name: Install Watchman
         run: brew install watchman
@@ -220,10 +220,10 @@ jobs:
       - name: Metro cache
         uses: actions/cache@v4
         with:
-          path: apps/playground/node_modules/.cache/rn-harness/metro-cache
-          key: metro-cache-${{ hashFiles('apps/playground/node_modules/.cache/rn-harness/metro-cache/**/*') }}
+          path: apps/playground/.harness/metro-cache
+          key: ${{ runner.os }}-metro-cache-${{ hashFiles('**/bun.lock', '**/bun.lockb', '**/package-lock.json', '**/npm-shrinkwrap.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/metro.config.js', '**/metro.config.cjs', '**/metro.config.mjs', '**/metro.config.ts', '**/babel.config.js', '**/babel.config.cjs', '**/babel.config.mjs', '**/babel.config.ts', '**/babel.config.json') }}
           restore-keys: |
-            metro-cache
+            ${{ runner.os }}-metro-cache-
 
       - name: Install dependencies
         run: |
@@ -276,10 +276,10 @@ jobs:
       - name: Metro cache
         uses: actions/cache@v4
         with:
-          path: apps/playground/node_modules/.cache/rn-harness/metro-cache
-          key: metro-cache-${{ hashFiles('apps/playground/node_modules/.cache/rn-harness/metro-cache/**/*') }}
+          path: apps/playground/.harness/metro-cache
+          key: ${{ runner.os }}-metro-cache-${{ hashFiles('**/bun.lock', '**/bun.lockb', '**/package-lock.json', '**/npm-shrinkwrap.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/metro.config.js', '**/metro.config.cjs', '**/metro.config.mjs', '**/metro.config.ts', '**/babel.config.js', '**/babel.config.cjs', '**/babel.config.mjs', '**/babel.config.ts', '**/babel.config.json') }}
           restore-keys: |
-            metro-cache
+            ${{ runner.os }}-metro-cache-
 
       - name: Install dependencies
         run: |
@@ -372,10 +372,10 @@ jobs:
       - name: Metro cache
         uses: actions/cache@v4
         with:
-          path: apps/playground/node_modules/.cache/rn-harness/metro-cache
-          key: metro-cache-${{ hashFiles('apps/playground/node_modules/.cache/rn-harness/metro-cache/**/*') }}
+          path: apps/playground/.harness/metro-cache
+          key: ${{ runner.os }}-metro-cache-${{ hashFiles('**/bun.lock', '**/bun.lockb', '**/package-lock.json', '**/npm-shrinkwrap.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/metro.config.js', '**/metro.config.cjs', '**/metro.config.mjs', '**/metro.config.ts', '**/babel.config.js', '**/babel.config.cjs', '**/babel.config.mjs', '**/babel.config.ts', '**/babel.config.json') }}
           restore-keys: |
-            metro-cache
+            ${{ runner.os }}-metro-cache-
 
       - name: Install Watchman
         run: brew install watchman
diff --git a/actions/android/action.yml b/actions/android/action.yml
@@ -117,7 +117,7 @@ runs:
         elif [ -f "yarn.lock" ]; then
           echo "manager=yarn" >> $GITHUB_OUTPUT
           echo "runner=yarn " >> $GITHUB_OUTPUT
-        elif [ -f "bun.lockb" ]; then
+        elif [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then
           echo "manager=bun" >> $GITHUB_OUTPUT
           echo "runner=bunx " >> $GITHUB_OUTPUT
         elif [ -f "deno.lock" ]; then
diff --git a/actions/ios/action.yml b/actions/ios/action.yml
@@ -55,7 +55,7 @@ runs:
         elif [ -f "yarn.lock" ]; then
           echo "manager=yarn" >> $GITHUB_OUTPUT
           echo "runner=yarn " >> $GITHUB_OUTPUT
-        elif [ -f "bun.lockb" ]; then
+        elif [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then
           echo "manager=bun" >> $GITHUB_OUTPUT
           echo "runner=bunx " >> $GITHUB_OUTPUT
         elif [ -f "deno.lock" ]; then
diff --git a/actions/web/action.yml b/actions/web/action.yml
@@ -43,7 +43,7 @@ runs:
         elif [ -f "yarn.lock" ]; then
           echo "manager=yarn" >> $GITHUB_OUTPUT
           echo "runner=yarn " >> $GITHUB_OUTPUT
-        elif [ -f "bun.lockb" ]; then
+        elif [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then
           echo "manager=bun" >> $GITHUB_OUTPUT
           echo "runner=bunx " >> $GITHUB_OUTPUT
         elif [ -f "deno.lock" ]; then
diff --git a/packages/github-action/src/android/action.yml b/packages/github-action/src/android/action.yml
@@ -117,7 +117,7 @@ runs:
         elif [ -f "yarn.lock" ]; then
           echo "manager=yarn" >> $GITHUB_OUTPUT
           echo "runner=yarn " >> $GITHUB_OUTPUT
-        elif [ -f "bun.lockb" ]; then
+        elif [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then
           echo "manager=bun" >> $GITHUB_OUTPUT
           echo "runner=bunx " >> $GITHUB_OUTPUT
         elif [ -f "deno.lock" ]; then
diff --git a/packages/github-action/src/ios/action.yml b/packages/github-action/src/ios/action.yml
@@ -55,7 +55,7 @@ runs:
         elif [ -f "yarn.lock" ]; then
           echo "manager=yarn" >> $GITHUB_OUTPUT
           echo "runner=yarn " >> $GITHUB_OUTPUT
-        elif [ -f "bun.lockb" ]; then
+        elif [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then
           echo "manager=bun" >> $GITHUB_OUTPUT
           echo "runner=bunx " >> $GITHUB_OUTPUT
         elif [ -f "deno.lock" ]; then
diff --git a/packages/github-action/src/web/action.yml b/packages/github-action/src/web/action.yml
@@ -43,7 +43,7 @@ runs:
         elif [ -f "yarn.lock" ]; then
           echo "manager=yarn" >> $GITHUB_OUTPUT
           echo "runner=yarn " >> $GITHUB_OUTPUT
-        elif [ -f "bun.lockb" ]; then
+        elif [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then
           echo "manager=bun" >> $GITHUB_OUTPUT
           echo "runner=bunx " >> $GITHUB_OUTPUT
         elif [ -f "deno.lock" ]; then
diff --git a/packages/jest/package.json b/packages/jest/package.json
@@ -37,6 +37,7 @@
     "@react-native-harness/bridge": "workspace:*",
     "@react-native-harness/bundler-metro": "workspace:*",
     "@react-native-harness/config": "workspace:*",
+    "@react-native-harness/metro": "workspace:*",
     "@react-native-harness/platforms": "workspace:*",
     "@react-native-harness/tools": "workspace:*",
     "chalk": "^4.1.2",
diff --git a/packages/jest/src/__tests__/harness-cache.test.ts b/packages/jest/src/__tests__/harness-cache.test.ts
@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+import type { HarnessPlatform } from '@react-native-harness/platforms';
+
+const mocks = vi.hoisted(() => ({
+  isMetroCacheReusable: vi.fn(),
+  logMetroCacheReused: vi.fn(),
+  logMetroPrewarmCompleted: vi.fn(),
+}));
+
+vi.mock('@react-native-harness/metro', () => ({
+  isMetroCacheReusable: mocks.isMetroCacheReusable,
+}));
+
+vi.mock('../logs.js', () => ({
+  logMetroCacheReused: mocks.logMetroCacheReused,
+  logMetroPrewarmCompleted: mocks.logMetroPrewarmCompleted,
+}));
+
+import { maybeLogMetroCacheReuse } from '../harness.js';
+
+const platform: HarnessPlatform = {
+  name: 'ios',
+  platformId: 'ios',
+  runner: '/virtual/platform-runner.js',
+  config: {},
+};
+
+const createHarnessConfig = (
+  overrides: Partial<HarnessConfig> = {}
+): HarnessConfig =>
+  ({
+    appRegistryComponentName: 'App',
+    webSocketPort: 8081,
+    disableViewFlattening: false,
+    bridgeTimeout: 5000,
+    entryPoint: 'index.js',
+    unstable__enableMetroCache: true,
+    forwardClientLogs: false,
+    ...overrides,
+  }) as HarnessConfig;
+
+describe('maybeLogMetroCacheReuse', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.isMetroCacheReusable.mockReturnValue(false);
+  });
+
+  it('logs when an existing metro cache will be reused', () => {
+    mocks.isMetroCacheReusable.mockReturnValue(true);
+
+    maybeLogMetroCacheReuse(createHarnessConfig(), platform, '/tmp/project');
+
+    expect(mocks.isMetroCacheReusable).toHaveBeenCalledWith('/tmp/project');
+    expect(mocks.logMetroCacheReused).toHaveBeenCalledWith(platform);
+  });
+
+  it('does not log when metro cache reuse is disabled', () => {
+    maybeLogMetroCacheReuse(
+      createHarnessConfig({ unstable__enableMetroCache: false }),
+      platform,
+      '/tmp/project'
+    );
+
+    expect(mocks.isMetroCacheReusable).not.toHaveBeenCalled();
+    expect(mocks.logMetroCacheReused).not.toHaveBeenCalled();
+  });
+
+  it('does not log when the metro cache is absent', () => {
+    maybeLogMetroCacheReuse(createHarnessConfig(), platform, '/tmp/project');
+
+    expect(mocks.logMetroCacheReused).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/jest/src/harness.ts b/packages/jest/src/harness.ts
@@ -16,6 +16,7 @@ import {
   getMetroInstance,
   prewarmMetroBundle,
 } from '@react-native-harness/bundler-metro';
+import { isMetroCacheReusable } from '@react-native-harness/metro';
 import { createCrashArtifactWriter } from '@react-native-harness/tools';
 import { InitializationTimeoutError } from './errors.js';
 import { Config as HarnessConfig } from '@react-native-harness/config';
@@ -24,7 +25,7 @@ import {
   type CrashSupervisor,
 } from './crash-supervisor.js';
 import { createClientLogListener } from './client-log-handler.js';
-import { logMetroPrewarmCompleted } from './logs.js';
+import { logMetroCacheReused, logMetroPrewarmCompleted } from './logs.js';
 
 export type HarnessRunTestsOptions = Exclude<TestExecutionOptions, 'platform'>;
 
@@ -40,6 +41,19 @@ export type Harness = {
   crashSupervisor: CrashSupervisor;
 };
 
+export const maybeLogMetroCacheReuse = (
+  config: HarnessConfig,
+  platform: HarnessPlatform,
+  projectRoot: string
+): void => {
+  if (
+    config.unstable__enableMetroCache &&
+    isMetroCacheReusable(projectRoot)
+  ) {
+    logMetroCacheReused(platform);
+  }
+};
+
 export const waitForAppReady = async (options: {
   serverBridge: BridgeServer;
   platformInstance: HarnessPlatformRunner;
@@ -105,6 +119,7 @@ const getHarnessInternal = async (
   const context: HarnessContext = {
     platform,
   };
+  maybeLogMetroCacheReuse(config, platform, projectRoot);
 
   const [metroInstance, platformInstance, serverBridge] = await Promise.all([
     getMetroInstance({ projectRoot, harnessConfig: config }, signal),
diff --git a/packages/jest/src/logs.ts b/packages/jest/src/logs.ts
@@ -31,6 +31,10 @@ export const logMetroPrewarmCompleted = (runner: HarnessPlatform): void => {
   );
 };
 
+export const logMetroCacheReused = (runner: HarnessPlatform): void => {
+  log(`${TAG} Reusing Metro cache for ${chalk.bold(runner.name)}\n`);
+};
+
 export const getErrorMessage = (error: HarnessError): string => {
   return `${ERROR_TAG} ${error.message}\n`;
 };
diff --git a/packages/jest/tsconfig.json b/packages/jest/tsconfig.json
@@ -3,6 +3,9 @@
   "files": [],
   "include": [],
   "references": [
+    {
+      "path": "../metro"
+    },
     {
       "path": "../cli"
     },
diff --git a/packages/jest/tsconfig.lib.json b/packages/jest/tsconfig.lib.json
@@ -13,10 +13,10 @@
   "include": ["src/**/*.ts"],
   "references": [
     {
-      "path": "../cli/tsconfig.lib.json"
+      "path": "../metro/tsconfig.lib.json"
     },
     {
-      "path": "../bundler-metro/tsconfig.lib.json"
+      "path": "../cli/tsconfig.lib.json"
     },
     {
       "path": "../tools/tsconfig.lib.json"
@@ -27,6 +27,9 @@
     {
       "path": "../config/tsconfig.lib.json"
     },
+    {
+      "path": "../bundler-metro/tsconfig.lib.json"
+    },
     {
       "path": "../bridge/tsconfig.lib.json"
     }
diff --git a/packages/metro/src/__tests__/paths.test.ts b/packages/metro/src/__tests__/paths.test.ts
@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  getHarnessManifestPath,
+  getHarnessMetroCachePath,
+  getHarnessRootPath,
+  isMetroCacheReusable,
+} from '../paths.js';
+
+const tempDirs: string[] = [];
+
+const createTempProjectRoot = (): string => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rn-harness-metro-'));
+  tempDirs.push(tempDir);
+  return tempDir;
+};
+
+afterEach(() => {
+  for (const tempDir of tempDirs.splice(0)) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+});
+
+describe('metro paths', () => {
+  it('resolves the harness root under the project root', () => {
+    const projectRoot = createTempProjectRoot();
+
+    expect(getHarnessRootPath(projectRoot)).toBe(
+      path.join(projectRoot, '.harness')
+    );
+    expect(getHarnessManifestPath(projectRoot)).toBe(
+      path.join(projectRoot, '.harness', 'manifest.js')
+    );
+    expect(getHarnessMetroCachePath(projectRoot)).toBe(
+      path.join(projectRoot, '.harness', 'metro-cache')
+    );
+  });
+
+  it('returns false when the metro cache directory is missing', () => {
+    const projectRoot = createTempProjectRoot();
+
+    expect(isMetroCacheReusable(projectRoot)).toBe(false);
+  });
+
+  it('returns false when the metro cache directory is empty', () => {
+    const projectRoot = createTempProjectRoot();
+    fs.mkdirSync(getHarnessMetroCachePath(projectRoot), { recursive: true });
+
+    expect(isMetroCacheReusable(projectRoot)).toBe(false);
+  });
+
+  it('returns true when the metro cache directory contains entries', () => {
+    const projectRoot = createTempProjectRoot();
+    const metroCachePath = getHarnessMetroCachePath(projectRoot);
+
+    fs.mkdirSync(metroCachePath, { recursive: true });
+    fs.writeFileSync(path.join(metroCachePath, 'entry'), 'cached');
+
+    expect(isMetroCacheReusable(projectRoot)).toBe(true);
+  });
+});
diff --git a/packages/metro/src/index.ts b/packages/metro/src/index.ts
@@ -1 +1,7 @@
 export { withRnHarness } from './withRnHarness.js';
+export {
+  getHarnessManifestPath,
+  getHarnessMetroCachePath,
+  getHarnessRootPath,
+  isMetroCacheReusable,
+} from './paths.js';
diff --git a/packages/metro/src/manifest.ts b/packages/metro/src/manifest.ts
@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { Config as HarnessConfig } from '@react-native-harness/config';
+import { getHarnessManifestPath } from './paths';
 
 const getManifestContent = (harnessConfig: HarnessConfig): string => {
   return `global.RN_HARNESS = { 
@@ -12,10 +13,7 @@ const getManifestContent = (harnessConfig: HarnessConfig): string => {
 
 export const getHarnessManifest = (harnessConfig: HarnessConfig): string => {
   const manifestContent = getManifestContent(harnessConfig);
-  const manifestPath = path.resolve(
-    process.cwd(),
-    'node_modules/.cache/rn-harness/manifest.js'
-  );
+  const manifestPath = getHarnessManifestPath();
 
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   fs.writeFileSync(manifestPath, manifestContent);
diff --git a/packages/metro/src/metro-cache.ts b/packages/metro/src/metro-cache.ts
diff --git a/packages/metro/src/paths.ts b/packages/metro/src/paths.ts
diff --git a/packages/metro/vite.config.ts b/packages/metro/vite.config.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
