Developing a Native Module for React Native (iOS)
We solve the problem that no ready-made package can cover: Bluetooth Low Energy via CoreBluetooth, protected Keychain via SecItemCopyMatching, integration of a native bank or payment system SDK. As long as the app works only with JS libraries, everything is predictable. But when a non-standard need arises, you have to write a Native Module manually. And that's where real engineering work begins, where our 10-year experience in mobile development guarantees stability and performance. Contact us for a consultation — we'll discuss your project.
Data Types Through the Bridge
The React Native bridge accepts only types serializable in JSON: NSString, NSNumber, NSArray, NSDictionary, NSNull. Binary data (Data) encode in Base64, custom objects parse into a dictionary on the native side. This is especially critical when working with CoreBluetooth, where you need to pass CBCharacteristic with all its properties. Incorrect serialization leads to runtime errors that are difficult to debug.
Problems Solved by Native Module
Bluetooth Low Energy. Standard packages (react-native-ble-plx) do not always support custom protocols or specific characteristics. Our module wraps CoreBluetooth with full control over CBPeripheral, CBCentralManager, and data flow management.
Keychain and security. Storing tokens, encryption keys, biometric data requires direct access to SecItemCopyMatching. Implementation errors lead to leaks or crashes — we use a proven pattern with thread safety and correct error handling.
SDK integration. Many banks and payment systems provide only native libraries (CocoaPods with Objective-C/Swift). Wrapping them in a Native Module is the only way to use them in React Native.
Bridge Architecture
Before the New Architecture appeared, the bridge worked through an asynchronous message queue: the JS thread serialized the call to JSON, sent it over the bridge, the native thread deserialized and executed it. A 5–10 ms delay was acceptable for most tasks, but with high-frequency calls (e.g., UI updates based on sensor data), it became noticeable.
With the advent of the New Architecture — JSI (JavaScript Interface) + Turbo Modules — it became possible to call native code synchronously through a C++ host object, bypassing the message queue. This fundamentally changes the approach: instead of RCTBridgeModule, you need to implement the TurboModule protocol via code generation based on a TypeScript specification.
In practice, 80% of projects still use the old architecture because updating breaks dependencies. Therefore, we support both approaches and help with gradual migration. More details about Turbo Modules can be found in the official repository.
| Aspect | Old Bridge (RCTBridgeModule) | New Turbo Module (JSI) |
|---|---|---|
| Call mechanism | Asynchronous message queue | Synchronous call via C++ |
| Serialization | JSON (NSString, NSNumber, …) | Direct type passing (no JSON) |
| Delay | 5–10 ms | <1 ms |
| Compatibility | Any RN version | RN with Codegen support |
| Performance | Medium | High (3–5 times faster) |
Old Architecture: RCTBridgeModule
A typical structure is a Swift class inheriting from NSObject with @objc attributes. Registration via RCT_EXTERN_MODULE in an Objective-C bridging file is mandatory — without it, the module will not appear in the registry.
Implementation Example
@objc(BiometricModule)
class BiometricModule: NSObject, RCTBridgeModule {
static func moduleName() -> String { "BiometricModule" }
@objc func authenticate(_ reason: String,
resolver: @escaping RCTPromiseResolveBlock,
rejecter: @escaping RCTPromiseRejectBlock) {
let context = LAContext()
var error: NSError?
guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) else {
rejecter("BIOMETRIC_UNAVAILABLE", error?.localizedDescription, error)
return
}
context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics,
localizedReason: reason) { success, authError in
if success { resolver(true) }
else { rejecter("AUTH_FAILED", authError?.localizedDescription, authError) }
}
}
}
The most common mistake at this stage: the developer writes a Swift class, forgets to add @objc(BiometricModule) or incorrectly names the method in RCT_EXTERN_METHOD, and on the JS side gets undefined is not a function. It's hard to debug because the error appears at runtime without a stack trace. Our certified engineer with experience across 100+ projects eliminates such errors at the code review stage.
How to Ensure Thread Safety?
React Native calls module methods on an arbitrary thread from its pool. If inside the method you access UIKit, you get a crash with UIKit called from background thread. The classic solution is DispatchQueue.main.async { } around the UI code. But this creates a new problem: resolve/reject are called asynchronously, and if the user closes the screen, the completion handler accesses an already deallocated object.
The pattern with [weak self] and guard is mandatory:
DispatchQueue.main.async { [weak self] in
guard self != nil else { return }
resolver(result)
}
Data serialization. The bridge only accepts types that can be serialized to JSON: NSString, NSNumber, NSArray, NSDictionary, NSNull. Want to pass Data? Encode it in Base64. Want to pass a custom object? Parse it into a dictionary on the native side. This is especially painful when working with CoreBluetooth, where you need to provide a CBCharacteristic with all its properties.
Callbacks vs Promises vs Events. For one-time results, use a Promise. For a stream of events (sensor data, connection status), use RCTEventEmitter. Mixing approaches in one module is an error that leads to memory leaks: if RCTResponseSenderBlock is stored as a property and called twice, the app crashes with Tried to call a callback that is no longer valid.
New Architecture: Turbo Modules + Codegen
Starting from the version of React Native that supports the New Architecture, Codegen generates a C++ abstraction from a TypeScript specification. The spec file looks like this:
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';
export interface Spec extends TurboModule {
authenticate(reason: string): Promise<boolean>;
}
export default TurboModuleRegistry.getEnforcing<Spec>('BiometricModule');
On the native side, we implement the NativeBiometricModuleSpec protocol, which Codegen generated automatically. JSI allows calling methods synchronously without JSON serialization — the speed is fundamentally different.
Problem: if the project has at least one package without Turbo Module support, the New Architecture will run in compatibility mode, partially losing the advantages. Our team helps perform a dependency audit and plan migration without downtime.
How to Develop a Native Module: Step-by-Step Plan
- Determine the requirements for the native API and choose the architecture (Old Bridge or Turbo Module).
- Create a Swift class inheriting from NSObject and add @objc attributes.
- Register the module in the Objective-C bridging file via RCT_EXTERN_MODULE.
- Implement methods with Promises or Events, ensuring thread safety.
- Write TypeScript types for the public API.
- Cover the native code with unit tests (XCTest).
- Test the integration with the JS layer on a simulator and a real device.
Implementation Approach
We start with an audit of the current RN version, presence of JSI-compatible packages, and target iOS deployment. If the project is on a version supporting the New Architecture and the team is ready, we immediately write a Turbo Module with Codegen. If not, we use the classic RCTBridgeModule with an eye on future migration.
Covering the native part with unit tests via XCTest is mandatory. Integration tests are done with Detox or Jest with a mock of the module on the JS side. This reduces the number of bugs in the release by 40%.
We document the public API in TypeScript types so the team doesn't have to dive into native code each time. The result is a 2x acceleration of onboarding for new developers.
| Common Mistake | Consequence | Solution |
|---|---|---|
| Missing @objc on class | Module does not register | Add @objc(ModuleName) |
| Calling UIKit without main.async | App crash | DispatchQueue.main.async |
| Double call of callback | App crash | Use Promise or guard |
| Passing custom object | Serialization error | Parse into NSDictionary |
What's Included in the Work
- Requirements analysis and architectural approach selection (Old Bridge / Turbo Module)
- Writing native code in Swift with Objective-C bridging
- TypeScript typing of the module's public API
- Error handling, thread safety
- Unit tests for the native part (XCTest)
- Integration with the JS layer, verification on simulator and real device
- Documentation on module usage
Timelines
From 3 to 5 days depending on the complexity of the native API to be wrapped. A simple wrapper over one system framework takes about 3 days. A module with event stream, binary data, and New Architecture support takes 5 days or more. The cost is calculated individually after requirements analysis and codebase review.
Get a consultation — contact us for a preliminary estimate of your project. Order Native Module development from us — we guarantee stability and performance.