Rethinking Gradle Integration for React Native

[fkgozali]

With the new React Native architecture getting ready for wider rollout, it is a good opportunity to revisit how Android apps are including React Native in Gradle today. Right now, apps include the react.gradle that react-native package provides. While this works, a more structured approach like using Gradle plugin can be more maintainable and easier to reason about.

This discussion outlines the proposed structure and potential requirements around it. The goal is to promote discussion around this topic and to find the path forward.

A Gradle Plugin Structure

Each application and library that needs to depend on React Native and/or react-native-codegen specifies a react extension on the build.gradle:

plugins {
  id("com.facebook.react"),
  // ...
}

// Using extension
react {
  enableCodegen = true
  `jsRootDir ``=`` ``file("$rootDir/packages/rn-tester")
  // All other configurations that used to be in project.ext.react
  // ...
}`

Ideal Requirements

• The plugin should support local builds without publishing to Gradle plugin central or local Maven
  • This means the plugin itself should be included in the npm package, and should be built directly from source
  • Long term, we may evaluate publishing this plugin to Gradle plugin central for ease of use
• The plugin can be applied to both application level and library level
  • An application is like the RNTester app, whereas a library is like ReactAndroid itself, or any other 3rd party android library
• The plugin should support base configuration for React Native, and also allow customizing codegen output
  • This means the plugin should allow JavaScript files as inputs
• The plugin should enable flavors or some other mechanism for applications to cleanly select between different JavaScript engines
  • The main use case is to select Hermes vs JSC
  • One tricky aspect of this is supporting native modules which depend on JSI in an engine-independent way.
• The plugin defines a set of dependencies or tasks given the available inputs on the application or library
• Application can then execute the automatically defined tasks as needed

Sample Implementation

A concrete sample implementation for this approach is the react-native-codegen Gradle plugin, as used by packages/android/app/rn-tester and ReactAndroid/build.gradle. Currently, the codegen Gradle plugin automatically defines 2 tasks when the react extension is defined:

• generateCodegenSchemaFromJavaScript
  • Given the JavaScript files/directory, generate theJSON schema using react-native-codegen type parser
• generateCodegenArtifactsFromSchema
  • Given the schema from the previous task, generate Android specific codegen output
  • This includes .java and C++ JNI files

In addition, the plugin automatically adds the code from the 2nd task above into the compilation source, which means:

• The codegen output is automatically generated during build time
• The output is not checked in to the repo, reducing the need to manually update them when JavaScript changes

Further Use Cases

With the proper plugin infra, we hope to cover the following build-time use cases to improve developer experience:

Automatic discovery of libraries/dependencies that use the same plugin

Ideally, the main application should be able to evaluate all of the libraries it depends on that have React Native specific treatments, i.e. those that use the same plugin. This is very useful to automatically build a TurboModule and Fabric lookup function based on all available NativeModules/NativeComponents in the app. Here’s an example.

The main goal is to reduce the need of manually written “list of things”, though not required. Imagine generating the example code automatically instead of manually registering a new module in a giant list.

Though, isn’t this what autolinking already does? In a way, yes. However, instead of crawling the dependencies outside of Gradle (autolinking uses react-native config to analyze deps, but not all apps may be using it), the plugin infra should allow automatic dependency collection to generated the combined artifacts (e.g. the lookup functions mentioned above). Note that this proposal is not a replacement for autolinking, rather, a supplement.

Annotation of such libraries/dependencies

To take this further, the plugin infra should support the general React Native “plugins” for native library proposal, by allowing “annotations” or “labels” on the libraries that configures the react extension. For example, a library can annotate itself to declare:

• which NativeModules/Components are provided
  • this list may also be auto-generated based on codegen schema
• whether it uses codegen or not
• any other annotations

With such annotations, the infra should allow crawling dependencies that use the plugin, and have specific annotations. This way, the app can evaluate automatically the list of all NativeModules in the app without hand-written code.

An analogy for this in Buck world is the use of buck query to search for Buck targets that specifies specific labels. For example:

buck query "attrregexfilter(labels, 'native_module:.*' deps(//myapp:))"

This query:

• Evaluates all the transitive dependencies of “myapp”
• For each dependency, filter those that specify a native_module: in the labels attribute
  • A hypothetical example: perhaps a library labels itself with: native_module:Appearance, to denote that it provides the Appearance native module.

Note that the query is not only limited to string labels, but also a more structured annotation, like name value pairs. See the examples from #125.

If we can bring over this support to Gradle, it will unlock many more sophisticated build processing.

cc @ramanpreet, @hramos, @mhorowitz

[kelset]

cc @dulmandakh I'm sure you'll be interested in this.