Native Modules: Bridge JS to Native Platform APIs

WHY IT EXISTS React Native provides many components, but it can't cover every platform-specific API for Android and iOS. When your app needs to interact with a native feature that isn't available in React Native or an existing library, you need a way to write that integration code yourself. Native Modules solve this by providing a mechanism to bridge your JavaScript application with the underlying native platform.

THE MENTAL MODEL Think of a Native Module as a contract and a translator. You first write a contract in a language both sides understand: a typed JavaScript specification. This contract defines the functions you want to expose, like setItem or getItem. Then, you write the native code (the translator) on Android and iOS that fulfills this contract, using platform-specific APIs. The React Native runtime ensures your JavaScript calls are correctly routed to the right native implementation.

HOW IT WORKS The modern process uses "Turbo Native Modules" and Codegen. First, you define a typed specification in a TypeScript or Flow file, outlining the methods and their signatures. Second, you configure Codegen in your package.json file, pointing it to your spec file. When you build the app, Codegen automatically generates the necessary interface boilerplate in the native languages (Java for Android, Objective-C for iOS). Finally, you write the actual native code that implements these generated interfaces, and then you can call your module from your JavaScript code.

WHEN TO USE IT Use a Native Module when you need to access a platform API that has no React Native equivalent or existing third-party library. This is common for features deeply integrated with the OS, such as custom hardware interactions, using specific OS-level data stores, or integrating a native SDK that doesn't have a React Native wrapper.

WHEN NOT TO USE IT Avoid writing a Native Module if a well-maintained third-party library already exists. Building and maintaining native code adds complexity and requires platform-specific knowledge. Always check for existing solutions before building your own. If the functionality can be achieved purely in JavaScript, stick with that to maintain cross-platform simplicity.

ONE CANONICAL EXAMPLE A common use case is creating a persistent key-value storage module. To build a NativeLocalStorage module that mirrors the web's localStorage API, you define a spec in JavaScript with setItem, getItem, and removeItem. Codegen creates the interfaces. Then, you implement the module on Android using SharedPreferences and on iOS using NSUserDefaults to provide a unified, persistent storage API for your React Native app.