☂️ Umbrella: Autolinking

[grabbou]

Opening this issue as an umbrella to discuss implementation details that are common to all platforms and track progress.

For rationale, please read this issue: react-native-community/discussions-and-proposals#96

Check this tweet with video for a demo.

PRs:

• Standardise configuration mechanism #254
• feat: make legacy link use new configuration #281
• feat: autolinking for Android with Gradle #258
• feat: autolinking for iOS with CocoaPods #256

The work can be split into 3 parts, one that touches CLI itself (JavaScript), one for CocoaPods-related changes (iOS) and one for Gradle changes (Android).

You can check the approach and rationale behind each of these approaches below.

JavaScript

Make a React Native package act like a normal JS dependency, but with some added conventions for configuring the native toolchains and the native source files.

Both platforms run react-native config to grab all of the RN packages, i.e. CocoaPods or the Gradle plugins never dives into node_modules itself.

This ensures consistent settings for iOS and Android and allows react-native config to update the implementation of how to source this information (be it specified filenames, entries in the module’s package.json, etc).

iOS

The Podfile used in your project includes an extra function use_native_modules! which gets the a list of native dependencies from the command react-native config and:

• Adds dependencies via CocoaPods development pods (using the files from node_modules)
• Adds build phase scripts to the App project’s build phase (see examples below)

This means that all libraries need to ship a Podspec in the root of their folder to work seamlessly. This references the native code that your library depends on, and notes any of its other native dependencies.

The implementation ensures that a library is imported only once, so if you need to have a custom pod directive then including it above the function use_native_modules!.

Script Phases

A project which wants to add an Xcode script phase to a user's app can use the custom support in iOS auto-linking via custom settings in either the project's package.json under "react-native" or via a react-native.config.js file in the root.

The options for the build phase are passed more-or-less directly to the Podfile via build_phase. Here's an example of adding the settings in your package.json:

{
  "react-native": {
     "ios": {
        "scriptPhases": {
            "name": "My Dep pre-parser",
           "path": "relative/path/to/script.sh",
           "execution_position": "after_compile"
         }
      }
  }
}

"path" is an extra provided to simplify storing the scripts in your repo, it sets "script" for you. You can see all available options here.

Android

• At build time, before the build script is run, a first gradle plugin (settings.gradle) is ran that takes the package metadata from react-native config to dynamically include android library projects into the build.
• A second plugin then adds those dependencies to the app project and generates a manifest of React Native packages to include in the fully generated file /android/build/generated/rn/src/main/java/com/facebook/react/PackageList.java.
• Finally, at runtime (on startup) the list of React Native packages, generated in step 2, is used to instruct the React Native runtime of what native modules are available.

[grabbou]

CC: @orta @alloy @Salakar @bartolkaruza - you would be the best to fill in iOS / Android parts with technical explanation behind each of the approaches. Don't want to take this pleasure out from you.

[orta]

Updated the JS / iOS side from https://docs.google.com/document/d/1WzMYo3Nv0jkrP30_BGLX7gNFaaiLEsdWxX-znMM0yBE/edit#heading=h.78ighmioc9n1

[jbrodriguez]

Please consider making this a must for 0.60

As mentioned in react-native-community/discussions-and-proposals#64 (comment), Cocoapods right now is painful on version upgrades.

[Salakar]

My PR has been updated to the latest changes now, #258

[thymikee]

And it's merged! Now testing and documentation time :)