React Native custom modules

cleaner codebases.

Core Solution

Building a React Native custom module using the New Architecture requires three phases: contract definition, native implementation, and runtime integration. We will implement a DeviceBatteryModule that exposes battery level, charging state, and a low-battery event listener.

1. Define the TypeScript Contract with Codegen

Codegen generates platform-specific bindings from a TypeScript specification. This eliminates manual bridge registration and enforces type safety.

// src/modules/DeviceBatteryModule.ts
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  getBatteryLevel(): Promise<number>;
  isCharging(): Promise<boolean>;
  addListener(eventName: 'onLowBattery'): void;
  removeListeners(count: number): void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('DeviceBatteryModule');

2. Configure Codegen in package.json

Codegen requires explicit module registration to generate iOS and Android bindings during build.

{
  "codegenConfig": {
    "name": "DeviceBatteryModuleSpec",
    "type": "modules",
    "jsSrcsDir": "src/modules"
  }
}

Run npx react-native codegen to generate:

• DeviceBatteryModuleSpec.h (iOS)
• DeviceBatteryModuleSpec.java (Android)
• Type-safe JS stubs

3. Implement iOS (Swift)

TurboModules on iOS conform to the generated protocol and use @ReactModule for registration.

// ios/DeviceBatteryModule.swift
import Foundation
import React

@objc(DeviceBatteryModule)
class DeviceBatteryModule: NSObject, DeviceBatteryModuleSpec {
  
  private var eventEmitter: RCTEventEmitter?
  
  @objc
  func constantsToExport() -> [AnyHashable : Any]! {
    return ["supportedEvents": ["onLowBattery"]]
  }
  
  func getBatteryLevel() async -> Double {
    UIDevice.current.isBatteryMonitoringEnabled = true
    return UIDevice.current.batteryLevel
  }
  
  func isCharging() async -> Bool {
    UIDevice.current.isBatteryMonitoringEnabled = true
    return UIDevice.current.batteryState == .charging || UIDevice.current.batteryState == .full
  }
  
  func addListener(_ eventName: String) {
    // TurboModule handles subscription tracking automatically
  }
  
  func removeListeners(_ count: Double) {
    // Cleanup handled by TurboModule lifecycle
  }
  
  @objc
  static func requiresMainQueueSetup() -> Bool {
    return false
  }
}

4. Implement Android (Kotlin)

Android TurboModules extend ReactContextBaseJavaModule and implement the generated spec interface.

// android/src/main/java/com/yourapp/DeviceBatteryModule.kt
package com.yourapp

import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.bridge.ReactMethod
import com.facebook.react.bridge.Promise
import com.facebook.react.module.annotations.ReactModule
import android.content.Intent
import android.content.IntentFilter
import android.os.BatteryManager
import com.yourapp.DeviceBatteryModuleSpec

@ReactModule(name = DeviceBatteryModule.NAME)
class DeviceBatteryModule(reactContext: ReactApplicationContext) :
  ReactContextBaseJavaModule(reactContext), DeviceBatteryModuleSpec {

  companion object {
    const val NAME = "DeviceBatteryModule"
  }

  override fun getName(): String = NAME

  @ReactMethod(isBlockingSynchronousMethod = true)
  override fun getBatteryLevel(): Double {
    val batteryManager = reactApplicationContext.getSystemService(BatteryManager::class.java)
    return batteryManager?.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)?.toDouble() ?: 0.0
  }

  @ReactMethod(isBlockingSynchronousMethod = true)
  override fun isCharging(): Boolean {
    val intent = reactApplicationContext.registerReceiver(null, IntentFilter(Intent.ACTION_BATTERY_CHANGED))
    val status = intent?.getIntExtra(BatteryManager.EXTRA_STATUS, -1) ?: -1
    return status == BatteryManager.BATTERY_STATUS_CHARGING || status == BatteryManager.BATTERY_STATUS_FULL
  }

  @ReactMethod
  override fun addListener(eventName: String) {
    // TurboModule manages listener lifecycle
  }

  @ReactMethod
  override fun removeListeners(count: Double) {
    // Cleanup handled by TurboModule
  }
}

5. Wire Up in TypeScript

Consume the module with full type safety. No manual linking or native registration required.

// src/services/BatteryService.ts
import DeviceBatteryModule from '../modules/DeviceBatteryModule';

export const getBatteryInfo = async () => {
  const level = await DeviceBatteryModule.getBatteryLevel();
  const charging = await DeviceBatteryModule.isCharging();
  return { level, charging };
};

Architecture Rationale

• Codegen over manual registration: Eliminates platform-specific boilerplate, ensures signature parity, and catches type mismatches at compile time.
• TurboModule over legacy bridge: Lazy-loading reduces startup overhead. Direct spec conformance removes bridge serialization. Async/await patterns align with modern JS runtime expectations.
• Thread boundary enforcement: iOS uses requiresMainQueueSetup() = false to avoid UI thread blocking. Android uses @ReactMethod with explicit promise/callback patterns. Heavy computation should always dispatch to background queues.
• Event listener management: TurboModules handle subscription tracking internally. Manual RCTDeviceEventEmitter usage is deprecated for new modules.

Pitfall Guide

1. Running native code on the UI thread without offloading Native modules execute on the bridge thread by default. Blocking operations (file I/O, network requests, heavy calculations) freeze the JS thread. Always dispatch to background queues (DispatchQueue.global() on iOS, Executors.newSingleThreadExecutor() on Android) and return results via promises or callbacks.

