xref: /expo/docs/pages/modules/autolinking.mdx (revision a16ac082) 
1---
2title: Autolinking
3description: Learn how to use Expo Autolinking to automatically link native dependencies in your Expo project.
4---
5
6import { Terminal } from '~/ui/components/Snippet';
7import { APIBox } from '~/components/plugins/APIBox';
8import { CodeBlocksTable } from '~/components/plugins/CodeBlocksTable';
9
10Usually, 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).
11In Expo and React Native, you already do that with your **package.json** file by installing the package from the [npm](https://www.npmjs.com) registry. Since most of the React Native libraries come with some native (platform-specific) code,
12installing a library will require configuring even up to three different package managers!
13
14Expo 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`.
15The core implementation can be found in the [`expo-modules-autolinking`](https://github.com/expo/expo/tree/main/packages/expo-modules-autolinking) package and is divided into three parts:
16
171. common JavaScript CLI tool with the module resolution algorithm
182. code that integrates with the Gradle build system for Android platform
193. Ruby script that integrates with CocoaPods for iOS platform
20
21## CLI commands
22
23<APIBox>
24
25### `search`
26
27Searching is the first phase of resolving the Expo modules installed in a project. Its implementation is shared between all platforms. It finds all modules marked as Expo modules and determines which version is of the highest precedence (in case of duplicates).
28
29<Terminal cmd={['$ npx expo-modules-autolinking search']} />
30
31The above command returns an object in JSON format with modules that have been found as dependencies:
32
33```json
34{
35  "expo-random": {
36    "path": "/absolute/path/to/node_modules/expo-random",
37    "version": "13.0.0",
38    "config": {
39      // Contents of `expo-module.config.json`
40      "platforms": ["ios", "android"],
41      "ios": { "modules": ["RandomModule"] },
42      "android": { "modules": ["expo.modules.random.RandomModule"] }
43    },
44    "duplicates": [] // An array of other revisions (with lower precedence) of the same module
45  }
46  // more modules...
47}
48```
49
50</APIBox>
51<APIBox>
52
53### `resolve`
54
55Resolving is the second phase based on the results from the `search` command. It resolves each search result to an object with more (platform-specific) details, such as the path to the podspec or **build.gradle** files and module classes to link.
56
57<Terminal cmd={['$ npx expo-modules-autolinking resolve --platform <ios|android>']} />
58
59For example, with the `--platform ios` option it returns an object in JSON format with an array of modules and resolved details for the iOS platform:
60
61```json
62{
63  "modules": [
64    {
65      "packageName": "expo-random",
66      "packageVersion": "13.0.0",
67      "pods": [
68        {
69          "podName": "ExpoRandom",
70          "podspecDir": "/absolute/path/to/node_modules/expo-random/ios"
71        }
72      ],
73      "swiftModuleNames": ["ExpoRandom"],
74      "modules": ["RandomModule"],
75      "appDelegateSubscribers": [],
76      "reactDelegateHandlers": [],
77      "debugOnly": false
78    }
79    // more modules...
80  ]
81}
82```
83
84</APIBox>
85<APIBox>
86
87### `verify`
88
89Verifies the search results by checking whether there are no duplicate packages, otherwise an appropriate warning is shown.
90
91<Terminal cmd={['$ npx expo-modules-autolinking verify']} />
92
93</APIBox>
94
95## Configuration
96
97The 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:
98
99- `expo.autolinking` config object in application's **package.json**
100- per platform overrides with `expo.autolinking.ios` and `expo.autolinking.android` objects
101- options provided to the CLI command, the `use_expo_modules!` method in the **Podfile** or `useExpoModules` function in the **settings.gradle**
102
103<APIBox>
104
105### `searchPaths`
106
107A list of paths relative to the app's root directory where the autolinking script should search for Expo modules.
108It defaults to a list of all **node_modules** folders found when traversing up through a monorepo, starting from the app's root directory.
109Useful when your project has a custom structure or you want to link local packages from folders different than **node_modules**.
110
111```json package.json
112{
113  "expo": {
114    "autolinking": {
115      "searchPaths": ["../../packages"]
116    }
117  }
118}
119```
120
121When used with the CLI, you can pass the search paths as command arguments like this:
122
123<Terminal cmd={['$ npx expo-modules-autolinking search ../../packages']} />
124
125</APIBox>
126<APIBox>
127
128### `exclude`
129
130A list of package names to exclude from autolinking. These packages will not be autolinked even if they are found in the search paths.
131For example, you may want not to link some packages that you don't use on the specific platform to reduce the binary size.
132The following config in **package.json** will exclude `expo-random` from autolinking on Android:
133
134```json package.json
135{
136  "expo": {
137    "autolinking": {
138      "android": {
139        "exclude": ["expo-random"]
140      }
141    }
142  }
143}
144```
145
146</APIBox>
147<APIBox platforms={['ios']}>
148
149### `flags`
150
151CocoaPods flags to pass to each autolinked pod. `inhibit_warnings` is likely the only flag most developers want to use, to inhibit Xcode warnings produced when compiling the autolinked modules.
152You can refer to the [CocoaPods Podfile documentation](https://guides.cocoapods.org/syntax/podfile.html#pod) for available flags.
153
154<CodeBlocksTable tabs={['Podfile', 'package.json']}>
155
156```ruby
157use_expo_modules!({
158  flags: {
159    :inhibit_warnings => false
160  }
161})
162```
163
164```json
165{
166  "expo": {
167    "autolinking": {
168      "ios": {
169        "flags": {
170          "inhibit_warnings": true
171        }
172      }
173    }
174  }
175}
176```
177
178</CodeBlocksTable>
179
180</APIBox>
181
182## Common questions
183
184### How to set up the autolinking in my app?
185
186All projects created with the `npx create-expo-app` command are already configured to use Expo Autolinking. If your project was created using different tools, please refer to [Installing Expo modules](/bare/installing-expo-modules) to make sure your project includes all necessary changes.
187
188### What do I need to have in my module to make it autolinkable?
189
190The module resolution algorithm searches only for packages that contain the [Expo module config](./module-config.mdx) file (**expo-module.config.json**) at the root directory, next to the **package.json** file.
191It'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.
192
193### How is it different from React Native autolinking?
194
195- Expo Autolinking comes in with built-in support for monorepos, Yarn workspaces and transitive dependencies.
196- It's also significantly faster, even though the module resolution algorithm is more complex to be more reliable and match the Node's module resolution.
197- Expo module resolution is also capable of detecting the duplicates which is a common issue in monorepos.
198- Last but not least, it integrates well with all the features offered by Expo Modules APIs.
199