React Native: Creating an iOS Native Module

WHY IT EXISTS React Native provides a powerful abstraction over native platforms, but it can't cover every single platform-specific API or use case. Native modules are the official escape hatch, created to solve the problem of needing to access functionality that only exists in the native SDK, or to run code that needs higher performance than JavaScript can offer.

THE MENTAL MODEL Think of a native module as a custom API bridge. Your JavaScript code lives on one side, and the native iOS platform (Objective-C or Swift) lives on the other. When you call a native module method from JS, you're sending a message across this bridge. The native code executes, performs the task, and can then send a result back to your JavaScript.

HOW IT WORKS The process involves creating a native class and explicitly telling React Native which parts to expose. First, you create an Objective-C class that implements the RCTBridgeModule protocol. Second, you add the RCT_EXPORT_MODULE() macro in your implementation file; this registers the class with React Native and makes it available to JS. Third, and most critically, you use the RCT_EXPORT_METHOD() macro for every single function you want to expose. Without this, the method remains private to the native side. Finally, in your JS, you import NativeModules from react-native and call your module's methods, like NativeModules.YourModuleName.yourExportedMethod().

WHEN TO USE IT Use a native module in three main scenarios. First, to access a platform API that React Native doesn't expose, like a specific iOS calendar or security feature. Second, to reuse existing, battle-tested Objective-C, Swift, or C++ code without rewriting it in JavaScript. Third, for high-performance, multi-threaded tasks like image processing, database operations, or heavy computations that would be too slow in JS.

WHEN NOT TO USE IT Don't build a native module if a well-maintained community package already exists. Creating and maintaining your own native code adds complexity to your project, requires native development skills, and can make future React Native upgrades more challenging. It's a tool of necessity, not a first choice.

ONE CANONICAL EXAMPLE A common example is a CalendarManager module. You would create a CalendarManager.m file in Objective-C that exports a method like addEvent:(NSString *)name location:(NSString *)location. After using the RCT_EXPORT_MODULE() and RCT_EXPORT_METHOD() macros, you could then call NativeModules.CalendarManager.addEvent('Birthday Party', '4 Privet Drive'); directly from your JavaScript code to run the native function.