mobile-react-native-native-modules

Accessing iOS-specific APIs not available in React Native

React Native Native Modules

Scope: Native modules, bridging Swift/Objective-C, iOS APIs, TurboModules, native UI components Lines: ~350 Last Updated: 2025-10-18

When to Use This Skill

Activate this skill when:

• Accessing iOS-specific APIs not available in React Native
• Implementing performance-critical native functionality
• Integrating third-party iOS SDKs
• Creating custom native UI components
• Bridging existing Swift/Objective-C code to React Native
• Using iOS hardware features (Camera, Bluetooth, etc.)
• Implementing native background tasks or services

Core Concepts

Native Module Architecture

Bridge Pattern:

• JavaScript thread runs React Native code
• Native thread runs iOS code
• Bridge serializes data between threads (JSON-like)
• Asynchronous by default (callbacks/promises)

TurboModules (New Architecture):

• Direct JavaScript to native communication (no bridge)
• Type-safe with Codegen
• Synchronous methods possible
• Better performance (lazy loading)

Communication Flow:

JavaScript → Bridge → Native Module → iOS API
iOS API → Native Module → Bridge → JavaScript

Swift Bridging

Bridging Header (Objective-C interop):

• Required for Swift modules in RN < 0.74
• Exposes Swift to Objective-C runtime
• Auto-generated by Xcode
• Manual updates for custom types

@objc Attribute:

• Makes Swift code visible to Objective-C
• Required for RCT macros
• Adds some runtime overhead
• Necessary for React Native bridge

Event Emitters

Push vs Pull:

• Callbacks: One-time data return
• Promises: Single async result
• Events: Continuous stream of data

Use Cases:

• Sensor data (accelerometer, GPS)
• Notifications (local, push)
• Network state changes
• Background task updates

---

Patterns

Pattern 1: Basic Swift Native Module

// ios/MyModule.swift
import Foundation
import React

@objc(MyModule)
class MyModule: NSObject {

  // MARK: - React Native Export

  @objc
  static func requiresMainQueueSetup() -> Bool {
    return false // Run on background thread
  }

  @objc
  func greet(_ name: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {
    let greeting = "Hello, \(name)!"
    resolver(greeting)
  }

  @objc
  func calculateSum(_ a: NSNumber, b: NSNumber, callback: @escaping RCTResponseSenderBlock) {
    let sum = a.doubleValue + b.doubleValue
    callback([NSNull(), sum]) // [error, result] pattern
  }

  @objc
  func getDeviceInfo() -> NSDictionary {
    return [
      "model": UIDevice.current.model,
      "systemVersion": UIDevice.current.systemVersion,
      "name": UIDevice.current.name
    ]
  }
}

// ios/MyModule.m (Bridging file)
#import <React/RCTBridgeModule.h>

@interface RCT_EXTERN_MODULE(MyModule, NSObject)

RCT_EXTERN_METHOD(greet:(NSString *)name
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)

RCT_EXTERN_METHOD(calculateSum:(nonnull NSNumber *)a
                  b:(nonnull NSNumber *)b
                  callback:(RCTResponseSenderBlock)callback)

RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(getDeviceInfo)

@end

// src/modules/MyModule.ts
import { NativeModules } from 'react-native';

interface MyModuleInterface {
  greet(name: string): Promise<string>;
  calculateSum(a: number, b: number, callback: (error: any, result: number) => void): void;
  getDeviceInfo(): { model: string; systemVersion: string; name: string };
}

const { MyModule } = NativeModules;

export default MyModule as MyModuleInterface;

Benefits:

• Type-safe TypeScript interface
• Async methods with promises
• Synchronous methods for simple data
• Callback pattern for legacy code

Pattern 2: Event Emitter Native Module

// ios/SensorModule.swift
import Foundation
import CoreMotion
import React

@objc(SensorModule)
class SensorModule: RCTEventEmitter {

  private var motionManager: CMMotionManager?
  private var isObserving = false

  override init() {
    super.init()
    motionManager = CMMotionManager()
  }

  // MARK: - React Native Export

  override static func requiresMainQueueSetup() -> Bool {
    return false
  }

  override func supportedEvents() -> [String]! {
    return ["onAccelerometerData", "onDeviceMotion"]
  }

