[janicduplessis]

Summary:

@react-native/metro-config sets asyncRequireModulePath with require.resolve(), an absolute path into the current checkout. Metro hashes the whole transformer config into its global transform cache key (metro-transform-worker getCacheKey), so two checkouts of the same project (git worktrees, CI workspaces, a renamed directory) never share a transform cache entry. Nothing fails; the cache is just cold for every checkout.

A bare specifier is not an option: Metro inlines it into every module with an import(), including library code, and under an isolated node_modules layout a library cannot see metro-runtime or react-native (see the resolution table below).

This uses metro:runtime/modules/asyncRequire instead, added in react/metro#2083. Metro's built-in metro: scheme resolver maps it to the metro-runtime that Metro itself depends on, from any importer, like metro:babel-runtime. The string is checkout-independent, so the cache key is too. @react-native/metro-config no longer requires anything from metro-runtime, so the dependency is dropped (Metro resolves metro:runtime from its own copy).

Requires a Metro release that includes react/metro#2083. There is none yet (latest is 0.87.1); on current Metro the scheme resolver throws Unsupported 'metro:' pathname for every module with an import(). This should land together with the metro-config dependency bump to that release.

• Dev-only side effect of sharing caches: __source.fileName (_jsxFileName, from @babel/plugin-transform-react-jsx-source, which the preset enables in dev) embeds the absolute path of the checkout that transformed the module, so checkout B served from A's cache shows A's paths there (73 modules in the template app; source maps are unaffected). Metro's own default config and Expo already share caches this way. I checked babel-plugin-module-resolver (root and alias), which emits relative paths, so its output is identical across checkouts.
• Custom resolvers see metro:runtime/... before the scheme resolver does (metro-resolver resolve). One that handles every non-relative specifier itself instead of delegating to context.resolveRequest would need to pass metro: through, same as for metro:babel-runtime.

Changelog:

[GENERAL] [FIXED] - Make Metro's transform cache shareable across checkouts by pointing asyncRequireModulePath at metro:runtime/modules/asyncRequire instead of an absolute path

Test Plan:

All tests use Metro built from main at 3de6a03 (the commit of react/metro#2083), packed as 0.87.1 tarballs and installed over every metro* package via overrides, and @react-native/metro-config@0.88.0 with this change applied to the installed file.

Cache sharing across checkouts. A fresh @react-native-community/cli init app on 0.88.0 copied to a second directory, both using one FileStore cache dir, react-native bundle (dev, iOS) in A with --reset-cache and then in B, with the file map already warm:

config	A (cold)	B
this PR	7.2 s	2.1 s
current require.resolve	5.9 s	5.7 s (every transform recomputed)

B's bundle from the shared cache is byte-identical to a cold B bundle except for the _jsxFileName strings above. With babel-plugin-module-resolver (root: ['./src'], alias: {'@app': './src'}) in the Babel config, A and B cold bundles differ only in those same strings.

Resolution from library code. A pnpm workspace with nodeLinker: isolated and hoist: false: apps/app depends on react-native@0.88.0 and a workspace package packages/lazy-lib whose index.js does import('./lazy') and declares no dependencies. Metro.runBuild of the app with getDefaultConfig and each asyncRequireModulePath:

asyncRequireModulePath	result
absolute require.resolve() (current)	ok
metro-runtime/src/modules/asyncRequire (Metro's default)	Unable to resolve module metro-runtime/src/modules/asyncRequire from <repo>/packages/lazy-lib/index.js
react-native/asset-registry (probe for a react-native/* entry point)	Unable to resolve module react-native/asset-registry from <repo>/packages/lazy-lib/index.js
metro:runtime/modules/asyncRequire (this PR)	ok

End to end. The same template app with App.tsx rendering React.lazy(() => import('./src-lazy')), built and launched on an iOS simulator against react-native start. Metro serves the main bundle with node_modules/metro-runtime/src/modules/asyncRequire.js inlined, then src-lazy.bundle on demand, and the lazy component renders with no errors in the Metro or app logs.

Cache key. The transformer-config segment of Metro's global cache key (metro-transform-worker getCacheKey) for two checkouts at /Users/x/app-a and /Users/x/app-b:

A abs : 4045a4cb2cabe49b5e47e841967c2306
B abs : b3b399e7c2f3f4659bcd815c0e0377b5
A new : 0c3f3e49043e70278a0be83a58932f59
B new : 0c3f3e49043e70278a0be83a58932f59

[javache]

react-native/asset-registry is a different use-case though, it points at a module that's actually internal to RN.

What would it take to allow metro-runtime/async-require as the package-relative specifier here?

[janicduplessis]

@javache The other option that works is using

+      extraNodeModules: {
+        'metro-runtime': path.dirname(
+          require.resolve('metro-runtime/package.json'),
+        ),
+      },

in the default metro config, but I thought adding the file seemed like a better idea since we do it for other configs (although as you said it is to access internal RN module instead of other package).

[janicduplessis]

@rubennorte @motiz88 Little ping on this :)

[javache]

cc @huntie @robhogan - can you review?

[robhogan]

I don't think this approach is safe unfortunately. Currently, asyncRequireModulePath is injected into require() statements of every module that has an import(), including library files.

Absolute paths obviously work because they're not sensitive to the origin, but no relative or bare specifier is safe on its own - under isolated node modules neither metro-runtime nor react-native are necessarily resolvable from source under transform.

Expo gets away with it because the specifier is intercepted by a custom resolver and pointed at a known location, but on the default resolver this PR would break folks.

asyncRequireModulePath is already deprecated in favour of the __loadBundleAsync runtime hook. If we could I'd be inclined to just remove it while we're in a breaking change window. Expo bolts a lot onto it currently though, beyond what can be replaced by __loadBundleAsync.

Otherwise, I think the cleanest approach is to use the new metro: scheme resolvers and change the default to (say) metro:runtime/modules/async-require after adding that to Metro. That's directly analogous to the way we (as of main) resolve metro:babel-runtime, ensuring it's resolvable from anywhere.

Separately, if cache portability has indeed been accidentally broken by this for most users, I'd want to make sure fixing cache re-use doesn't inadvertently expose issues with common setups. babel-plugin-module-resolver is one I'd be wary of.

[robhogan]

I've opened react/metro#2083 to allow us to point at metro:runtime/... - it'll be useful for internal resolution even if we end up removing the configurable path.

[janicduplessis]

@robhogan Updated to use the new metro api, so it should be good to go when it releases. I tested locally by packing it.

I also verified with babel-plugin-module-resolver and it didn't seem to cause any issues. It resolved via relative paths.

[janicduplessis]

The only thing I saw was _jsxFileName which still contains an absolute path, not sure if worth fixing.

[javache]

Blocked on metro release.