feat: automate React Native Metro setup

Configure supported React Native and Expo projects with reversible Metro and entry-graph edits.

Author: V3RON

.changeset/quiet-walls-connect.md

@@ -2,6 +2,6 @@
 'agent-react-devtools': minor
 ---
 
-Add React Native support through a Metro config wrapper and native bootstrap
-entry. React Native apps now wrap their final Metro config and import
-`agent-react-devtools/react-native` from the application entry graph.
+Automatically configure standard React Native and Expo projects through a
+CommonJS Metro wrapper and a native bootstrap entry import. Unsupported Metro
+formats and ambiguous projects retain the documented manual setup path.

README.md

@@ -199,8 +199,10 @@ patch the appropriate web entry or config:
 npx agent-react-devtools init
 ```
 
-React Native is detected too, but `init` only prints the manual React Native
-setup shown below; it does not edit Metro or application files.
+For standard React Native and Expo projects, `init` also configures Metro and a
+reachable app module. It supports existing CommonJS (`.js`/`.cjs`) Metro
+configs and creates one when none exists. Use the manual setup below for ESM,
+TypeScript, JSON/package-field, custom `--config`, or ambiguous Metro setups.
 
 To undo these changes:
 
@@ -253,6 +255,13 @@ npm install --save-dev agent-react-devtools
 
 Both of the following steps are required.
 
+`npx agent-react-devtools init` performs both steps automatically for the
+common CommonJS Metro configurations and entries it recognizes: `package.json`
+`main`, Expo Router's root layout, bare `index.*`, and Expo `App.*`. It patches
+all available platform-specific entries when a shared entry does not exist.
+The CLI first preflights every target and leaves files unchanged when it cannot
+safely identify the config or entry. `uninit` removes only its marked edits.
+
 #### 1. Wrap the final Metro config
 
 For a bare React Native app:
@@ -335,6 +344,13 @@ If `status` reports zero connected apps:
 4. Confirm the daemon is listening on 8097 and repeat `adb reverse` for Android devices.
 5. Check that the app is a development build.
 
+#### Manual fallback
+
+Configure the two steps above manually when Metro uses ESM (`.mjs`),
+TypeScript, JSON or a package-field configuration; when your app starts Metro
+with a custom `--config`; or when the CLI reports an ambiguous config or entry.
+Keep `withAgentReactDevTools` as the final outermost wrapper.
+
 ## Using with agent-browser
 
 When using `agent-browser` to drive the app (e.g. for profiling interactions), you **must use headed mode**. Headless Chromium does not properly execute the devtools connect script:

packages/agent-react-devtools/skills/react-devtools/references/commands.md

@@ -119,6 +119,11 @@ Categories with no changes are omitted. Keys are deduplicated across commits in
 ## Setup
 
 ### `agent-react-devtools init [--dry-run]`
-Auto-detect the framework in the current directory. It configures Vite, Next.js, and CRA automatically. For Expo/React Native, it prints the required manual Metro-wrapper and entry-import steps without editing files.
+Auto-detect the framework in the current directory. It configures Vite, Next.js,
+CRA, and standard Expo/React Native projects automatically. For React Native it
+patches existing CommonJS Metro configs (or creates one), then adds the native
+bootstrap import to a recognized reachable app module. ESM, TypeScript, JSON or
+package-field Metro configs, custom `--config` use, and ambiguous targets are
+left unchanged with manual setup instructions.
 
 Use `--dry-run` to preview changes without writing files.

packages/agent-react-devtools/skills/react-devtools/references/setup.md

@@ -1,8 +1,8 @@
 # Setup Guide
 
 agent-react-devtools works with React web and React Native apps. The `init`
-command auto-configures Vite, Next.js, and Create React App. For React Native,
-it prints the manual setup steps without editing files.
+command auto-configures Vite, Next.js, Create React App, and standard React
+Native/Expo projects with CommonJS Metro configs.
 
 ## Web Auto Setup (Recommended)
 
@@ -59,7 +59,15 @@ import 'agent-react-devtools/connect';
 
 ### React Native / Expo
 
-The Metro wrapper and entry-graph import below are both mandatory.
+The Metro wrapper and entry-graph import below are both mandatory. For a
+standard project, `init` adds both automatically: it supports existing
+`metro.config.js`/`.cjs` files, or creates the appropriate default config when
+none exists, then patches `package.json` `main`, Expo Router's root layout,
+bare `index.*`, or Expo `App.*`.
+
+It safely falls back without editing files for ESM, TypeScript, JSON or
+package-field Metro configurations, custom `--config` usage, or ambiguous
+targets. In those cases, apply the two manual steps below.
 
 ```bash
 npm install --save-dev agent-react-devtools
