Resolve [metro-watchFolders] URL prefix in bundle and entry point paths (#1695)

Summary:
Pull Request resolved: #1695

Extends Metro `Server.js` to handle `[metro-watchFolders]/N/...` prefixed entry file paths in `.bundle` and `.map` requests. This convention is already used for source file serving (powering React Native DevTools), and this change extends it to bundle resolution.

**Implementation**

Adds `_resolveWatchFolderPrefix()`, which parses `[metro-watchFolders]/N/relative/path` URLs and resolves them against the corresponding `watchFolders[N]` entry from the Metro config. Also handles `[metro-project]/...` as a prefix for the project root.

This method is called from two sites:
- `_resolveRelativePath()` — used for resolving module paths in bundle/map requests
- `_getEntryPointAbsolutePath()` — used for resolving the entry file to an absolute path

**Motivation**

The primary use case is environments where the entry point resolves to a path outside the Metro server root (e.g. via a symlink to a different filesystem mount). In these cases, `path.relative(serverRoot, entryPath)` produces a broken `../../...` path. A client (such as Expo CLI) can instead construct a `[metro-watchFolders]/N/...` URL referencing the watchFolder that contains the entry file, allowing Metro to resolve it correctly.

We have an open PR in Expo CLI that aims to use this configuration path: expo/expo#45010.

Changelog: [Internal]

Differential Revision: D102004228

Author: huntie

packages/metro/src/Server.js

@@ -1622,6 +1622,32 @@ export default class Server {
     );
   }
 
+  _resolveWatchFolderPrefix(
+    filePath: string,
+  ): {rootDir: string, filePath: string} | null {
+    const watchFolderMatch = filePath.match(
+      /^\.\/\[metro-watchFolders\]\/(\d+)\/(.*)/,
+    );
+    if (watchFolderMatch != null) {
+      const index = parseInt(watchFolderMatch[1], 10);
+      const watchFolder = this._config.watchFolders[index];
+      if (watchFolder != null) {
+        return {
+          rootDir: path.resolve(watchFolder),
+          filePath: './' + watchFolderMatch[2],
+        };
+      }
+    }
+    const projectMatch = filePath.match(/^\.\/\[metro-project\]\/(.*)/);
+    if (projectMatch != null) {
+      return {
+        rootDir: path.resolve(this._config.projectRoot),
+        filePath: './' + projectMatch[1],
+      };
+    }
+    return null;
+  }
+
   async _resolveRelativePath(
     filePath: string,
     {
@@ -1639,13 +1665,22 @@ export default class Server {
       transformOptions.platform,
       resolverOptions,
     );
+    const resolved = this._resolveWatchFolderPrefix(filePath);
     const rootDir =
-      relativeTo === 'server'
-        ? this._getServerRootDir()
-        : this._config.projectRoot;
+      resolved != null
+        ? resolved.rootDir
+        : relativeTo === 'server'
+          ? this._getServerRootDir()
+          : this._config.projectRoot;
+    const resolvedFilePath = resolved != null ? resolved.filePath : filePath;
     return resolutionFn(`${rootDir}/.`, {
-      name: filePath,
-      data: {key: filePath, locs: [], asyncType: null, isESMImport: false},
+      name: resolvedFilePath,
+      data: {
+        key: resolvedFilePath,
+        locs: [],
+        asyncType: null,
+        isESMImport: false,
+      },
     }).filePath;
   }
 
@@ -1706,6 +1741,10 @@ export default class Server {
   }
 
   _getEntryPointAbsolutePath(entryFile: string): string {
+    const resolved = this._resolveWatchFolderPrefix(entryFile);
+    if (resolved != null) {
+      return path.resolve(resolved.rootDir, resolved.filePath);
+    }
     return path.resolve(this._getServerRootDir(), entryFile);
   }
 

packages/metro/src/Server/__tests__/Server-test.js

@@ -1436,4 +1436,87 @@ describe('processRequest', () => {
       },
     );
   });
+
+  describe('watchFolder prefix resolution', () => {
+    let watchFolderServer: $FlowFixMe;
+
+    beforeEach(() => {
+      watchFolderServer = new Server(
+        mergeConfig(getDefaultValues('/'), {
+          projectRoot: '/project',
+          watchFolders: ['/project', '/external/packages'],
+          resolver: {blockList: []},
+          cacheVersion: '',
+          serializer: {
+            getRunModuleStatement: moduleId =>
+              `require(${JSON.stringify(moduleId)});`,
+            polyfillModuleNames: [],
+            getModulesRunBeforeMainModule: () => ['InitializeCore'],
+          },
+          reporter: require('../../lib/reporting').nullReporter,
+        } as InputConfigT),
+      );
+    });
+
+    test('resolves [metro-watchFolders]/N/ prefix against the Nth watch folder', () => {
+      expect(
+        watchFolderServer._resolveWatchFolderPrefix(
+          './[metro-watchFolders]/1/expo-router/entry',
+        ),
+      ).toEqual({
+        rootDir: '/external/packages',
+        filePath: './expo-router/entry',
+      });
+    });
+
+    test('resolves [metro-watchFolders]/0/ prefix against the first watch folder', () => {
+      expect(
+        watchFolderServer._resolveWatchFolderPrefix(
+          './[metro-watchFolders]/0/app/index',
+        ),
+      ).toEqual({
+        rootDir: '/project',
+        filePath: './app/index',
+      });
+    });
+
+    test('resolves [metro-project]/ prefix against projectRoot', () => {
+      expect(
+        watchFolderServer._resolveWatchFolderPrefix(
+          './[metro-project]/src/App',
+        ),
+      ).toEqual({
+        rootDir: '/project',
+        filePath: './src/App',
+      });
+    });
+
+    test('returns null for paths without a recognized prefix', () => {
+      expect(
+        watchFolderServer._resolveWatchFolderPrefix('./mybundle'),
+      ).toBeNull();
+    });
+
+    test('returns null for out-of-bounds watchFolder index', () => {
+      expect(
+        watchFolderServer._resolveWatchFolderPrefix(
+          './[metro-watchFolders]/99/mybundle',
+        ),
+      ).toBeNull();
+    });
+
+    test('_getEntryPointAbsolutePath resolves prefixed entry against the corresponding watch folder', () => {
+      expect(
+        watchFolderServer._getEntryPointAbsolutePath(
+          './[metro-watchFolders]/1/expo-router/entry',
+        ),
+      ).toBe('/external/packages/expo-router/entry');
+    });
+
+    test('_getEntryPointAbsolutePath resolves non-prefixed entry against server root', () => {
+      expect(
+        watchFolderServer._getEntryPointAbsolutePath('./mybundle'),
+      ).toBe('/project/mybundle');
+    });
+  });
 });