Revamp React Native Manifest proposal

cipolleschi · cipolleschi · commit d4cacd6f15e9 · 2023-10-06T10:49:08.000+01:00
diff --git a/proposals/0012-introduce-reactNativeMetadata.md b/proposals/0012-introduce-reactNativeMetadata.md
@@ -3,6 +3,7 @@ title: DRAFT | Introducing `reactNativeManifest` to `package.json` for React Nat
 author:
 - Lorenzo Sciandra
 - Nicola Corti
+- Riccardo Cipolleschi
 date: 25-01-2021
 ---
 
@@ -14,24 +15,33 @@ date: 25-01-2021
 
 This RFC introduces and formally discuss the concept of _React Native Manifest_, a set of metadata about a React Native project (either app or library). This metadata can be consumed by tooling to enhance the developer experience and support the React Native ecosystem.
 
+This would be the entry point for all the official configurations supported by the core of React Native. Examples (not an exhaustive list) of these configurations could be:
+* Whether the New Architecture is enabled or not.
+* Which JS Engine should run in the app.
+This will not be the place where we can add any kind of configuration.
+
 Practically, this RFC proposes to add a `reactNativeManifest` section to the `package.json` file of a React Native app or library.
 This new section will allow developers to follow a declarative approach to express capabilities of apps and libraries in a more formalized manner.
 
 ## Rationale
 
-The need to specify **capabilities and metadata** for a react-native library is inherent to the React Native ecosystem.
+The need to specify **capabilities and metadata** for a react-native library is inherent to the React Native ecosystem. This need is so evident that various frameworks provided their own ways to specify those values. Look at `react-native.config.js` for the CLI or `expo.config.js` for Expo.
 