@@ -103,6 +111,9 @@ The import puts the module into Metro's dependency graph; the wrapper executes
 it after React Native initialization and before application modules. Restart
 Metro after changing `metro.config.js`.
 
+`uninit` removes only the ownership-marked import and Metro wrapper it added.
+It deletes an auto-created config only if it is still unchanged.
+
 The daemon and client use port 8097 by default:
 
 ```bash

packages/agent-react-devtools/src/__tests__/init.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, writeFileSync, mkdirSync, readFileSync, rmSync, existsSync
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { detectFramework, runInit, runUninit } from '../init.js';
+import { withAgentReactDevTools } from '../metro-plugin.js';
 
 function makeTempDir(): string {
   return mkdtempSync(join(tmpdir(), 'ard-test-'));
@@ -200,35 +201,170 @@ describe('runInit', () => {
     expect(content).toBe(original);
   });
 
-  it('prints manual React Native setup without modifying files', async () => {
-    const packageJson = JSON.stringify({
+  it('patches a bare React Native Metro config and its reachable entry idempotently', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
       dependencies: { 'react-native': '^0.87.0' },
-    });
+    }));
     const metroConfig = `module.exports = { serializer: {} };\n`;
-    const entry = `import { AppRegistry } from 'react-native';\n`;
-    writeFileSync(join(dir, 'package.json'), packageJson);
+    writeFileSync(join(dir, 'metro.config.js'), metroConfig);
+    writeFileSync(join(dir, 'index.js'), `import { AppRegistry } from 'react-native';\n`);
+
+    await runInit(dir, false);
+    const configAfterFirstInit = readFileSync(join(dir, 'metro.config.js'), 'utf-8');
+    const entryAfterFirstInit = readFileSync(join(dir, 'index.js'), 'utf-8');
+
+    expect(configAfterFirstInit).toContain('@agent-react-devtools:metro-wrapper:start');
+    expect(configAfterFirstInit).toContain('module.exports = withAgentReactDevTools(module.exports);');
+    expect(entryAfterFirstInit).toContain('@agent-react-devtools:react-native-bootstrap');
+    expect(entryAfterFirstInit).toContain("import 'agent-react-devtools/react-native';");
+
+    await runInit(dir, false);
+    expect(readFileSync(join(dir, 'metro.config.js'), 'utf-8')).toBe(configAfterFirstInit);
+    expect(readFileSync(join(dir, 'index.js'), 'utf-8')).toBe(entryAfterFirstInit);
+  });
+
+  it('makes the native bootstrap reachable in the entry graph and schedules it after React Native initialization', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    writeFileSync(join(dir, 'index.js'), `export {};\n`);
+
+    await runInit(dir, false);
+
+    const entry = readFileSync(join(dir, 'index.js'), 'utf-8');
+    const modules = withAgentReactDevTools({
+      serializer: {
+        getModulesRunBeforeMainModule: () => ['/react-native/InitializeCore.js'],
+      },
+    }).serializer.getModulesRunBeforeMainModule(join(dir, 'index.js'));
+
+    expect(entry).toContain("import 'agent-react-devtools/react-native';");
+    expect(modules[0]).toBe('/react-native/InitializeCore.js');
+    expect(modules[1]).toMatch(/react-native\.js$/);
+  });
+
+  it('creates an Expo CommonJS Metro config in module packages and patches the router root layout', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      type: 'module',
+      dependencies: { expo: '^54.0.0', 'expo-router': '^5.0.0' },
+    }));
+    mkdirSync(join(dir, 'app'));
+    writeFileSync(join(dir, 'app/_layout.tsx'), `export default function Layout() { return null; }\n`);
+
+    await runInit(dir, false);
+
+    const configPath = join(dir, 'metro.config.cjs');
+    expect(existsSync(configPath)).toBe(true);
+    expect(readFileSync(configPath, 'utf-8')).toContain("require('expo/metro-config')");
+    expect(readFileSync(join(dir, 'app/_layout.tsx'), 'utf-8')).toContain(
+      "import 'agent-react-devtools/react-native';",
+    );
+  });
+
+  it('patches every platform entry when no shared React Native index exists', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    writeFileSync(join(dir, 'index.ios.js'), `export {};\n`);
+    writeFileSync(join(dir, 'index.android.ts'), `export {};\n`);
+
+    await runInit(dir, false);
+
+    expect(readFileSync(join(dir, 'index.ios.js'), 'utf-8')).toContain('agent-react-devtools/react-native');
+    expect(readFileSync(join(dir, 'index.android.ts'), 'utf-8')).toContain('agent-react-devtools/react-native');
+  });
+
+  it('uses a local package main entry before conventional entry files', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      main: './src/bootstrap.ts',
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    mkdirSync(join(dir, 'src'));
+    writeFileSync(join(dir, 'src/bootstrap.ts'), `export {};\n`);
+    writeFileSync(join(dir, 'index.js'), `export {};\n`);
+
+    await runInit(dir, false);
+
+    expect(readFileSync(join(dir, 'src/bootstrap.ts'), 'utf-8')).toContain('agent-react-devtools/react-native');
+    expect(readFileSync(join(dir, 'index.js'), 'utf-8')).not.toContain('agent-react-devtools/react-native');
+  });
+
+  it('uses the nearest Metro config found by Metro’s upward search', async () => {
+    const appDir = join(dir, 'app');
+    mkdirSync(appDir);
+    writeFileSync(join(appDir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    writeFileSync(join(dir, 'metro.config.cjs'), `module.exports = {};\n`);
+    writeFileSync(join(appDir, 'index.js'), `export {};\n`);
+
+    await runInit(appDir, false);
+
+    expect(readFileSync(join(dir, 'metro.config.cjs'), 'utf-8')).toContain('@agent-react-devtools:metro-wrapper:start');
+    expect(readFileSync(join(appDir, 'index.js'), 'utf-8')).toContain('agent-react-devtools/react-native');
+  });
+
+  it('leaves a .js Metro config alone when package.json declares ESM', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      type: 'module',
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    const metroConfig = `export default {};\n`;
+    const entry = `export {};\n`;
     writeFileSync(join(dir, 'metro.config.js'), metroConfig);
     writeFileSync(join(dir, 'index.js'), entry);
+
+    await runInit(dir, false);
+
+    expect(readFileSync(join(dir, 'metro.config.js'), 'utf-8')).toBe(metroConfig);
+    expect(readFileSync(join(dir, 'index.js'), 'utf-8')).toBe(entry);
+  });
+
+  it('keeps unsupported Metro configs and entries unchanged', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    const metroConfig = `export default {};\n`;
+    const entry = `export {};\n`;
+    writeFileSync(join(dir, 'metro.config.mjs'), metroConfig);
+    writeFileSync(join(dir, 'index.js'), entry);
     const log = vi.spyOn(console, 'log').mockImplementation(() => {});
 
     try {
       await runInit(dir, false);
-      await runInit(dir, true);
-
-      const output = log.mock.calls.flat().join('\n');
-      expect(output).toContain('React Native requires manual setup');
-      expect(output).not.toContain('0.87');
-      expect(output).toContain('npm install -D agent-react-devtools');
-      expect(output).not.toContain('react-devtools-core');
-      expect(output).toContain('withAgentReactDevTools');
-      expect(output).toContain("import 'agent-react-devtools/react-native'");
-      expect(output).not.toContain('connect to DevTools automatically');
+      expect(log.mock.calls.flat().join('\n')).toContain('Manual setup required');
     } finally {
       log.mockRestore();
     }
 
-    expect(readFileSync(join(dir, 'package.json'), 'utf-8')).toBe(packageJson);
+    expect(readFileSync(join(dir, 'metro.config.mjs'), 'utf-8')).toBe(metroConfig);
+    expect(readFileSync(join(dir, 'index.js'), 'utf-8')).toBe(entry);
+  });
+
+  it('preserves manual Metro wrapper setup while completing a missing entry import', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    const metroConfig = `const { withAgentReactDevTools } = require('agent-react-devtools/metro');\nmodule.exports = withAgentReactDevTools({});\n`;
+    writeFileSync(join(dir, 'metro.config.js'), metroConfig);
+    writeFileSync(join(dir, 'index.js'), `export {};\n`);
+
+    await runInit(dir, false);
+
     expect(readFileSync(join(dir, 'metro.config.js'), 'utf-8')).toBe(metroConfig);
+    expect(readFileSync(join(dir, 'index.js'), 'utf-8')).toContain('agent-react-devtools/react-native');
+  });
+
+  it('preflights React Native targets before a dry run writes any files', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    const entry = `export {};\n`;
+    writeFileSync(join(dir, 'index.js'), entry);
+
+    await runInit(dir, true);
+
+    expect(existsSync(join(dir, 'metro.config.js'))).toBe(false);
     expect(readFileSync(join(dir, 'index.js'), 'utf-8')).toBe(entry);
   });
 });
@@ -371,21 +507,39 @@ describe('runUninit', () => {
     expect(afterInit2).toContain('agent-react-devtools');
   });
 
-  it('explains that React Native manual setup has nothing to uninit', async () => {
-    writeFileSync(
-      join(dir, 'package.json'),
-      JSON.stringify({ dependencies: { 'react-native': '^0.87.0' } }),
-    );
-    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+  it('reverts only its marked React Native edits and deletes an unmodified generated config', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    const entry = `export {};\n`;
+    writeFileSync(join(dir, 'index.js'), entry);
+
+    await runInit(dir, false);
+    await runUninit(dir, false);
+
+    expect(existsSync(join(dir, 'metro.config.js'))).toBe(false);
+    expect(readFileSync(join(dir, 'index.js'), 'utf-8')).toBe(entry);
+  });
+
+  it('keeps a modified generated Metro config while removing marked entry imports', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'react-native': '^0.87.0' },
+    }));
+    writeFileSync(join(dir, 'index.js'), `export {};\n`);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     try {
+      await runInit(dir, false);
+      const configPath = join(dir, 'metro.config.js');
+      writeFileSync(configPath, `${readFileSync(configPath, 'utf-8')}\n// user customization\n`);
+
       await runUninit(dir, false);