2. Retaining strong references to React context or views Holding ReactApplicationContext or UIView references beyond module lifecycle causes memory leaks. Use weak references for context, and explicitly nil out native observers in onCatalystInstanceDestroy() (Android) or deinit (iOS).

3. Assuming synchronous bridge calls still work The legacy @ReactMethod(isBlockingSynchronousMethod = true) is deprecated in New Architecture. TurboModules enforce async boundaries. Synchronous patterns will fail at runtime or trigger bridge warnings. Refactor to Promise<T> or callback signatures.

4. Passing large objects instead of primitives or identifiers Cross-language serialization penalizes payload size. Instead of passing entire native models, pass IDs or hashes. Fetch full data on-demand or stream it via native events. This reduces memory pressure and GC frequency.

5. Ignoring platform-specific error boundaries Native failures (permission denials, hardware unavailable, OS version gaps) must map to typed JS errors. Never swallow exceptions. Use Promise.reject() with structured error codes, and validate platform capabilities before invoking hardware APIs.

6. Skipping Codegen after spec changes TypeScript spec modifications do not auto-sync to native. Failing to run npx react-native codegen results in signature mismatches, silent failures, or build crashes. Integrate codegen into pre-commit hooks or CI pipelines.

7. Duplicating module logic across platforms Custom modules should expose a unified contract. Platform-specific implementations must converge on the same TypeScript interface. If logic diverges, abstract shared behavior into a common utility layer and isolate platform adapters.

Production Bundle

Action Checklist

• Define TypeScript contract: Create a TurboModule spec with explicit method signatures and event types
• Run Codegen: Execute npx react-native codegen after every spec modification and verify generated bindings
• Enforce thread boundaries: Offload blocking operations to background queues; never block UI or JS threads
• Implement structured error handling: Map native exceptions to typed JS errors with consistent error codes
• Manage native lifecycle: Release observers, nil context references, and clean up hardware monitors on module destruction
• Validate platform capabilities: Check OS version, permissions, and hardware availability before invoking native APIs
• Add integration tests: Mock native responses in Jest, verify promise resolution, and test event emission flows
• Document cross-platform behavior: Specify platform limitations, fallback strategies, and performance characteristics

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Accessing standard platform APIs (battery, sensors, storage)	TurboModule + Codegen	Type-safe, lazy-loaded, minimal boilerplate, aligns with RN New Architecture	Low (standard toolchain, fast iteration)
Ultra-low latency C++ interop (video processing, real-time audio)	Direct JSI Binding	Bypasses JSI bridge entirely, enables synchronous C++ execution	High (C++ toolchain, manual memory management, steeper learning curve)
Expo-managed projects or CI-constrained environments	Expo Config Plugin + Native Module	Leverages Expo's native build pipeline, avoids manual linking, supports prebuild	Medium (Expo dependency, but reduces setup overhead)
Legacy codebase with existing bridge modules	Incremental TurboModule migration	Replace high-traffic modules first, maintain bridge compatibility during transition	Medium (dual-runtime support temporarily, long-term savings)
Simple one-off native calls (analytics, deep links)	Use existing community packages	Avoids custom module overhead; community packages are battle-tested and maintained	Low (dependency risk, but faster delivery)

Configuration Template

package.json (Codegen registration)

{
  "name": "your-app",
  "version": "1.0.0",
  "codegenConfig": {
    "name": "CustomModuleSpec",
    "type": "modules",
    "jsSrcsDir": "src/modules"
  }
}

TypeScript Spec (src/modules/CustomModule.ts)

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  initialize(config: { apiKey: string }): Promise<void>;
  executeTask(taskId: string, payload: Record<string, unknown>): Promise<boolean>;
  addListener(eventName: 'onTaskComplete' | 'onError'): void;
  removeListeners(count: number): void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('CustomModule');

Android build.gradle (Module registration)

apply plugin: 'com.android.library'

android {
  namespace "com.yourapp.custommodule"
  compileSdkVersion 34

  defaultConfig {
    minSdkVersion 24
  }

  buildTypes {
    release { minifyEnabled false }
  }
}

dependencies {
  implementation 'com.facebook.react:react-android:+'
}

iOS Podfile (TurboModule linking)

use_frameworks! :linkage => :static

target 'YourApp' do
  config = use_native_modules!
  
  use_react_native!(
    :path => config[:reactNativePath],
    :hermes_enabled => true,
    :fabric_enabled => true
  )
  
  # Auto-linked via Codegen; no manual pod addition required
end

Quick Start Guide

1. Scaffold the contract: Create src/modules/MyModule.ts with a TurboModule interface defining methods, parameters, and events.
2. Register Codegen: Add codegenConfig to package.json, then run npx react-native codegen to generate iOS/Android bindings.
3. Implement native adapters: Create Swift and Kotlin classes conforming to the generated specs. Register them with @ReactModule (iOS) and @ReactModule/ReactContextBaseJavaModule (Android).
4. Consume in TypeScript: Import the generated module stub, call methods with await, and attach event listeners. Verify type safety and async behavior.
5. Validate & ship: Run npx react-native run-ios and npx react-native run-android. Test thread safety, error propagation, and event emission. Add to CI with codegen pre-build step.