-As of today, there is no simple programmatic way to know if a NPM package is a React Native library. Good indicators could be:
+Another issue is that, as of today, there is no simple programmatic way to know if a NPM package is a React Native library.
+We have some heuristics, though:
 * Presence of a `react-native:*` dependency in the `peerDependencies` section of the `package.json` ([example](https://github.com/RonRadtke/react-native-blob-util/blob/80628d418a5c81439dc2c1a1f05fae6406f0ba7f/package.json#L46C10-L49))
 * Presence of React Native specific files such as `react-native.config.js` files
-Those indicators are all non-exhaustive. 
+Those indicators are all non-exhaustive.
 
-Similarly, there is no easy way to understand if a library is exposing a native module or not. 
-The React Native CLI is facing this difficulty and tries to circumvent it by inspecting the native code and searching for subclasses of `*ReactPackage` using complex regular expressions ([example](https://github.com/react-native-community/cli/blob/605c542d18efcb02f217d3c85726fa73a79054c2/packages/cli-platform-android/src/config/findPackageClassName.ts#L35)) due to the lack of a declarative way to express this information.
+Similarly, there is no easy way to understand if a library is exposing a native module, a native component or not.
+The lack of this information pushed the community to create workarounds to understand that. For Example, the React Native CLI tries to circumvent it by inspecting the native code and searching for subclasses of `*ReactPackage` using complex regular expressions ([example](https://github.com/react-native-community/cli/blob/605c542d18efcb02f217d3c85726fa73a79054c2/packages/cli-platform-android/src/config/findPackageClassName.ts#L35)) due to the lack of a declarative way to express this information.
 
 Another practical example of this need is the [React Native Directory](https://reactnative.directory/) attempting to [programmatically infer](https://github.com/react-native-community/directory/pull/870) the New Architecture support from the presence of the `codegenConfig` fields in the `package.json` of a library. The `codegenConfig` field is not intended to carry semantic information about New Architecture support, and is definitely a non-exhaustive solution for this problem.
 
-While we can continue to build tooling that tries to infer metadata and capabilities of a library, providing a declarative way to describe such capabilities yields a series of benefit:
+While we can continue to build tooling that tries to infer metadata and capabilities of a library, all these approach would never be precise and could provide misleading information.
+
+We suggest to provide a declarative way to describe such capabilities.
+This approach would yield several benefits:
 * **predictability**: developers can easily understand what a library is capable of doing and if such capability matches their app.
 * **tooling**: tooling can easily consume this information and provide a better experience to developers.
 * **single source of thruth**: a single manifest will act as a source of truth for all those capabilities and flag definition, that can easily be consumed by different platforms to provide a unified way to enable/disable capabilities.
@@ -56,30 +66,32 @@ We're proposing to declare if a project is either a library or an app by adding
 }
 ```
 
+This is a mandatory field that needs to be specified in all the apps and libraries.
+
 ### New Architecture support
 
 One of the primary driver of this proposal is the [New React Native Architecture support](https://reactnative.dev/docs/the-new-architecture/landing-page). Specifically we believe that the ecosystem is currently affected by:
 * Lack of a declarative way to define if a library is compatible with the New Architecture
   * As described in the [rationale](#rationale), tooling needs to infer this information from the presence of the `codegenConfig` field in the `package.json` of a library. Libraries might decide not to use Codegen and still be compatible with the New Architecture, so this method is not exhaustive.
   * The alternative at this stage is to inspect the code and check whether the API callsites are New Architecture or Old Architecture compatible.
 * Lack of a declarative way to enable the New Architecture on both platforms
-  * Currently the New Architecture is enabled by a Gradle Property `newArchEnabled` on Android in the `gradle.properties` file and by invoking `RCT_NEW_ARCH_ENABLED=1 bundle exec pod install` on iOS.
+  * Currently the New Architecture is enabled by a Gradle Property `newArchitectureEnabled` on Android in the `gradle.properties` file and by invoking `RCT_NEW_ARCH_ENABLED=1 bundle exec pod install` on iOS.
   * As of today, there is no way to enable the New Architecture for an app project for both platforms
   * Moreover, the difference in how the New Architecture is enabled leads to a scenario where you can't statically know if an app supports New Architecture or not (as the New Architecture support is known at  `pod install` time and is not codified in the codebase)
 
-Therefore we propose to add the `newArch` section to the `reactNativeManifest.capabilities` of **both apps and libraries** with the following semantic:
-* For Apps: `newArch.enabled==true` means that the app wants to use the New Architecture.
-* For Libraries: `newArch.enabled==true` means that the library is compatible with the New Architecture.
+Therefore we propose to add the `newArchitecture` section to the `reactNativeManifest.capabilities` of **both apps and libraries** with the following semantic:
+* For Apps: `newArchitecture.enabled==true` means that the app wants to use the New Architecture.
+* For Libraries: `newArchitecture.enabled==true` means that the library is compatible with the New Architecture.
 
-Tools can be built on top of this information to check that an app with `newArch.enabled==true` is not accepting libraries with `newArch.enabled==false` and to warn against library that don't have the key specified.
+Tools can be built on top of this information to check that an app with `newArchitecture.enabled==true` is not accepting libraries with `newArchitecture.enabled==false` and to warn against library that don't have the key specified.
 
 The setup would look as follows for both apps and libraries:
 
 ```json
 {
   "reactNativeManifest": {
     "capabilities": {
-      "newArch": {
+      "newArchitecture": {
         "enabled": true
       }
     }
@@ -94,14 +106,14 @@ This section will allow also for split configuration between platforms:
   "reactNativeManifest": {
     "android": {
       "capabilities": {
-        "newArch": {
+        "newArchitecture": {
           "enabled": true
         }
       }
     },
     "ios": {
       "capabilities": {
-        "newArch": {
+        "newArchitecture": {
           "enabled": true
         }
       }
@@ -110,10 +122,35 @@ This section will allow also for split configuration between platforms:
 }
 ```
 
+If omitted, the `newArchitecture.enabled` would have a value of `false` (this may change in the future).
+
+The precedence rules are that platform-specific settings override general settings. So, for example:
+
+```json
+{
+  "reactNativeManifest": {
+    "capabilities": {
+      "newArchitecture": {
+        "enabled": true
+      }
+    },
+    "android": {
+      "capabilities": {
+        "newArchitecture": {
+          "enabled": false
+        }
+      }
+    },
+  }
+}
+```
+
+would means that, in general, the app/library support the New Architecture, but not for Android.
+
 #### `codegenConfig` support
 
 Similarly to the New Architecture support metadata, the `codegenConfig` is a key metadata of the New Architecture build pipeline.
-Currently the `codegenConfig` is a **top-level** key in the `package.json` of a project. 
+Currently the `codegenConfig` is a **top-level** key in the `package.json` of a project.
 
 We propose to move this key under the `reactNativeManifest.capabilites` section as follows:
 ```json
@@ -174,9 +211,34 @@ which will also allow for split configuration between platforms as follows:
 }
 ```
 
+If omitted, the `hermes.enabled` would have a value of `true`.
+
+The precedence rules are that platform-specific settings override general settings. So, for example:
+
+```json
+{
+  "reactNativeManifest": {
+    "capabilities": {
+      "hermes": {
+        "enabled": true
+      }
+    },
+    "android": {
+      "capabilities": {
+        "hermes": {
+          "enabled": false
+        }
+      }
+    },
+  }
+}
+```
+
+would means that the app will run with Hermes for all the platforms it supports but not for Android.
+
 ### React Native Release feature flagging
 
-We currently have a numer of different files where capabilities of React Native can be toggled to enable/disable features in the runtime.
+We currently have a number of different files where capabilities of React Native can be toggled to enable/disable features in the runtime.
 For example we have:
 * [android/gradle.properties](https://github.com/facebook/react-native/blob/main/packages/react-native/template/android/gradle.properties) to specify key-value build time properties for Android
 * [android/app/build.gradle](https://github.com/facebook/react-native/blob/main/packages/react-native/template/android/app/build.gradle) to specify build time configuration for Android
@@ -200,7 +262,7 @@ For the time being, we're not planning to add a `version` section to the `reactN
 
 ### TurboModule/Fabric toggles
 
-At the time of writing, we prefer not to offer a dedicated section to toggle Fabric/TurboModule capability inside `reactNativeManifest`. The rationale is that we believe that the `newArch` section is sufficient to expose the New Architecture to users.
+At the time of writing, we prefer not to offer a dedicated section to toggle Fabric/TurboModule capability inside `reactNativeManifest`. The rationale is that we believe that the `newArchitecture` section is sufficient to expose the New Architecture to users.
 Selectively toggling Fabric/TurboModule is a more advanced feature. We believe we'll still be offering a more advanced way to enable or disable those pieces of the New Architecture infrastructure, but at the current state, our preference is not to expose such capability in the top level `reactNativeManifest` section.
 
 ## Proposed Tooling
@@ -215,7 +277,6 @@ Build tools such as Gradle/CocoaPods or others should account for the `reactNati
    1. If the user is **also** specifying the capability `foo` in the build tool specific configuration (e.g. inside `gradle.properties` for Android) behave as follows:
       1. If the two values are **compatible**, use them without notifying the user.
       1. If the two values are **incompatible**, notify the user and use the value specified in the `reactNativeManifest.capabilities.foo` section will prevail and the value specified in the build tool specific configuration will be ignored.
-   1. If the user is **not** specifying the capability `foo` in the build tool specific configuration, honor the value specified in the `reactNativeManifest.capabilities.foo` section.
 1. If the capability `foo` is **not** specificed in the `reactNativeManifest.capabilities` section, honor the value specified in the build tool specific configuration or the default value if not specified.
 
 ### `align-deps` support
@@ -254,7 +315,7 @@ Specifically, we envision to evolve `reactNativeManifest` or `reactNativeManifes
 Here we present a full example of how a `reactNativeManifest` section could look like for a library and an app.
 
 For an app the section will look as follows:
-    
+
 ```json
 {
   "name": "my-awesome-app",
@@ -266,7 +327,7 @@ For an app the section will look as follows:
       "hermes": {
         "enabled": true
       },
-      "newArch": {
+      "newArchitecture": {
         "enabled": true
       },
       "codegenConfig": {
@@ -292,10 +353,7 @@ For a library the section will look as follows:
     "schema": "1.0.0",
     "type": "library",
     "capabilities": {
-      "hermes": {
-        "enabled": true
-      },
-      "newArch": {
+      "newArchitecture": {
         "enabled": true
       },
       "codegenConfig": {
@@ -324,7 +382,7 @@ The JSON Schema will be published as soon as we find an agreement on the key nam
 If we decide to adopt this proposal, we'll have to broadcast this change to the ecosystem.
 Ideally, we'll start by adding the `reactNativeManifest` section to the app template and to `create-react-native-library`.
 
-We foresee a phase in which only a part of the userbase has this section configured, and tool and developers need to account for the absence of this section.
+We foresee a phase in which only a part of the user base has this section configured, and tool and developers need to account for the absence of this section.
 
 Once the v1.0.0 version of the shape is finalised, we can start integrating it across the board in various tools mentioned in [Proposed Tooling](#proposed-tooling) section. This first wave of support would have to be aligned around a given React Native release, say in 0.73 (which branch has not been cut).
 
