Skip to content

Commit d60222b

Browse files
kelsetcipolleschi
kelset
authored and
cipolleschi
committed
add RFC for reactNativeMeta
1 parent 8995818 commit d60222b

File tree

1 file changed

+148
-0
lines changed

1 file changed

+148
-0
lines changed

‎proposals/0011-introduce-reactNativeMeta.md

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: Introducing `reactNativeMeta` to `package.json`, for RN specific metadata
3+
author:
4+
- Lorenzo Sciandra
5+
date: 25-01-2021
6+
---
7+
8+
# RFC0011: Introducing `reactNativeMeta` to `package.json`, for RN specific metadata
9+
10+
## Summary
11+
12+
This RFC wants to introduce and formally discuss a new section for the package.json of a react-native project (app or library), called `reactNativeMeta`.
13+
14+
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.
15+
16+
**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 finalize the spec for this section.
17+
18+
## Basic examples
19+
20+
This is how this section would look like...
21+
22+
...for a library:
23+
24+
```json
25+
{
26+
"name": "@rnx-kit/metro-serializer",
27+
"version": "1.0.11",
28+
...,
29+
"reactNativeMeta": {
30+
"version": "2.3",
31+
"type": "library",
32+
"features": {
33+
"fabric": "true",
34+
"android": {
35+
"turbomodules": "true",
36+
},
37+
},
38+
"requirements": {
39+
"react-native": ">= 0.71.0",
40+
"expo": ">= 46.0.0",
41+
"expo-modules-core": "1.2.0"
42+
}
43+
...
44+
}
45+
```
46+
47+
...for an app:
48+
49+
```json
50+
{
51+
"name": "contoso",
52+
"version": "2.0.3",
53+
...,
54+
"reactNativeMeta": {
55+
"version": "1.0",
56+
"type": "app",
57+
"features": {
58+
"newArchEnabled": "true",
59+
"android": {
60+
"codegen": "true",
61+
"turbomodules": "true",
62+
},
63+
// Future example
64+
// "metroExportsMode": "strict"
65+
},
66+
...
67+
}
68+
```
69+
70+
## Motivation
71+
72+
The conversation that originated this idea was [an ask from the Meta team](https://github.com/microsoft/rnx-kit/issues/1863) to have `align-deps` help developers in the community migrating to the new architecture by providing insights into which libraries would have Fabric/TM support. Very quickly it became clear that there is currently no straightforward way to know if a library indeed has that support.
73+
74+
A similar problem was also encountered by [React Native Directory](https://reactnative.directory/), that tried to [programmatically infer](https://github.com/react-native-community/directory/pull/870) support via the presence of certain fields in the package.json of a library - this because one can get access to the manifest file via npm without having to download the entire node_module.
75+
76+
It became clear that there was a need to be able to communicate and parse certain information about a react-native library via its `package.json`, which led to [a meeting](https://github.com/microsoft/rnx-kit/discussions/2125) between Meta, Microsoft and Expo to figure out a common solution.
77+
78+
This RFC is the result of that meeting: a new section of the `package.json`, called `reactNativeMeta`, to contain certain metadata about a react-native project - it being either a library or an app.
79+
80+
There are a few areas that this section could express in a consistent manner; here's a list of the ones we could think of (in no particular order):
81+
82+
- if a library supports the new architecture, turbo modules or fabric or both
83+
- which versions of react-native a library supports in a given release
84+
- if an app has opted in into Fabric, TM, or both
85+
- if an app is using Hermes or another js engine
86+
87+
Sidenote: the name `reactNativeMeta` was chosen to mirror the camel case pattern used by other fields such as `peerDependenciesMeta`.
88+
89+
## Detailed design
90+
91+
This is the section that in this first draft will need to be properly finalised. For now, here's what we envisioned:
92+
93+
```js
94+
reactNativeMeta: {
95+
version: string, // ex. 1.0.0 - we know that this spec might evolve in the future
96+
type: string; // "app" or "library"
97+
features: {
98+
// can be global...
99+
newArchEnabled: boolean,
100+
hermesEnabled: boolean,
101+
// ...or platform specific
102+
android: {
103+
newArchEnabled: boolean,
104+
fabric: boolean,
105+
turbomodules: boolean,
106+
hermesEnabled: boolean,
107+
},
108+
ios: {
109+
... // same as android
110+
},
111+
macos: {
112+
... // same as android
113+
},
114+
windows: {
115+
... // same as android
116+
},
117+
// more platforms, params - add a comment here
118+
},
119+
// this section would most likely only be relevant for libraries
120+
requirements: {
121+
react-native: string, // semver compliant range of versions of RN supported
122+
expo: string, // semver compliant range of versions of Expo supported (if any)
123+
}
124+
}
125+
```
126+
127+
## Drawbacks
128+
129+
The main drawback is that we'd need to convince developers to start using it, so we'd have to expect a phase in which only a part of the userbase has this section configured and tool developers need to account for the section missing entirely.
130+
131+
## Alternatives
132+
133+
This section is, in itself, fully original and new: there are other files that are used to define configurations for various aspect of react-native based projects (such as `react-native.config.js`, `app.json`, Expo's `app.config.js`, `expo-module.config.json`) but by design this section does **not** overlap with any of them. Explicitly, this one has the purpose of being filled only with metadata to be read by package managers and other tools.
134+
135+
## Adoption strategy
136+
137+
Once the v1.0.0 version of the shape is finalised, we can start integrating it across the board in tools such has `align-deps` and the RNDirectory, and in the react-native tools themselves. This first wave of support would have to be coordinated around a certain release that lives in RN's main branch, such as now it'd be introduced in 0.72 (which branch has not been cut).
138+
139+
After adding this first wave of support, and related documentation, we could more broadly communicate to the community and the maintainers how adding this section would benefit them too. Especially for library maintainers we'll have another RFC coming up soon to describe how we are planning to better communicate this.
140+
141+
## How we teach this
142+
143+
- add to core's documentation (which should happen anyway if we start using it for flags for new arch configuration)
144+
- have RNDirectory and align-deps mention a call to action to introduce this
145+
146+
## Unresolved questions
147+
148+
v1.0.0 of the shape needs to be finalized.

0 commit comments

Comments
 (0)