doc: define "react-native" community condition

[huntie]

I'm a React Native maintainer working on Metro, our first-party JavaScript bundler. Here I'm proposing the inclusion of a "react-native" condition under the "Community Conditions Definitions" section of Node's docs.

This is linked to our framework proposal for package exports support: react-native-community/discussions-and-proposals#534.

Why this condition is needed

React Native is a popular platform within the JS ecosystem, where code can be executed in non-browser environments, such as our Hermes JavaScript engine. When package maintainers want to target React Native, we have historically provided a top-level "react-native" root field within package.json — which was an extension of the "browser" field spec (now itself a community condition).

e.g. Used by pusher-js:

As with "browser", we are aiming to translate "react-native" to the conditional exports concept.

What the "react-native" condition will represent

These are unchanged from current use of the "react-native" root field.

• Modules are being required by a React Native app.
• JavaScript code will be executed under the Hermes or JavaScriptCore runtimes, or a web browser.
• Modules are most likely being loaded under Metro and babel-preset-react-native.

What will change when this is used as a condition via "exports":

• Because "exports" allows packages to define the order of conditional exports, package maintainers will have more fine-grained control over what is selected for their package (e.g. matching before, or after, "browser").

Prior usage

Use of "react-native" root field

This is a popular feature and is used by both React Native-specific libraries and larger multiplatform libraries (such as the above pusher-js example). Searching across GitHub, use of the top-level "react-native" field for specifying alternate source files is present in ~20k repositories.

Use of "react-native" package exports condition

Webpack already lists "react-native" under its docs for Package exports, which is enabled when configured by the user or in templates under React Native projects.

From this we can infer there is independent desire for such a condition, and perhaps limited use today. The definition it provides is "TBD", leaving us to provide the concrete and canonical definition with this PR.

How we teach this

Once "exports" support is ready in Metro:

• We will update the primary template for new React Native libraries: create-react-native-library.
• We aim to publish a Metro/React Native website blog post with an upgrade guide for package maintainers.

With the merging of this PR:

• Package maintainers can optionally get their packages ready for conditional exports in React Native using the documented definition, which we are set on.
  • This will work in Webpack today, but not Metro (until support is shipped).

[nodejs-github-bot]

Review requested:

• @nodejs/modules

[GeoffreyBooth]

There’s a spec in progress for this: nodejs/tooling#166. I assume we should defer to that spec? cc @nodejs/tsc @guybedford

[ljharb]

+1, but this submission aligns with it so far afaict.

[mcollina]

generically +1, with the WinterCG caveat

[huntie]

There’s a spec in progress for this: nodejs/tooling#166. I assume we should defer to that spec? cc @nodejs/tsc @guybedford

@GeoffreyBooth Thanks for raising, we also gave input on the WinterCG spec. Worth noting that "react-native" is subtly different in that context:

• WinterCG runtime key
  Describes JS runtime environments, therefore represents React Native JS runtimes on native platforms only (Hermes and JavaScriptCore) — and not in browsers via React Native for Web.
• "exports" condition (this submission)
  Represents React Native projects and matches all runtime platforms (native and web). This is motivated by 1) giving package maintainers control over inclusively matching "react-native" before/after "browser", and 2) consistency with our previous package.json field concept.

[mhdawson]

LGTM

[huntie]

Hi all, is this good to merge? :)

[nodejs-github-bot]

Landed in d09f0c4