RFC: introduce reactNativeManifest to package.json

[kelset]

This RFC wants to introduce and formally discuss a new section for the package.json of a react-native project (app or library), called reactNativeMetadata.

This new section will allow developer to express certain characteristics of their code in a more formalized manner, that can easily used by tooling to act towards the code accordingly.

Note well: this is but the first draft of the actual shape and fields. The goal of this draft is to collect feedback and help finalise the spec for this section.

---

You can read more details in the text itself - here's the file view for easier reading experience.

[cortinico]

Thanks for the writeup @kelset
I'll do a further review in the next days. I'll just left one thoughts I had on top of my mind

[NickGerleman]

As this grows, or if we want to allow it to be dynamic, or extendable from a base, it seems beneficial to allow mirroring into a react-native.config.js outside the direct package.json (maybe not named that since already taken). E.g. see recent template change moving Jest config out of package.json (or... cosmic-config bits).

[kelset]

react-native.config.js already exists and is used for CLI stuff (see https://github.com/react-native-community/cli/blob/main/docs/configuration.md#configuration) - it is an explicit goal of this metadata field to be entirely separate.

[NickGerleman]

Call it something else as an example, but it seems like the app fields are being used for configuration. If that configuration becomes non-trivial, it may scale badly inlined into each package.json vs being shareable. Like, say, a root eslint.config.js or jest.config.js. The mapping of foo in package.json to foo.config.js is also somewhat expected by convention imo.

[NickGerleman]

filled only with metadata to be read by package managers and other tools

What does this mean? It seems like it allows it to be used for almost anything.

[cortinico]

As this grows, or if we want to allow it to be dynamic, or extendable from a base, it seems beneficial to allow mirroring into a react-native.config.js outside the direct package.json

Could you clarify on why we want this now? This is something we can still add later if we wish and the current design is not preventing it. Or am I missing something?

[motiz88]

package.json of a react-native project (app or library), called reactNativeMetadata

High-level comment: I don't think solving for apps and libraries with the same mechanism is the right call. package.json should ideally contain only configuration/metadata that applies to the code within that package, makes sense in the published version of the package, and is respected by all relevant tools when the package is transitively included in an app project. App-level config should live elsewhere (and probably already does).

[kelset]

hey folks - quick update here: there have been some conversations happening behind the scenes but current goal is to get to a new level of alignment on the topic and update the PR here by end of next week

[motiz88]

I've spent some time reading this RFC and talking to @cortinico, and I've identified my main issues with it. I'll start with the more focused points, with broader concerns towards the end.

Autocomplete / IDE support

If we add a field to package.json as opposed to a separate file, what are our options for providing a schema that developers can plug into their IDE to get autocompletion etc? Do IDEs like VS Code offer ways to compose extended schemas onto the base package.json schema? (Any DSL we invent should have a good authoring experience as a baseline expectation, so we should design for this even if it's not the top priority.)

Naming

This is a small & bikesheddy point, but I'm gravitating towards reactNativeManifest as the name, inspired by Android manifest files. (And hey, at least I'm not proposing XML. 😅) In my view the term "metadata" can range from human-readable and imprecise to machine-readable and well-defined; the name should convey that this is more the latter, and I feel like "manifest" does it a bit better than "metadata".

Scope creep (current and future)

A "bag of properties" config paradigm can easily end up confusing people by conflating properties that apply at different times, to different scopes, and have different levels of strictness / user-friendliness. In short, we need to ensure this mechanism stays cohesive and easy to learn. We should apply a lot of scrutiny to potential use cases here and lay down stronger guidelines on what's a good fit for reactNativeMetadata vs some other mechanism.

The current proposal introduces reactNativeMetadata with the following description:

This new section will allow developer to express certain characteristics of their code in a more formalized manner, that can easily used by tooling to act towards the code accordingly.

I think that's too open-ended. I'd propose wording to the effect of:

reactNativeMetadata is an optional object in package.json describing specific aspects of the package that are unique to integrating with React Native, which cannot be inferred from standard fields in package.json. It's mainly intended to enable package discovery, autolinking and build-time validation in React Native projects. The metadata is intended to be useful both for published packages (e.g. on npm) and private/workspace packages. The scope of the metadata extends only to files included in the package, excluding any files under ./node_modules.

Concretely:

• metroExportsMode does not fit here: it's not specific to integrating with React Native (as Metro can also be used outside of React Native). I propose that if we want to create this flag in the future, we leave it outside of reactNativeMetadata
• requirements seems redundant given that peerDependencies exists (discussion). Even if there are theoretical benefits, they will be hard to teach and maintain. I propose that we remove this and separately explore using peerDependencies (in combination with peerDependenciesMeta?) to solve the same problem.
• I would suggest that we specify here that the semantics/shape of reactNativeMetadata can only change further via a follow-up RFC (and tool-specific extensions are strictly disallowed).

What is the big picture design?

tl;dr for the purposes of this RFC: we should not block on solving this much larger challenge, BUT we should ruthlessly limit the scope to what's immediately useful so that we can focus future efforts on a more comprehensive solution.

To put it bluntly, it feels like we're dancing around the lack of an end-to-end, user-extensible, designed, build system for native code in React Native projects. We do have a patchwork of systems in place, that many people are using successfully, but the ad hoc nature of these solutions leaves us with a poor caching/incremental builds story, scattered documentation, duplication of tools/effort, wildly differing levels of polish, and - yes - an unclear source of truth for build configuration in a project.

AFAICT, reactNativeMetadata aims to partially address the "source of truth" problem, which is great - but I worry that we may be adopting constraints that wouldn't really work for a more fundamental solution. For example, the use of JSON to express what is essentially build logic (which even includes conditionals, i.e. platforms) seems short-sighted from this perspective. The more complexity we add down the line, the more we will start straining against the lack of Turing-complete facilities and other features of mature build systems. (Or worse: we will start adding them in... badly. See Greenspun's tenth rule.)