  @objc
  func startAccelerometer() {
    guard let manager = motionManager, !isObserving else { return }

    isObserving = true
    manager.accelerometerUpdateInterval = 0.1

    manager.startAccelerometerUpdates(to: .main) { [weak self] (data, error) in
      guard let data = data, error == nil else { return }

      self?.sendEvent(withName: "onAccelerometerData", body: [
        "x": data.acceleration.x,
        "y": data.acceleration.y,
        "z": data.acceleration.z,
        "timestamp": Date().timeIntervalSince1970
      ])
    }
  }

  @objc
  func stopAccelerometer() {
    motionManager?.stopAccelerometerUpdates()
    isObserving = false
  }

  override func stopObserving() {
    stopAccelerometer()
  }
}

// ios/SensorModule.m
#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

@interface RCT_EXTERN_MODULE(SensorModule, RCTEventEmitter)

RCT_EXTERN_METHOD(startAccelerometer)
RCT_EXTERN_METHOD(stopAccelerometer)

@end

// src/modules/SensorModule.ts
import { NativeEventEmitter, NativeModules } from 'react-native';

const { SensorModule } = NativeModules;
const sensorEmitter = new NativeEventEmitter(SensorModule);

export interface AccelerometerData {
  x: number;
  y: number;
  z: number;
  timestamp: number;
}

export const startAccelerometer = () => {
  SensorModule.startAccelerometer();
};

export const stopAccelerometer = () => {
  SensorModule.stopAccelerometer();
};

export const subscribeToAccelerometer = (
  callback: (data: AccelerometerData) => void
) => {
  const subscription = sensorEmitter.addListener('onAccelerometerData', callback);
  return () => subscription.remove();
};

When to use:

• Continuous data streams (sensors, location)
• Push notifications or system events
• Real-time updates from native code
• Background task status updates

Pattern 3: Native UI Component (Swift)

// ios/CircularProgressView.swift
import UIKit

class CircularProgressView: UIView {

  private var progressLayer = CAShapeLayer()
  private var trackLayer = CAShapeLayer()

  @objc var progress: CGFloat = 0 {
    didSet {
      updateProgress()
    }
  }

  @objc var progressColor: UIColor = .systemBlue {
    didSet {
      progressLayer.strokeColor = progressColor.cgColor
    }
  }

  @objc var trackColor: UIColor = .systemGray5 {
    didSet {
      trackLayer.strokeColor = trackColor.cgColor
    }
  }

  override func layoutSubviews() {
    super.layoutSubviews()
    setupLayers()
  }

  private func setupLayers() {
    let center = CGPoint(x: bounds.midX, y: bounds.midY)
    let radius = min(bounds.width, bounds.height) / 2 - 10
    let circularPath = UIBezierPath(
      arcCenter: center,
      radius: radius,
      startAngle: -.pi / 2,
      endAngle: 3 * .pi / 2,
      clockwise: true
    )

    // Track layer
    trackLayer.path = circularPath.cgPath
    trackLayer.fillColor = UIColor.clear.cgColor
    trackLayer.strokeColor = trackColor.cgColor
    trackLayer.lineWidth = 10
    trackLayer.lineCap = .round

    // Progress layer
    progressLayer.path = circularPath.cgPath
    progressLayer.fillColor = UIColor.clear.cgColor
    progressLayer.strokeColor = progressColor.cgColor
    progressLayer.lineWidth = 10
    progressLayer.lineCap = .round
    progressLayer.strokeEnd = 0

    layer.addSublayer(trackLayer)
    layer.addSublayer(progressLayer)
  }

  private func updateProgress() {
    CATransaction.begin()
    CATransaction.setAnimationDuration(0.3)
    progressLayer.strokeEnd = progress
    CATransaction.commit()
  }
}

// ios/CircularProgressViewManager.swift
import React

@objc(CircularProgressViewManager)
class CircularProgressViewManager: RCTViewManager {

  override static func requiresMainQueueSetup() -> Bool {
    return true // UI components need main thread
  }

