Skip to content

doc: define "react-native" community condition

Rodrigo Muino Tomonari requested to merge github/fork/huntie/react-native-community-condition into main

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: https://github.com/react-native-community/discussions-and-proposals/pull/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:

image

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.

image

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.

image

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).

Merge request reports