[mozzius]

Summary

Addresses #1135 behind a new opt-in flag, resolver.unstable_applyBrowserSpecAfterExports.

For a bare import of a package that has "exports", Metro applies "browser" spec redirections (object-valued mainFields) to the requested subpath before it looks the subpath up in "exports". If the redirect target isn't itself an exported subpath, Metro logs "not listed in the "exports"" and falls back to file-based resolution. Two widely used packages hit this on every bundle:

• react-dom/server (react-dom/server cannot be resolved with unstable_enablePackageExports and condition browser #1135): "browser": {"./server.js": "./server.browser.js"} matches the ./server subpath before "exports" does.
• multiformats/hashes/sha2 (a dependency of @atproto/* and many IPFS packages): "browser": {"./hashes/sha2": "./dist/src/hashes/sha2-browser.js"}. The maintainers would rather Metro fixed this than drop the field, which they say some webpack versions rely on (fix: resolve sha hashers via exports in react native multiformats/js-multiformats#345).

The comparison in #1135 found that webpack and Vite resolve "exports" first, then apply the object "browser" map to the resolved file. The conclusion there was that Metro should do the same. With the flag on:

• Packages with "exports": "exports" resolves the requested subpath, without redirecting it first. BROWSER_SPEC_REDIRECTION is then applied to the resolved file, using its closest package.json, including false → empty module. This covers node_modules, nodeModulesPaths and extraNodeModules lookups, Haste packages, and self-references.
• A redirection to a file that doesn't exist: logs a warning and keeps the "exports" target, so the flag can't break an import that resolves without it.
• Subpaths not matched by "exports": same fallback as today (a warning, then file-based resolution with redirections), except that the warning now names the requested subpath rather than the redirect target.
• Unchanged: packages without "exports", relative and absolute imports, and unstable_enablePackageExports: false.

It's opt-in because results can change, not just the warnings. React Native lists "browser" in mainFields but doesn't assert the browser condition on iOS/Android, so under the flag react-dom/server on iOS resolves to server.node.js (the "exports" default target) instead of server.browser.js. With the flag off, the only new work is a boolean check. With it on, there's one extra getPackageForModule call per file resolved from "exports", for the second pass.

Not covered: webpack also applies the "browser" map to "imports" targets. I left that out to keep this change small.

Changelog: [Experimental] Add resolver.unstable_applyBrowserSpecAfterExports to apply "browser" field redirections to files resolved from "exports", as webpack and Vite do

Test plan

New "browser" spec redirections with "exports" block in package-exports-test.js. With the flag on, it covers:

• a subpath (both iOS and web)
• the main entry point
• a key matching the exported subpath that should not redirect it (the react-dom shape)
• false → empty module
• mainFields without "browser"
• a self-reference
• the not-exported fallback
• a redirection to a missing file (warns and keeps the "exports" target), for both an import and a self-reference

Every flag-on case also asserts that no warning is logged, except the two fallback cases, which each assert their one warning. One more test pins today's behavior with the flag off. Against the resolver on main, the flag-on cases fail except the mainFields control.

yarn jest packages/metro-resolver   # pass
yarn flow check                     # no errors
yarn lint && yarn format-check      # pass
yarn verify-api-snapshots           # pass (metro-config / metro-resolver snapshots updated)
yarn jest                           # pass, apart from one FallbackWatcher-test timing failure
                                    # in metro-file-map that passes on rerun (untouched here)

I also ran this branch's resolver against the real published packages. Settings: Expo's defaults, i.e. mainFields ['react-native', 'browser', 'main'] with condition react-native for iOS, and ['browser', 'module', 'main'] with condition browser for web.

Import	Platform	Flag off	Flag on
multiformats@14.0.5/hashes/sha2 (and /sha1)	ios	sha2-browser.js + warning	sha2-browser.js
	web	sha2-browser.js + warning	sha2-browser.js
react-dom@19.3.0/server	ios	server.browser.js + warning	server.node.js
	web	server.browser.js + warning	server.browser.js
multiformats, multiformats/cid, multiformats/basics, react-dom	both	unchanged	unchanged

Happy to rename the flag, or to flip the default in a follow-up once it's had some use.

🤖 Generated with Claude Code

[github-actions]

Metro review: Looks good

Risk: low · Commit: 2d49dab · 9 commands run, in a restricted sandbox after an automated safety assessment

Adds opt-in resolver.unstable_applyBrowserSpecAfterExports, which applies "browser" redirections to the file "exports" resolves to, and now shares one package lookup between the redirect and "exports". No blocking or should-fix issues: with the flag off, head matched base on all 21,768 resolutions over Metro's node_modules and on synthetic edge cases, and the PR's react-dom and multiformats table reproduces. My earlier nit is fixed, and the lookup refactor shows no significant timing change on or off in a synthetic benchmark.

No findings.

Verified

• ✅ yarn jest --no-watchman packages/metro-resolver packages/metro-config packages/metro/src/node-haste packages/metro/src/DeltaBundler/__tests__/resolver-test.js — 18 suites, 472 tests.
• ✅ yarn lint packages/metro-resolver/src/resolve.js packages/metro-resolver/src/__tests__/package-exports-test.js packages/metro-resolver/src/__tests__/package-scope-test.js
• ✅ yarn verify-api-snapshots — 18 snapshots verified.
• ✅ yarn typecheck (Linux VM) — Flow: no errors.
• ✅ jest package-exports-test.js package-scope-test.js browser-spec-test.js (Windows) — 3 suites, 95 tests.
• ✅ node bench/diff.js table — react-dom@19.3.0 and multiformats@14.0.5 match the PR's table, with import added to the conditions: same files, and the warnings are gone with the flag on.
• ✅ node bench/diff.js diff — 21,768 base/head resolutions across 2,721 specifiers: 0 flag-off differences, 0 new throws with the flag on. 12 flag-on changes, all react-dom/server, react-dom/static or @‍noble/hashes/crypto.
• ✅ node bench/diff.js edge — Nested scopes, chains, loops, false, directory targets, self-references, extraNodeModules, nodeModulesPaths: 0 flag-off differences.
• ✅ node bench/diff.js bench — Interleaved base, head flag off and head flag on; results are in benchmarks.

Benchmarks (base vs this PR)

Benchmark	Base	This PR	Change
Resolver, head flag off vs base	102.5ms (100.2-106.3)	99.1ms (95.5-109.5)	no significant change
Resolver, head flag on vs base	102.5ms (100.2-106.3)	101.6ms (99.1-105.5)	no significant change

Method

• Resolver, head flag off vs base: 2,721 specifiers from Metro's node_modules × 5 per sample, iOS, in-memory file context, one process, 21 rounds with rotated order; base always loaded first. Median (range). Getting ranges overlap; lookups fell 93,292 to 82,516 in the separate diff run. bench/diff.js bench
• Resolver, head flag on vs base: Same run as above. Median (range). Lookups in the separate diff run: 93,292 at base, 87,596 with the flag on. In-memory context, so this understates real file map lookup cost. bench/diff.js bench

Not run: Local flow check was denied by this session's permission policy, so Flow ran on the Linux VM instead. Not run: full Jest suite, yarn typecheck-ts, yarn test-smoke, and a benchmark through the real DependencyGraph/TreeFS or on Bluesky. Differential runs used a hand-written context, not TreeFS. Haste with the flag on was only read, not exercised. Relative nodeModulesPaths/extraNodeModules weren't exercised: docs show absolute paths, and the refactor could change which package's "browser" map applies to relative ones.

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

[github-actions]

should fix · A "browser" redirect to a missing file after "exports" silently drops the resolution

redirectPackageExportsResolution passes the redirected path to resolveModulePath and returns its failed result as is. In resolvePackage, that failure goes up to resolveModuleFromTargetPath, which returns null, so the node_modules walk moves on to the next level.

Example: a package has "exports": {"./broken": "./broken-node.js"} and "browser": {"./broken-node.js": "./does-not-exist.js"}, and broken-node.js exists.

• Flag off: pkg/broken resolves to broken-node.js.
• Flag on: the resolution is thrown away with no warning. The import ends in FailedToResolveNameError ("Module does not exist in the Haste module map or in these directories: …"), which names only the node_modules directories it searched. It says nothing about the "browser" entry or the target file. If a parent node_modules has another copy of the package, that copy is used silently.

The self-reference path, by contrast, throws FailedToResolvePathError with candidates. So the same broken entry fails differently depending on how the package was reached.

This breaks the resolver's "errors are data" contract. It also turns a working import into an opaque failure only because the flag was turned on. Existing "exports" handling of a missing target is the model to follow: it raises InvalidPackageConfigurationError with the paths involved, logs a warning and falls back. Suggested fix: when the redirected path fails to resolve, either throw an InvalidPackageConfigurationError that names the package, the "exports" target and the redirect target, or log a warning and keep the "exports" result. Add a test for this case.

_{Reproduced: Repro __review__/__tests__/browser-after-exports-review-test.js ('redirect to a missing file after exports'), run on Linux and Windows, logged: broken -> {"threw":"FailedToResolveNameError","message":"Module does not exist in the Haste module map or in these directories:\n /root/src/node_modules\n /root/node_modules\n /node_modules\n"}. Code path: redirectPackageExportsResolution (resolve.js:710) → resolvePackage returns failed → resolveModuleFromTargetPath returns null (resolve.js:431-435) → the walk continues. · id 609ce9d6}

[mozzius]

Fixed in c9e8e89, taking your second option. A redirection to a missing file now logs an InvalidPackageConfigurationError warning that names the package, the "exports" target and the redirect target. Resolution then keeps the "exports" target, so turning on the flag can no longer break an import that resolves without it. Self-references go through the same helper, so both paths now behave the same. I added a test covering both paths; it fails on 6278f15.

[github-actions]

nit · RESOLVE_PACKAGE spec step omits the missing-redirect-target fallback

Step 1.1.1 says that if the redirection is a different path, Metro returns RESOLVE_MODULE(context, redirectedPath, platform). The code does something different. If that resolution fails, redirectPackageExportsResolution logs an InvalidPackageConfigurationError warning and returns the original "exports" result (resolve.js, in redirectPackageExportsResolution). Resolution.md is meant to describe the algorithm precisely, so it should include this fallback. Suggested wording: "If that resolves, return it; otherwise log a package configuration warning and return result."

_{Evidence: Compared docs/Resolution.md lines 120-123 at head with redirectPackageExportsResolution in packages/metro-resolver/src/resolve.js. The test '[nonstrict] should warn and keep the "exports" target when it is redirected to a missing file' confirms the code's fallback behavior. · id 0b3fe9f6}

[mozzius]

Fixed in 64b4ad8 using your wording: step 1.1.1 now returns RESOLVE_MODULE of the redirected path "if that resolves, otherwise log a package configuration warning and continue". Step 1.1.2 then returns the "exports" result. I also fixed the same gap in PACKAGE_SELF_RESOLVE step 5.1. It still said "return result", but self-references get the same redirection under the flag, so it now performs RESOLVE_PACKAGE step 1.1.1 first.

[github-actions]

nit · A redirect to a directory with an invalid package.json throws instead of falling back

redirectPackageExportsResolution promises that enabling the flag "cannot break an import that resolves without it", and the PR description says the same. That only holds when resolveModulePath returns failed. If the redirect target is a directory whose own package.json has an unresolvable main, resolvePackageEntryPoint throws InvalidPackageError. Neither resolvePackage nor the self-reference path catches that error, so it propagates and the build fails.

Failure case: "exports": {"./dir": "./dir-node.js"}, "browser": {"./dir-node.js": "./broken-dir"}, and broken-dir/package.json with {"main": "./missing.js"}. With the flag off, pkg/dir resolves to dir-node.js. With it on, the import throws InvalidPackageError.

This package shape should be rare. Either catch InvalidPackageError around this call and use the existing warn-and-keep path, or narrow the docblock's claim to missing targets.

_{Reproduced: packages/metro-resolver/src/__tests__/review-2134-test.js, differential pkg/dir: flag off returns /root/node_modules/pkg/dir-node.js; flag on threw InvalidPackageError: The package /root/node_modules/pkg/broken-dir/package.json is invalid because it specifies a main module field that could not be resolved. · id 57a4d3a3}

[mozzius]

Fixed in 7f9c6fe. An InvalidPackageError from resolving the redirect is now caught and goes through the same warn-and-keep path. The warning now says the redirect target "could not be resolved" instead of "this file does not exist", since that wording no longer fits every case. I added your broken-dir case to the existing test.each; it throws on 64b4ad8.

[robhogan]

With the flag on, this PR adds a second closest-package.json lookup per package resolution. isBrowserSpecAppliedAfterExports walks up from the candidate path to check for "exports", and then resolvePackage does the same walk straight after:

metro/packages/metro-resolver/src/resolve.js

Lines 674 to 684 in 64b4ad8

	function isBrowserSpecAppliedAfterExports(
	context: ResolutionContext,
	absoluteCandidatePath: string,
	): boolean {
	return (
	context.unstable_applyBrowserSpecAfterExports &&
	context.unstable_enablePackageExports &&
	context.getPackageForModule(absoluteCandidatePath)?.packageJson.exports !=
	null
	);
	}

metro/packages/metro-resolver/src/resolve.js

Lines 621 to 623 in 64b4ad8

	if (context.unstable_enablePackageExports) {
	const pkg = context.getPackageForModule(absoluteCandidatePath);
	const exportsField = pkg?.packageJson.exports;

It's measurable - on Bluesky, turning the flag on makes node_modules resolutions ~4% slower (~1% of resolution overall). Could we look the package up once in resolveModuleFromTargetPath and pass it down? Roughly:

const pkg = context.getPackageForModule(targetPath);
const candidate =
  pkg == null ||
  (context.unstable_applyBrowserSpecAfterExports &&
    context.unstable_enablePackageExports &&
    pkg.packageJson.exports != null)
    ? targetPath
    : redirectPackageSubpath(context, targetPath, pkg, pkg.packageRelativePath);
// ...
const result = resolvePackage(
  context,
  candidate,
  platform,
  candidate === targetPath
    ? pkg
    : context.unstable_enablePackageExports
      ? context.getPackageForModule(candidate)
      : null,
);

...with resolvePackage taking the package rather than looking it up, and isBrowserSpecAppliedAfterExports dropped. redirectModulePath does its own lookup too, so this also removes one that's on main today. With this shape, turning the flag on is no slower than main without it.

The other reason I'd like this: we currently read "exports" from the package.json closest to the requested subpath, not the one at the package root, so a nested {"type": "commonjs"} or a legacy shim package.json hides the root's "exports" (Bluesky hits this with @floating-ui/utils/dom). That's a separate bug and not for this PR, but the fix is to change where the package comes from. With two independent lookups it'd need changing in both - otherwise, with the flag on, we'd see no "exports" in the nested one, apply the "browser" redirect first, and then run the root's "exports" on the redirected subpath. With one lookup it's a change in one place.

AI-driven benchmark (Bluesky, iOS and web as Expo configures them):

	node_modules resolutions	All resolutions
This PR, flag on vs off	+3.9% to +4.6%	+0.7% to +0.8%
One lookup, flag on vs main	-0.9% to -1.6%	-1.2% to -2.3%
One lookup vs this PR, both flag on	-4.3% to -7.9%	-1.8% to -4.6%

Each resolution the app makes (~25k, ~6k of them in node_modules) is replayed through DependencyGraph with the resolution cache cleared, both checkouts in one process, 30 rounds with the order rotated every round and both load orders checked. Figures are medians of paired per-round ratios, the range across platforms (and load orders for the last row). The one-lookup version changes no resolutions or warnings on Bluesky, and the resolver tests pass with one lookup-count expectation in package-scope-test.js going down by one.

[mozzius]

Thanks for the benchmark! Done in 7572574, following your sketch:

• resolveModuleFromTargetPath looks the package up once and passes it to resolvePackage.
• isBrowserSpecAppliedAfterExports is gone.
• The Haste path still does its own lookup, and only when exports are enabled, like before.

As you said, the package subpath with package exports expectation in package-scope-test.js drops by one lookup.

I also added a flag-on case there to pin the one extra lookup that remains. The second pass has to read redirections from the scope of the file that "exports" resolves to, because that can be a nested package.json.

Agreed on the nested package.json hiding the root's "exports" being a separate bug. With one lookup, changing where pkg comes from now fixes it for both the redirect and "exports" in one place.

Separately, 7f9c6fe fixes the review bot's last nit: a redirect to a directory with an invalid "main" threw instead of falling back.

[robhogan]

Thanks for this!

[robhogan]

@mozzius Is this something you're hitting in the wild? Do you need it releasing under any particular Metro/Expo version?

[mozzius]

Is this something you're hitting in the wild? Do you need it releasing under any particular Metro/Expo version?

No, not to my knowledge, it just triggers an annoying warning 😅