[robhogan]

Note: the module system is not publicly configurable - although the path lives in metro-config's defaults, it's not actually a config option.

Currently it's set to require.resolve('metro-runtime/src/polyfills/require.js') within in metro-config, an absolute path which does not pass through Metro's resolver, depending instead on metro-config's dependency on metro-runtime.

That's potentially a different copy of metro-runtime than #2180 and react/react-native#58584 resolves to, and unlike those, isn't guaranteed to be watched - though it must be, as it's included in the bundle via getPrependedScripts.

This changes it to metro:runtime/polyfills/require, resolved once per graph via Metro's resolver, so it always comes from the copy Metro adds to the file map, and it's one fewer use of metro-runtime/src/*.

A custom resolveRequest will now see this specifier on every build and must delegate it to context.resolveRequest.

With #2180 landed, this was metro-config's last use of metro-runtime, so this also drops that dependency.

Changelog:

 - **[Breaking]**: Resolve the module system via `metro:runtime/polyfills/require`. A custom `resolver.resolveRequest` must delegate `metro:` specifiers it doesn't handle to `context.resolveRequest`

Test plan:
New integration test. Built and ran a bundle from a project outside this repo, so that metro-runtime isn't reachable from it. An unused emptyModulePath that's missing, outside the file map or thrown on by the resolver still builds.

Overwriting the moduleSystem export with an absolute path, as Expo CLI does, still builds and gives a byte-identical bundle. I haven't run this through Expo itself.

[github-actions]

Metro review: Looks good

Risk: medium · Commit: 7d84878 · 7 commands run

The PR now resolves the module system as metro:runtime/polyfills/require through Metro's resolver, once per prepended-scripts build, instead of using an absolute path from metro-config's own copy of metro-runtime. It also drops metro-config's now-unused metro-runtime dependency. Since my last review, the isEmptyModule check has been removed, so nothing resolves emptyModulePath eagerly any more. The new test fails on the base and passes on the head, the wider integration, Server and lib suites pass, and overriding moduleSystem with an absolute path still gives a byte-identical bundle.

No findings.

Verified

• ✅ yarn jest --no-watchman packages/metro/src/integration_tests/__tests__/module-system-test.js packages/metro-config — 5 suites, 50 tests
• ✅ (base-worktree) yarn jest --no-watchman packages/metro/src/integration_tests/__tests__/module-system-test.js (PR test copied to base) (failed as expected) — resolveRequest is never called with 'metro:runtime/polyfills/require' on the base, so the test does detect the change
• ✅ yarn jest --no-watchman packages/metro/src/integration_tests packages/metro/src/Server packages/metro/src/lib — 406 tests
• ✅ yarn jest --no-watchman packages/metro/src/integration_tests/__tests__/review-2184-test.js — A missing, unused emptyModulePath still builds. Overriding defaults.moduleSystem with an absolute require.resolve path gives a bundle byte-identical to the default (IDENTICAL true).
• ✅ yarn typecheck
• ✅ yarn eslint <changed js files>
• ✅ yarn verify-api-snapshots — Verified 18 snapshots. DependencyGraph.isEmptyModule is no longer in API.md.

Not run: No benchmark. The change adds one memoized resolver call per prepended-scripts build, not per module, so it can't plausibly affect cost. Windows wasn't checked: no Windows machine was available, and the metro: path ignores the origin, so ${projectRoot}/. isn't path-sensitive here. Expo CLI itself wasn't run, but its absolute-path override was simulated in Jest. I couldn't delete the copy of the PR test left in the base checkout, because the sandbox denied the rm.

_{Automated review by Claude. Advisory only: it never approves or blocks, and a maintainer makes the call.}

[github-actions]

should fix · The empty-module guard makes every build depend on emptyModulePath resolving

The guard calls resolveFromProjectRoot(config.resolver.emptyModulePath) for every graph, even when nothing resolves to empty. Before this PR that path was only resolved lazily, in ModuleResolver._getEmptyModule, when a resolution actually returned {type: 'empty'}. There are three consequences:

• Metro's copy doesn't fully replace metro-config's. The default emptyModulePath is still require.resolve('metro-runtime/src/modules/empty-module.js') from metro-config. If metro-config has its own metro-runtime copy outside the file map, the module system now resolves from Metro's copy, but the build still fails on empty-module.js. The description says this change removes that dependency on metro-config's copy.
• Configs that build today break. A custom emptyModulePath that is missing or outside the file map, and never used, now fails with Unable to resolve module <emptyModulePath> from <projectRoot>/.. The error gives no hint that the module system check caused it.
• Custom resolvers see a new specifier. resolveRequest now receives the absolute emptyModulePath on every graph, and a resolver that throws on it fails the build. The changelog line only mentions metro: specifiers.

Suggested fix: don't let this comparison fail the build. If emptyModulePath can't be resolved, the module system can't have resolved to empty, because _getEmptyModule would already have thrown. Wrapping only the second resolve in a try/catch and treating failure as "not empty" is therefore sound. Alternatively, have the resolver report that the resolution type was empty, so emptyModulePath isn't touched at all. Separately, defaulting emptyModulePath to metro:runtime/modules/empty-module (already in metro-runtime's exports) would remove the metro-config copy dependency for the default config.

_{Reproduced: packages/metro/src/integration_tests/__tests__/review-2184-test.js ran the same scenarios on head and base. With emptyModulePath set to /does/not/exist/empty.js, or to a real file outside the file map, or with a resolver that throws on emptyModulePath, base built and ran. Head failed with UnableToResolveError: Unable to resolve module /does/not/exist/empty.js from .../basic_bundle/. and resolver saw emptyModulePath. The outside-the-file-map path stands in for a duplicate metro-config copy; no real duplicate install was built. · id 25f357bd}

[robhogan]

Fixed in 334ed31 - the check now asks the resolver whether the module system is its cached empty module, so emptyModulePath is only resolved when something returns {type: 'empty'}. This adds a small isEmptyModule to DependencyGraph.

[github-actions]

should fix · Docs still describe delegating from a custom resolver as optional

With default config, a resolveRequest that handles bare specifiers itself and doesn't delegate metro: specifiers used to build and run. It now fails. docs/Configuration.md still shows this under resolveRequest with the comment // Optionally, chain to the standard Metro resolver., and the docs/Resolution.md section on resolveRequest says nothing about the requirement. Users hitting this breaking change will only find it in the changelog.

Suggested fix: state in both places that a custom resolver must delegate metro: specifiers it doesn't handle, and that this includes the module system on every build.

_{Reproduced: Read docs/Configuration.md:320-335 and docs/Resolution.md:311-342; the PR changes no docs. In review-2184-test.js, the scenario where bare specifiers return {type: 'empty'} and paths delegate built and ran on base, and gave the new error on head. · id c5e4fe65}

[robhogan]

Done in 334ed31 - Configuration.md and Resolution.md now both say a custom resolver must delegate metro: specifiers, including the module system.

[github-actions]

nit · A literal catch-all {type: 'empty'} resolver overflows the stack instead of reaching the new error

The description says a catch-all {type: 'empty'} resolver gets the new error. A resolver that really returns {type: 'empty'} for everything recurses instead: _getEmptyModule resolves emptyModulePath through the same resolver, gets empty again, and calls itself. The build dies with RangeError: Maximum call stack size exceeded on line 55, before the guard runs.

The recursion also exists on base, so this isn't a regression, but it is the most direct form of the mistake this error is meant to explain. The new test only maps the exact module system specifier to empty, so it doesn't cover this.

Suggested fix: detect the recursion in _getEmptyModule and throw a descriptive error, and add a true catch-all case to the test.

_{Reproduced: review-2184-test.js with resolveRequest: () => ({type: 'empty'}) gave RangeError: Maximum call stack size exceeded on both head and base. The new message only appeared when the resolver delegated paths, including emptyModulePath. · id 823a17cb}

[robhogan]

This is handled in #2180, which replaces the overflow with a descriptive error, so I have not duplicated it here. Checked the literal catch-all with both merged.