Repository navigation
Add metro:runtime for resolving asyncRequireModulePath from any importer - #2083
Merged
Merged
Conversation
`transformer.asyncRequireModulePath` is injected as a `require()` into every module that uses `import()`, and resolved from that module. The default, `metro-runtime/src/modules/asyncRequire`, therefore fails wherever `metro-runtime` isn't resolvable from an importer, eg library code under isolated `node_modules`. React Native works around this with an absolute `require.resolve()` path, which is hashed into the transform cache key and so makes caches non-portable between checkouts. This adds `metro:runtime/<subpath>` to the `metro:` scheme, resolved through the `exports` of the `metro-runtime` that Metro itself depends on (with package exports enabled, since subpaths like `modules/asyncRequire` exist only there), and makes `metro:runtime/modules/asyncRequire` the default. As for `@babel/runtime`, Metro adds that `metro-runtime` to the file map as a dynamic root, in case it's outside every configured root. The integration tests' config no longer overrides `asyncRequireModulePath`, so they exercise the default. Changelog: - **[Fix]**: Resolve the default `transformer.asyncRequireModulePath` from any importer, via a new built-in `metro:runtime/*` specifier
meta-cla
Bot
added
the
CLA Signed
robhogan
changed the title
asyncRequireModulePath via metro:runtimemetro:runtime for resolving asyncRequireModulePath from any importer
facebook-github-tools
Bot
added
the
Shared with Meta
javache
approved these changes
Oct 21, 2026
robhogan
added a commit
that referenced
this pull request
Oct 21, 2026
Summary: Publish Metro 0.87.2 from `main`. Changelog: [Internal] Test plan: ``` node scripts/updateVersion.js 0.87.2 sl diff --stat ``` Only the 17 `packages/*/package.json` manifests change, and every `0.87.1` reference is replaced. Draft release notes (from the 95 commits in v0.87.1...main - internal-only changes omitted): ``` - **[Feature]**: Add a built-in `metro:runtime/*` specifier, resolvable from any importer, eg for `transformer.asyncRequireModulePath` (#2083 by @robhogan) - **[Feature]**: When `transformer.enableBabelRuntime` is `true`, pass Metro's own `@babel/runtime` (`metro:babel-runtime`) and its installed version to Babel presets via caller data (#1957 by @robhogan) - **[Fix]**: Resolver: Fix stale resolutions after adding a nearer `package.json` or retargeting a symlinked directory, which previously needed a restart (#1948 by @robhogan) - **[Fix]**: Resolver: Packages and directories named with an asset extension (eg `lodash.zip`) resolve as modules rather than failing as assets (#2055 by @robhogan) - **[Fix]**: Resolver: Fall through to parent conditions when a nested `"exports"` or `"imports"` condition has no matching target (#2074 by @maximilliangrand) - **[Fix]**: Resolver: An exact `"exports"` or `"imports"` subpath with a `null` or unmatched target no longer resolves through a less specific subpath pattern (#1987 by @kwy404) - **[Fix]**: Use indexed watch folder paths (`[metro-watchFolders]/N/`) for assets outside `projectRoot` (#1892 by @robhogan) - **[Fix]**: Fix `/[metro-project]/` and `/[metro-watchFolders]/` bundle serving on Windows (#2015 by @motiz88) - **[Fix]**: Prevent HMR crash on `[metro-watchFolders]` or `[metro-project]` URLs (#2017 by @motiz88) - **[Fix]**: Remove erroneous `[metro-project]` and `[metro-watchFolders]` resolution of entry points from the API and CLI (#2030 by @motiz88) - **[Fix]**: Fix backslashes in async bundle paths on Windows (`includeAsyncPaths`) (#1938 by @robhogan) - **[Fix]**: Fix stale modules on the client when a file is deleted and recreated during a build, or changes during a build that fails (#2007 by @YevheniiKotyrlo) - **[Fix]**: Fix files created or modified while Metro starts up being missed until restart (#2054 by @cpruijsen) - **[Fix]**: Fix watch mode losing files when a directory replaces a file or symlink, eg when unlinking a package (#2009 by @robhogan) - **[Fix]**: Fix the fallback (Linux/Windows) watcher hanging on stop, and missing changes in a replaced directory, after a watch error (#1967 by @robhogan) - **[Fix]**: Fix the fallback watcher missing changes when a directory changes faster than Windows can report (#1967 by @robhogan) - **[Fix]**: Close the watch handles of a deleted directory and every directory under it in `FallbackWatcher`, which kept the process busy on Windows (#2004 by @YevheniiKotyrlo) - **[Fix]**: `metro-file-map`: Fix removing a non-active duplicate mock changing which mock is active (#1756 by @durvesh1992) - **[Fix]**: Propagate transformer initialisation errors from `Bundler` (#1854 by @Boulea7) - **[Fix]**: Release transform workers and file watchers when Metro fails to initialise (#1963 by @robhogan) - **[Fix]**: Ignore hyphenated and namespaced SVG attributes (eg `stroke-width`) when reading SVG asset dimensions (#1972 by @GabrielDumbrava) - **[Fix]**: Fix generated positions when iterating the mappings of indexed source maps, eg in `composeSourceMaps` (#1976 by @kwy404) - **[Fix]**: `composeSourceMaps` keeps every mapping at a generated column that the last map maps more than once (#1981 by @robhogan) - **[Fix]**: Source maps no longer lose lines after a gap of more than about two million unmapped generated lines (#1983 by @robhogan) - **[Fix]**: `metro-symbolicate` no longer fails on stack frames with no source position, such as `[native code]:0:0` in crash reporter output (#1891 by @robhogan) - **[Fix]**: Fix `metro-symbolicate` parsing of stack frames with Windows absolute paths (#1939 by @robhogan) - **[Performance]**: `metro-source-map`: Faster `Consumer` decoding and position lookups, and `composeSourceMaps` encodes its output directly - 3.2x faster composition of a bundle map with its Hermes map, using 15% less memory (#1978, #1979, #1980, #1983 by @robhogan) - **[Performance]**: Resolver: Ask for the package of a directory once for all extension candidates, and check `hierarchicalLookup` candidates from their own file map nodes. First-pass resolution is 35% faster (172ms -> 113ms on a mid-size RN app), net of a ~3% first-build cost from dropping `PackageCache`'s closest-package memo, which also cuts the resolver's retained heap by 37% (#1945, #1946, #1948 by @robhogan) - **[Performance]**: 33% faster non-Watchman file system crawl on startup (#1677 by @kitten) - **[Deprecated]**: `server.enhanceMiddleware` logs a deprecation warning when set to anything other than its default. Use `server.unstable_middleware` or `server.unstable_priorityMiddleware` (#2031 by @vzaidman) - **[Deprecated]**: `runServer`'s `unstable_extraMiddleware` option. Use `unstable_priorityMiddleware`, which runs the same middleware in the same place (#2031 by @vzaidman) - **[Deprecated]**: String values of `transformer.enableBabelRuntime` (use `true`) (#1957 by @robhogan) - **[Types]**: Add TypeScript definitions for `metro-runtime` modules, and generate (rather than hand-maintain) types for `metro-file-map` workers (#1996 by @robhogan) > NOTE: Experimental features are not covered by semver and can change at any time. - **[Experimental]**: Add `server.unstable_middleware` and `server.unstable_priorityMiddleware` config options, and `runServer` options of the same names, to add middleware after and before Metro's own. `mergeConfig` combines them from both configs: a later config's `unstable_middleware` runs last and its `unstable_priorityMiddleware` runs first (#2031 by @vzaidman) - **[Experimental]**: Add `server.unstable_onServerCreated` config option and `runServer` option of the same name, called with Metro's server instance before the HTTP server listens (#2031 by @vzaidman) - **[Experimental]**: Fix mismatched asset paths in (release) builds under `unstable_serverRoot`, make them always relative to `projectRoot` (#1917 by @robhogan) **Full Changelog**: v0.87.1...v0.87.2 ```
robhogan
added a commit
that referenced
this pull request
Oct 21, 2026
Summary: Publish Metro 0.87.2 from `main`. Changelog: [Internal] Test plan: ``` node scripts/updateVersion.js 0.87.2 sl diff --stat ``` Only the 17 `packages/*/package.json` manifests change, and every `0.87.1` reference is replaced. Draft release notes (from the 95 commits in v0.87.1...main - internal-only changes omitted): ``` - **[Feature]**: Add a built-in `metro:runtime/*` specifier, resolvable from any importer, eg for `transformer.asyncRequireModulePath` (#2083 by @robhogan) - **[Feature]**: When `transformer.enableBabelRuntime` is `true`, pass Metro's own `@babel/runtime` (`metro:babel-runtime`) and its installed version to Babel presets via caller data (#1957 by @robhogan) - **[Fix]**: Resolver: Fix stale resolutions after adding a nearer `package.json` or retargeting a symlinked directory, which previously needed a restart (#1948 by @robhogan) - **[Fix]**: Resolver: Packages and directories named with an asset extension (eg `lodash.zip`) resolve as modules rather than failing as assets (#2055 by @robhogan) - **[Fix]**: Resolver: Fall through to parent conditions when a nested `"exports"` or `"imports"` condition has no matching target (#2074 by @maximilliangrand) - **[Fix]**: Resolver: An exact `"exports"` or `"imports"` subpath with a `null` or unmatched target no longer resolves through a less specific subpath pattern (#1987 by @kwy404) - **[Fix]**: Use indexed watch folder paths (`[metro-watchFolders]/N/`) for assets outside `projectRoot` (#1892 by @robhogan) - **[Fix]**: Fix `/[metro-project]/` and `/[metro-watchFolders]/` bundle serving on Windows (#2015 by @motiz88) - **[Fix]**: Prevent HMR crash on `[metro-watchFolders]` or `[metro-project]` URLs (#2017 by @motiz88) - **[Fix]**: Remove erroneous `[metro-project]` and `[metro-watchFolders]` resolution of entry points from the API and CLI (#2030 by @motiz88) - **[Fix]**: Fix backslashes in async bundle paths on Windows (`includeAsyncPaths`) (#1938 by @robhogan) - **[Fix]**: Fix stale modules on the client when a file is deleted and recreated during a build, or changes during a build that fails (#2007 by @YevheniiKotyrlo) - **[Fix]**: Fix files created or modified while Metro starts up being missed until restart (#2054 by @cpruijsen) - **[Fix]**: Fix watch mode losing files when a directory replaces a file or symlink, eg when unlinking a package (#2009 by @robhogan) - **[Fix]**: Fix the fallback (Linux/Windows) watcher hanging on stop, and missing changes in a replaced directory, after a watch error (#1967 by @robhogan) - **[Fix]**: Fix the fallback watcher missing changes when a directory changes faster than Windows can report (#1967 by @robhogan) - **[Fix]**: Close the watch handles of a deleted directory and every directory under it in `FallbackWatcher`, which kept the process busy on Windows (#2004 by @YevheniiKotyrlo) - **[Fix]**: `metro-file-map`: Fix removing a non-active duplicate mock changing which mock is active (#1756 by @durvesh1992) - **[Fix]**: Propagate transformer initialisation errors from `Bundler` (#1854 by @Boulea7) - **[Fix]**: Release transform workers and file watchers when Metro fails to initialise (#1963 by @robhogan) - **[Fix]**: Ignore hyphenated and namespaced SVG attributes (eg `stroke-width`) when reading SVG asset dimensions (#1972 by @GabrielDumbrava) - **[Fix]**: Fix generated positions when iterating the mappings of indexed source maps, eg in `composeSourceMaps` (#1976 by @kwy404) - **[Fix]**: `composeSourceMaps` keeps every mapping at a generated column that the last map maps more than once (#1981 by @robhogan) - **[Fix]**: Source maps no longer lose lines after a gap of more than about two million unmapped generated lines (#1983 by @robhogan) - **[Fix]**: `metro-symbolicate` no longer fails on stack frames with no source position, such as `[native code]:0:0` in crash reporter output (#1891 by @robhogan) - **[Fix]**: Fix `metro-symbolicate` parsing of stack frames with Windows absolute paths (#1939 by @robhogan) - **[Performance]**: `metro-source-map`: Faster `Consumer` decoding and position lookups, and `composeSourceMaps` encodes its output directly - ~3.2x faster composition of a bundle map with its Hermes map, using ~15% less memory (#1978, #1979, #1980, #1983 by @robhogan) - **[Performance]**: Resolver: Ask for the package of a directory once for all extension candidates, and check `hierarchicalLookup` candidates from their own file map nodes. First-pass resolution is ~35% faster, net of a ~3% first-build cost from dropping `PackageCache`'s closest-package memo, which also cuts the resolver's retained heap by ~37% (#1945, #1946, #1948 by @robhogan) - **[Performance]**: ~33% faster non-Watchman file system crawl on startup (#1677 by @kitten) - **[Deprecated]**: `server.enhanceMiddleware` logs a deprecation warning when set to anything other than its default. Use `server.unstable_middleware` or `server.unstable_priorityMiddleware` (#2031 by @vzaidman) - **[Deprecated]**: `runServer`'s `unstable_extraMiddleware` option. Use `unstable_priorityMiddleware`, which runs the same middleware in the same place (#2031 by @vzaidman) - **[Deprecated]**: String values of `transformer.enableBabelRuntime` (use `true`) (#1957 by @robhogan) - **[Types]**: Add TypeScript definitions for `metro-runtime` modules, and generate (rather than hand-maintain) types for `metro-file-map` workers (#1996 by @robhogan) > NOTE: Experimental features are not covered by semver and can change at any time. - **[Experimental]**: Add `server.unstable_middleware` and `server.unstable_priorityMiddleware` config options, and `runServer` options of the same names, to add middleware after and before Metro's own. `mergeConfig` combines them from both configs: a later config's `unstable_middleware` runs last and its `unstable_priorityMiddleware` runs first (#2031 by @vzaidman) - **[Experimental]**: Add `server.unstable_onServerCreated` config option and `runServer` option of the same name, called with Metro's server instance before the HTTP server listens (#2031 by @vzaidman) - **[Experimental]**: Fix mismatched asset paths in (release) builds under `unstable_serverRoot`, make them always relative to `projectRoot` (#1917 by @robhogan) **Full Changelog**: v0.87.1...v0.87.2 ```
janicduplessis
added a commit
to janicduplessis/react-native
that referenced
this pull request
Oct 21, 2026
…he is shareable across checkouts @react-native/metro-config set asyncRequireModulePath with require.resolve(), which embeds the absolute path of the checkout in Metro's global transform cache key. Two checkouts of the same project (git worktrees, CI workspaces) never shared a transform cache entry. Point it at metro:runtime/modules/asyncRequire instead: Metro's built-in metro: scheme resolver maps it to the metro-runtime Metro itself depends on, from any importer, so it also works for library code that cannot see metro-runtime under an isolated node_modules layout. Requires Metro with react/metro#2083.
janicduplessis
added a commit
to janicduplessis/react-native
that referenced
this pull request
Oct 21, 2026
…he is shareable across checkouts @react-native/metro-config set asyncRequireModulePath with require.resolve(), which embeds the absolute path of the checkout in Metro's global transform cache key. Two checkouts of the same project (git worktrees, CI workspaces) never shared a transform cache entry. Point it at metro:runtime/modules/asyncRequire instead: Metro's built-in metro: scheme resolver maps it to the metro-runtime Metro itself depends on, from any importer, so it also works for library code that cannot see metro-runtime under an isolated node_modules layout. Requires Metro with react/metro#2083.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
React Native sets
asyncRequireModulePathto an absoluterequire.resolve()path, which is hashed into the transform cache key, so caches aren't portable between checkouts (react/react-native#58584). It does that because Metro resolves the module from every importer ofimport(), and a baremetro-runtime/src/modules/asyncRequireisn't resolvable from library code under isolatednode_modules.This adds
metro:runtime/<subpath>, which resolves likemetro:babel-runtime: the same file from any importer, from themetro-runtimeMetro itself depends on (added to the file map as a dynamic root if needed). RN can then setasyncRequireModulePath: 'metro:runtime/modules/asyncRequire'instead of an absolute path. Metro's own default is unchanged.Changelog:
Test plan:
New integration test bundling an
import()withmetro-runtimeoutside every configured root and hierarchical lookup disabled. It fails withmetro-runtime/src/modules/asyncRequireand passes withmetro:runtime/modules/asyncRequire. The existing integration tests now usemetro:runtimetoo, with snapshots unchanged.