Skip to content
useffect.sh
Book 30 min with a senior
Native

Autolinking

The mechanism that discovers native libraries in node_modules and adds them to the Podfile and Gradle with no manual edits.

Definition

Autolinking is the mechanism through which a React Native project discovers the native code of libraries installed in node_modules and wires it into the iOS and Android builds automatically. Before it, adding a native dependency meant editing the Podfile, settings.gradle, MainApplication, and sometimes the Xcode project by hand, with react-native link commands that left residue behind. Today, the react_native_pods.rb script required by the Podfile (use_native_modules!) reads the output of react-native config and adds each library as a local pod; on Android, autolinkLibrariesWithApp in settings.gradle and app/build.gradle generates the list of packages to register. Expo modules have their own autolinking, driven by expo-module.config.json, which coexists with the CLI’s. A native module missing at runtime while its package is installed is almost always an autolinking problem, especially in a monorepo where the dependency was hoisted to the root.

In a real app

In a project, autolinking shows up in the Podfile (config = use_native_modules!), in android/settings.gradle (the React Native Gradle Plugin), and in android/app/build.gradle (autolinkLibrariesWithApp()). Every library must ship a .podspec at its root and, on Android, a build.gradle; a library missing either is silently skipped. To exclude a library on one platform or point at a local path, react-native.config.js accepts a dependencies entry with platforms.ios: null or root.

The case that burns hours is the monorepo. Autolinking searches the app’s node_modules; a dependency hoisted to the workspace root or installed in isolated mode (pnpm) can escape it. Expo added experiments.autolinkingModuleResolution to app.json in SDK 54, enabled automatically for apps in a monorepo from SDK 55. When a native module “does not exist” at runtime even though the package is installed, I start with npx expo-modules-autolinking search or npx react-native config to see what the build actually sees.

With the experimental Swift Package Manager support (React Native 0.87 and 0.88), iOS autolinking takes a second form: npx react-native spm generates the package references, and a library then has to ship a Package.swift (or generate one with npx react-native spm scaffold), with its SwiftPM settings under swiftpmConfig in its package.json.

Related terms

Sources

All 35 glossary terms

One of these is blocking your app?

30 minutes with a senior to look at the problem in your code. Free.

Book 30 minBack to home