Concretely, we should put resources towards designing the overall build system for React Native, and think of our current efforts as the first few steps towards that broader vision.

That cohesive system may or may not be based on Buck; it's much too early to take a firm stance either way. (And frankly this idea might not even materialise soon - for now I'm mainly hoping to start a discussion around it.) But the concept of specifying a single cross-platform graph of build actions, encompassing all the configuration, codegen, compilation, linking, and bundling in a React Native project, is something that Buck makes relatively natural - so I think it's one of the options we should evaluate more closely.

To be clear, there are tough design problems here, e.g. how the unified build system should interoperate with Xcode / Android Studio / and their underlying build systems & package managers - and I'm not claiming to have complete answers at this stage. But there are encouraging precedents at Meta for tools that do glue Buck with Xcode and Android Studio while providing a good and consistent developer experience.

[cortinico]

Hey all,
I know this RFC was silent for a bit. We reworked it quite substantially to reduce the scope a bit and make it more focused on supporting capabilities. I would be supporting @kelset in driving this forward and I'd like to get another round of review

[brentvatne]

• requirements seems redundant given that peerDependencies exists (discussion). Even if there are theoretical benefits, they will be hard to teach and maintain. I propose that we remove this and separately explore using peerDependencies (in combination with peerDependenciesMeta?) to solve the same problem.

I want to push back against this point - the peerDependencies field brings a lot of baggage with it, and in the React Native ecosystem it often leads to a bad user experience in the form of unactionable/unhelpful error messages and obscure bugs related to package hoisting or duplicate versions of packages installed, where only a single version actually ever makes sense in the project (eg: for native modules, where only one version can be linked at any given time).

That said, I do appreciate your point about tightening this specification up and I think we could simplify the requirements field by allowing only specific keys instead of arbitrary package names. I think the most important ones to support are react-native and expo. This would allow us to recommend that library authors express peer dependencies on react-native and expo using the * matcher, which indicates they are required but otherwise mostly skips the default package manager peer dependency validation (this validation would break with alpha/beta/rc releases) and delegates those validations to tools that we build instead. We can use this information for a few purposes:

• Show version compatibility on https://reactnative.directory
• Validate project dependencies against that data
• Upgrade package versions automatically when upgrading React Native versions based on that data
• Installing correct versions of packages for the given React Native / Expo versions

[lunaleaps]

How do other libraries determine this? I guess it's not really a problem because we need to be able to catalogue libraries specifically for React Native?

[cortinico]

How do other libraries determine this?

What do you mean with "other libraries". Like other ecosystems?

[lunaleaps]

Oops yes other ecosystems. I'm guessing they have similar directories. Are they all maintaining it manually?

[lunaleaps]

Is this only for apps? I'm guessing it doesn't make sense for a library to specify flags? But I guess there could be a library that enforces a certain feature flag?

[cortinico]

It's for both apps and libraries. There could be a scenarios where a capability needs all the dependencies to expose such capability (for example the newArch one).

[lunaleaps]

Would this proposal enforce this? Like if a library specifies a certain feature flag, and an app uses that library, how do we communicate this?

[cortinico]

Would this proposal enforce this? Like if a library specifies a certain feature flag, and an app uses that library, how do we communicate this?

That's up to each feature to define the semantic of such flags. That's also why we need a dedicated RFC for each feature. There might be features that have a hard requirement on dependencies (like the New Architecture Renderer) and other features that have fallbacks

[cortinico]

I want to push back against this point - the peerDependencies field brings a lot of baggage with it, and in the React Native ecosystem it often leads to a bad user experience in the form of unactionable/unhelpful error messages and obscure bugs related to package hoisting or duplicate versions of packages installed, where only a single version actually ever makes sense in the project (eg: for native modules, where only one version can be linked at any given time).

Thanks for flagging this @brentvatne. I think we'll probably have a separate RFC to decide how to proceed with either peerDependencies, requirements or any other mechanism to provide better support for version alignment.

I do personally like your direction of allowing only react-native and expo as it will make it more predictable and easy to validate for users.

[migueldaipre]

The newArch flag sounds strange to me. For me users new to the React Native ecosystem shouldn't know it as "newArch" or "oldArch".

[cortinico]

The newArch flag sounds strange to me. For me users new to the React Native ecosystem shouldn't know it as "newArch" or "oldArch".

For context, that's how it's called today:
https://reactnative.dev/docs/new-architecture-app-intro#android---prerequisites
Renaming features is outside the scope of this RFC

[cipolleschi]

I left some comments. Most of them are fixes for typos, but I left also a couple of questions.

[cipolleschi]

would this be a part of React Native core or a feature we want to defer to frameworks?

[cortinico]

This is framework/tooling responsibility. Is added here to provide context on what we believe could be valuable use cases of those APIs

[cipolleschi]

I left some comments. Most of them are fixes for typos, but I left also a couple of questions.

[cipolleschi]

Hey folks, I created a(nother) PR with some small updates on this.
Let's move the conversation there!