Autolinking

Learn how to use Expo Autolinking to automatically link native dependencies in your Expo project.

Usually, when you're developing a native mobile app and want to install a third-party library, you're asked to add the dependency to the manifest files of your package managers (build.gradle on Android, Podfile for CocoaPods on iOS, Package.swift for SwiftPM on iOS). In Expo and React Native, you already do that with your package.json file by installing the package from the npm registry. Since most of the React Native libraries come with some native (platform-specific) code, installing a library will require configuring even up to three different package managers!

Expo Autolinking is a mechanism that automates this process and reduces the library installation process to the minimum — usually just installing the package from npm and re-running pod install. The core implementation can be found in the expo-modules-autolinking package and is divided into three parts:

1. a CLI command with the module resolution algorithms
2. code that integrates with the Gradle build system for Android
3. code that integrates with CocoaPods for iOS

Since SDK 52, Expo Autolinking not only links Expo modules, but also React Native modules. To use the React Native community CLI autolinking instead, see opting out of Expo Autolinking for React Native modules section.

Linking behavior

Expo Autolinking is integrated into the Gradle build system for Android and CocoaPods for iOS. When building your app, the Expo Autolinking CLI is called and searches for Expo and React Native modules to autolink.

This module resolution searches for candidate dependencies to autolink in four separate steps:

1. For React Native modules only, it considers any dependencies in your project root's react-native.config.js that contain an explicit root path. This file is optional and doesn't exist in most Expo projects.
2. It searches all directories specified in your autolinking configuration's searchPaths option.
3. It searches local modules in the directory specified in your autolinking configuration's nativeModulesDir option, which defaults to ./modules/.
4. It resolves the dependencies of your app and any dependency or peer dependency recursively. This matches the Node.js resolution algorithm.

The autolinked modules are automatically added to the build, which usually means that your app's dependencies that contain native (platform-specific) code are set up automatically.

Configuration

The behavior of the module resolution can be customized using some configuration options. These options can be defined in three different places, from the lowest to the highest precedence:

• expo.autolinking config object in application's package.json
• per platform overrides with expo.autolinking.ios and expo.autolinking.android objects
• options provided to the CLI command, the use_expo_modules! method in the Podfile or useExpoModules function in the settings.gradle

{
  "expo": {
    "autolinking": {
      "searchPaths": ["../../packages"]
    }
  }
}

{
  "expo": {
    "autolinking": {
      "nativeModulesDir": "./modules"
    }
  }
}

{
  "expo": {
    "autolinking": {
      "android": {
        "exclude": ["expo-random", "third-party-expo-module"]
      }
    }
  }
}

module.exports = {
  dependencies: {
    'library-name': {
      platforms: {
        android: null,
      },
    },
  },
};

use_expo_modules!({
  flags: {
    :inhibit_warnings => false
  }
})

{
  "expo": {
    "autolinking": {
      "ios": {
        "flags": {
          "inhibit_warnings": true
        }
      }
    }
  }
}

CLI commands

{
  "expo-random": {
    "path": "/absolute/path/to/node_modules/expo-random",
    "version": "13.0.0",
    "config": {
      // Contents of `expo-module.config.json`
    },
    "duplicates": [
      // List of conflicting duplicates for this module (with lower precedence)
    ]
  }
  // more modules...
}

{
  "modules": [
    {
      "packageName": "expo-random",
      "packageVersion": "13.0.0",
      "pods": [
        {
          "podName": "ExpoRandom",
          "podspecDir": "/absolute/path/to/node_modules/expo-random/ios"
        }
      ],
      "swiftModuleNames": ["ExpoRandom"],
      "modules": ["RandomModule"],
      "appDelegateSubscribers": [],
      "reactDelegateHandlers": [],
      "debugOnly": false
    }
    // more modules...
  ]
}

{
  "root": "/absolute/path/to",
  "reactNativePath": "/absolute/path/to/node_modules/react-native",
  "dependencies": {
    "@react-native-async-storage/async-storage": {
      "root": "/absolute/path/to/node_modules/@react-native-async-storage/async-storage",
      "name": "@react-native-async-storage/async-storage",
      "platforms": {
        "ios": {
          "podspecPath": "/absolute/path/to/node_modules/@react-native-async-storage/async-storage/RNCAsyncStorage.podspec",
          "version": "",
          "configurations": [],
          "scriptPhases": []
        }
      }
    }
    // more modules...
  }
}

Dependency resolution and conflicts

This is an experimental feature starting in SDK 54 and above.

Autolinking and Node resolution have different goals and the module resolution algorithm in Node and Metro can sometimes come into conflict. If your app contains duplicate installations of a native module that is picked up by autolinking, your JavaScript bundle may contain both versions of the native module, while autolinking and your native app will only contain one version. This might cause runtime crashes and risks incompatibilities.

This is an especially common problem with isolated dependencies or monorepos, and you should check for and deduplicate native modules in your dependencies.

From SDK 54, you can set the EXPO_USE_STICKY_RESOLVER=1 environment variable to apply autolinking to Expo CLI and Metro bundler automatically. This will force dependencies that Metro resolves to match the native modules that autolinking resolves.

Common questions

How to set up the autolinking in my app?

All projects created with the npx create-expo-app command are already configured to use Expo Autolinking. If your project was created using a different tool, see Installing Expo modules to make sure your project includes all necessary changes.

What do I need to have in my module to make it autolinkable?

The module resolution algorithm searches only for packages that contain the Expo module config file (expo-module.config.json) at the root directory, next to the package.json file. It's also necessary to include supported platforms in the platforms array — if the platform for which the autolinking algorithm is run is not present in this array, it's just skipped in the search results.

How is it different from React Native community CLI autolinking?

• Expo Autolinking comes with built-in support for monorepos, package manager workspaces, transitive dependencies, and isolated dependencies installations.
• It's also significantly faster, although the module resolution algorithm is more complex to be more reliable and match Node.js's module resolution.
• Expo module resolution is also capable of detecting duplicate dependencies, which is a common issue in monorepos.
• Last but not least, it integrates well with the features offered by Expo Modules APIs and supports React Native modules.

Opting out of Expo Autolinking for React Native modules

Starting from SDK 52, Expo Autolinking replaces the React Native community CLI autolinking by default. If you would like to use the React Native community CLI's autolinking instead, set the environment variable EXPO_USE_COMMUNITY_AUTOLINKING=1 and add @react-native-community/cli as a dev dependency to your project.

With this environment variable set, Expo Autolinking will not be used to resolve React Native modules, but will continue to autolink Expo modules.