  override func view() -> UIView! {
    return CircularProgressView()
  }
}

// ios/CircularProgressViewManager.m
#import <React/RCTViewManager.h>

@interface RCT_EXTERN_MODULE(CircularProgressViewManager, RCTViewManager)

RCT_EXPORT_VIEW_PROPERTY(progress, CGFloat)
RCT_EXPORT_VIEW_PROPERTY(progressColor, UIColor)
RCT_EXPORT_VIEW_PROPERTY(trackColor, UIColor)

@end

// src/components/CircularProgress.tsx
import React from 'react';
import { requireNativeComponent, ViewProps } from 'react-native';

interface CircularProgressProps extends ViewProps {
  progress: number; // 0.0 - 1.0
  progressColor?: string;
  trackColor?: string;
}

const NativeCircularProgress = requireNativeComponent<CircularProgressProps>(
  'CircularProgressView'
);

export const CircularProgress: React.FC<CircularProgressProps> = (props) => {
  return <NativeCircularProgress {...props} />;
};

Benefits:

• Native iOS animations and rendering
• Full access to UIKit components
• Performance for complex UI
• Reusable across React Native apps

Pattern 4: Async Native Operations with Error Handling

// ios/NetworkModule.swift
import Foundation
import React

@objc(NetworkModule)
class NetworkModule: NSObject {

  @objc
  static func requiresMainQueueSetup() -> Bool {
    return false
  }

  @objc
  func fetchUser(_ userId: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {

    guard let url = URL(string: "https://api.example.com/users/\(userId)") else {
      rejecter("INVALID_URL", "Invalid user ID", nil)
      return
    }

    URLSession.shared.dataTask(with: url) { data, response, error in
      // Handle network error
      if let error = error {
        rejecter("NETWORK_ERROR", error.localizedDescription, error)
        return
      }

      // Handle HTTP error
      guard let httpResponse = response as? HTTPURLResponse else {
        rejecter("INVALID_RESPONSE", "Invalid response type", nil)
        return
      }

      guard (200...299).contains(httpResponse.statusCode) else {
        rejecter("HTTP_ERROR", "Status code: \(httpResponse.statusCode)", nil)
        return
      }

      // Parse JSON
      guard let data = data else {
        rejecter("NO_DATA", "No data received", nil)
        return
      }

      do {
        let json = try JSONSerialization.jsonObject(with: data, options: [])
        resolver(json)
      } catch {
        rejecter("PARSE_ERROR", "Failed to parse JSON", error)
      }
    }.resume()
  }
}

// src/modules/NetworkModule.ts
import { NativeModules } from 'react-native';

interface User {
  id: string;
  name: string;
  email: string;
}

class NetworkModuleWrapper {
  async fetchUser(userId: string): Promise<User> {
    try {
      const user = await NativeModules.NetworkModule.fetchUser(userId);
      return user as User;
    } catch (error: any) {
      // Error codes from native module
      switch (error.code) {
        case 'INVALID_URL':
          throw new Error('Invalid user ID format');
        case 'NETWORK_ERROR':
          throw new Error('Network connection failed');
        case 'HTTP_ERROR':
          throw new Error(`Server error: ${error.message}`);
        case 'PARSE_ERROR':
          throw new Error('Invalid response format');
        default:
          throw error;
      }
    }
  }
}

export default new NetworkModuleWrapper();

When to use:

• Network requests with iOS URLSession
• File system operations
• Database queries
• Any async native operation

Pattern 5: Swift Concurrency Integration

// ios/ModernAsyncModule.swift
import Foundation
import React

@objc(ModernAsyncModule)
class ModernAsyncModule: NSObject {

  @objc
  static func requiresMainQueueSetup() -> Bool {
    return false
  }

