Linking Native Dependencies in React Native

WHY IT EXISTS React Native provides core components, but real-world apps often need functionality not included, like web views or advanced maps. These features require access to native platform APIs, which pure JavaScript libraries cannot provide. Linking bridges this gap, connecting third-party native code to your React Native project.

THE MENTAL MODEL Think of it like adding a specialized hardware component to your computer. You don't just place the component inside the case; you also have to connect it to the motherboard and install its drivers. In React Native, npm install is like placing the component in the case. Linking (pod install for iOS, Gradle sync for Android) is connecting it to the motherboard, and rebuilding the app is like installing the drivers so the OS can use it.

HOW IT WORKS When you install a library with native code, the JavaScript part is added to your node_modules folder. For iOS, React Native uses CocoaPods as the dependency manager. Running npx pod-install updates your ios/Podfile.lock and integrates the new library's native code into your Xcode workspace. For Android, the Gradle build system automatically detects and links the new dependency when you rebuild the app. In both cases, a full application rebuild (npm run ios or npm run android) is required to compile the new native code into the final app binary.

WHEN TO USE IT You must link dependencies whenever you install a React Native library that is not 100% JavaScript. This is common for packages that interact with device hardware (camera, GPS), use platform-specific UI elements (like a web view), or perform heavy computations that are faster in native code. The library's documentation will almost always specify if native linking is required.

WHEN NOT TO USE IT This process is unnecessary for pure JavaScript libraries. Packages like lodash or state management libraries like zustand work in any JavaScript environment and don't have native components. Installing them with npm or yarn is sufficient. Trying to link a pure JS library will have no effect, and you only need to restart your bundler, not rebuild the entire app.

ONE CANONICAL EXAMPLE To add a web view to your app, you install react-native-webview by running npm install react-native-webview. This is not enough. To link it on iOS, you must run npx pod-install from your project root. Then, you rebuild the app with npm run ios. For Android, you simply need to rebuild after the install: npm run android. Only after these steps can you import and use the <WebView /> component in your code.