RFC: Metro package exports support

[huntie]

This adds a new RFC containing the intended design and rollout strategy for package exports support within Metro, which will affect how React Native apps consume npm packages and how package authors expose modules to React Native apps.

NOTE: This is a mostly-ready first pass which I'm opening now in order to link related conversations to. Further commits will be stacked to address early feedback.

• ⬇️ Near-term planned changes

---

Recommended (in the Files changed tab): "Display the rich diff"

[huntie]

Near-term planned changes

From initial internal and external feedback round. These are being strongly considered to form updated versions of this proposal.

cc @motiz88 @robhogan @EvanBacon @kelset (+ others)

1. Move strict handling out of current proposal

The surface area of this proposal is large and we want to be sure that package maintainers understand changes correctly and are not burdened by too many framework decisions at once (e.g. the new architecture migration is concurrently being pushed to the community).

Most of the benefits of "exports" relevant to React Native app developers will be adequately delivered by the proposed lenient handling by Metro, and "metroExportsMode": "strict" presents complexity and footguns both to us and to package maintainers in implementing this correctly. Therefore it makes sense not to ship metroExportsMode immediately.

Proposed: Split out all strict mode references into a future RFC (for a future effort).

2. Widen definition and behaviour of "react-native" condition

Expand the "react-native" condition to represent all React Native platforms (more conceptually and community aligned), provide info on how packages should correctly use this with "browser" for react-native-web support (i.e. guide the introduction of the "react-native" condition correctly).

Proposed: Metro will assert both conditions.
Possible alternative: Metro gives precedence to "browser" when platform = 'web' — but non-spec compliant.

Relevant discussion: #535 (comment)

3. Handling of platform-specific extensions under "exports"

The current plan of deciding to try extra files based on extensionless "exports" keys is very loose behaviour and possibly spec-conflicting enough to break in other bundlers.

This could be redesigned now or deprioritised and handled as a future decision + feature — particularly as we offer alternatives for the same functionality without platform extensions.

---

Note: "Near-term" = reasonably soon. I'm likely to focus on other internal project priorities before getting back to this.

[motiz88]

Re asserting both "react-native" and "browser" everywhere and proceeding as per spec (picking the one specified first if both are specified): I think this is the right call as the least breaking change that preserves the most future value. IMO it goes hand-in-hand with keeping the default resolverMainFields: ["react-native", "browser", "main"] setting in the CLI. The key difference is that with exports, package authors wishing to provide both browser and react-native entry points can control which one gets selected.

[kelset]

hey @huntie just wanted to check in - what's the status of the work and/or of this PR? any blockers we can help with?

[huntie]

@kelset No blockers as of the "Near-term planned changes" note above. I haven't started implementation yet due to internal project scheduling (have been working on another thing for the last couple of months), but I wanted to get questions answered for "exports" earlier and get this RFC (and Node RFC) in public.

I'm aiming to push the updated RFC doc (incorporating planned changes) to this branch next week, then seeking to merge this PR. Will ping you and others for an approval at that time.

[SimenB]

FWIW, facebook/react-native#35203 has landed, so the Jest env used in the preset uses it (or, will when published)

[huntie]

Changes in 1a25973

(Planned changes above were integrated in e510faa.) Following this, I've pushed another revision addressing further feedback, and have ended up inverting our plans around backwards compatibility for exact path specifiers and platform-specific extensions — we would prefer to make handling of these cases breaking in order to follow the "exports" spec correctly (discussed with @motiz88).

Significant changes:

• Now breaking: "exports" subpath is preferred in a path conflict.
• Now breaking: "exports" subpath is used if matched, blocking platform-specific extensions resolution.

More detail on:

• Dynamic configuration of asserted condition names.
• Anticipated breaking change risk levels.
• Nested conditions support is now P0.

As of these changes, I'm looking to have the proposal accepted and merged.

[matthew-dean]

What about subpath imports? Is there a separate RFC for this?

[huntie]

@matthew-dean Briefly noted on L78: We aren't committing to implementing subpath imports right now, but it might be something we can follow up with quickly next year.

[motiz88]

This is stellar work! Thanks @huntie for shepherding it through all the design discussions. LGTM, with one thing I'd love to see clarified re: path conflicts.