  @objc
  func performAsyncWork(_ input: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {

    Task {
      do {
        let result = try await processData(input)
        resolver(result)
      } catch {
        rejecter("ASYNC_ERROR", error.localizedDescription, error)
      }
    }
  }

  private func processData(_ input: String) async throws -> [String: Any] {
    // Simulate async work
    try await Task.sleep(nanoseconds: 1_000_000_000)

    // Use structured concurrency
    async let part1 = fetchPart1(input)
    async let part2 = fetchPart2(input)

    let results = try await [part1, part2]

    return [
      "input": input,
      "results": results,
      "timestamp": Date().timeIntervalSince1970
    ]
  }

  private func fetchPart1(_ input: String) async throws -> String {
    try await Task.sleep(nanoseconds: 500_000_000)
    return "Part1: \(input)"
  }

  private func fetchPart2(_ input: String) async throws -> String {
    try await Task.sleep(nanoseconds: 500_000_000)
    return "Part2: \(input)"
  }
}

Benefits:

• Modern Swift async/await syntax
• Structured concurrency patterns
• Better error handling
• Cancellation support

Pattern 6: Objective-C Native Module (Legacy)

// ios/LegacyModule.h
#import <React/RCTBridgeModule.h>

@interface LegacyModule : NSObject <RCTBridgeModule>
@end

// ios/LegacyModule.m
#import "LegacyModule.h"

@implementation LegacyModule

RCT_EXPORT_MODULE();

RCT_EXPORT_METHOD(addNumbers:(NSInteger)a
                  b:(NSInteger)b
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  NSInteger sum = a + b;
  resolve(@(sum));
}

RCT_EXPORT_METHOD(performCallback:(RCTResponseSenderBlock)callback)
{
  callback(@[[NSNull null], @"Success"]);
}

+ (BOOL)requiresMainQueueSetup
{
  return NO;
}

@end

When to use:

• Legacy codebases
• Existing Objective-C libraries
• Team familiar with Objective-C
• Interoperating with C/C++ code

---

Quick Reference

Bridge Data Types

JavaScript Type    | Objective-C/Swift Type       | Notes
-------------------|------------------------------|------------------
number             | NSNumber / Double / Int      | Auto-converted
string             | NSString / String            | UTF-8 encoded
boolean            | NSNumber / Bool              | true/false
null/undefined     | NSNull / nil                 | Check for NSNull
Array              | NSArray / [Any]              | Ordered collection
Object             | NSDictionary / [String: Any] | Key-value pairs
Function           | RCTResponseSenderBlock       | Callback
Promise            | RCTPromise(Resolve/Reject)   | Async result

Module Export Macros

RCT_EXPORT_MODULE()                      // Export module with class name
RCT_EXPORT_MODULE(CustomName)            // Export with custom name
RCT_EXPORT_METHOD(methodName:...)        // Export async method
RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD() // Export synchronous method
RCT_EXPORT_VIEW_PROPERTY(name, type)     // Export view property

Best Practices

✅ DO: Use promises for async operations
✅ DO: Validate input parameters
✅ DO: Return descriptive error codes
✅ DO: Run on background thread when possible
✅ DO: Use type-safe TypeScript interfaces

❌ DON'T: Block the main thread with heavy operations
❌ DON'T: Return functions or callbacks from native
❌ DON'T: Store references to JavaScript objects
❌ DON'T: Use synchronous methods for slow operations
❌ DON'T: Forget to handle errors properly

---

Anti-Patterns

❌ Synchronous heavy operations: Blocking main thread with slow native code ✅ Use promises and background threads: requiresMainQueueSetup() -> false

❌ Over-bridging: Calling native for simple logic better done in JS ✅ Use native only for platform APIs, performance-critical code, or third-party SDKs

❌ No error handling: Native errors crash the app ✅ Always use try-catch and reject promises with descriptive error codes

❌ Storing JavaScript callbacks: Memory leaks and crashes ✅ Use event emitters for continuous updates, promises for one-time results

❌ Large data serialization: Sending MB of data across bridge ✅ Use file paths or shared memory, send only metadata

❌ Main thread for async work: UI freezes during operations ✅ Use background threads for network, file I/O, computations

❌ Missing TypeScript types: Untyped native module usage ✅ Create interfaces for all native modules with full type safety

❌ Not cleaning up resources: Memory leaks from sensors, timers, etc. ✅ Implement stopObserving and cleanup in dealloc/deinit

---

Related Skills

• react-native-setup.md - Project configuration for native modules
• react-native-performance.md - Optimizing bridge communication
• swift-concurrency.md - Modern Swift async patterns
• ios-networking.md - URLSession and network best practices
• swiftui-architecture.md - iOS app structure and patterns
• ios-testing.md - Testing native modules

---

Last Updated: 2025-10-18 Format Version: 1.0 (Atomic)