-      const output = log.mock.calls.flat().join('\n');
-      expect(output).toContain('manual setup');
-      expect(output).toContain('no changes to remove');
-      expect(output).not.toContain('configuration has been removed');
+
+      expect(existsSync(configPath)).toBe(true);
+      expect(warn.mock.calls.flat().join('\n')).toContain('leaving it in place');
+      expect(readFileSync(join(dir, 'index.js'), 'utf-8')).not.toContain('agent-react-devtools/react-native');
     } finally {
-      log.mockRestore();
+      warn.mockRestore();
     }
   });
 });

packages/agent-react-devtools/src/__tests__/metro-plugin.test.ts

@@ -51,6 +51,35 @@ describe('withAgentReactDevTools', () => {
     expect(serializer.getModulesRunBeforeMainModule).toBe(originalCallback);
     expect(modules[0]).toBe('existing-serializer:/entry.js');
   });
+
+  it('wraps Metro config factories without changing their arguments or serializer hooks', () => {
+    const factory = (projectRoot: string) => ({
+      projectRoot,
+      serializer: {
+        getModulesRunBeforeMainModule: () => ['/react-native/InitializeCore.js'],
+      },
+    });
+
+    const wrapped = withAgentReactDevTools(factory);
+    const config = wrapped('/app');
+
+    expect(config.projectRoot).toBe('/app');
+    expect(config.serializer.getModulesRunBeforeMainModule('/app/index.js')).toEqual([
+      '/react-native/InitializeCore.js',
+      expect.stringMatching(/react-native\.js$/),
+    ]);
+  });
+
+  it('wraps async and promise Metro config exports', async () => {
+    const asyncFactory = async () => ({ serializer: {} });
+    const promisedConfig = Promise.resolve({ serializer: {} });
+
+    const fromFactory = await withAgentReactDevTools(asyncFactory)();
+    const fromPromise = await withAgentReactDevTools(promisedConfig);
+
+    expect(fromFactory.serializer.getModulesRunBeforeMainModule('/app/index.js')).toHaveLength(1);
+    expect(fromPromise.serializer.getModulesRunBeforeMainModule('/app/index.js')).toHaveLength(1);
+  });
 });
 
 describe('React Native package exports', () => {