---
id: rn-native-module-bridging
title: RN Native Module — TurboModule (New Arch)
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [react-native, native-module, turbomodule, vibe-coding]
tech_stack: { language: "TS / Swift / Kotlin", applicable_to: ["React Native"] }
applied_in: []
aliases: [TurboModule, Codegen, JSI, native bridge]
---

# RN Native Module (TurboModule)

> JS 가 native API 호출. **New Architecture 의 TurboModule + Codegen** 이 표준. 옛 NativeModule 보다 동기 호출 + 타입 안전. 단 native 코드 작성 필요.

## 📖 핵심 개념
- TS spec 정의 → Codegen 이 native interface 생성.
- iOS Swift / Android Kotlin 구현체 등록.
- JS 가 직접 호출 (JSI).

## 💻 코드 패턴

### 1. TS spec
```ts
// specs/NativeBattery.ts
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  getBatteryLevel(): number;                       // sync
  getInfo(): Promise<{ level: number; charging: boolean }>;
  setBrightness(value: number): void;
}

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

### 2. iOS — Swift
```swift
import Foundation

@objc(NativeBattery)
class NativeBattery: NSObject {

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

  @objc func getBatteryLevel() -> NSNumber {
    UIDevice.current.isBatteryMonitoringEnabled = true
    return NSNumber(value: UIDevice.current.batteryLevel)
  }

  @objc(getInfoWithResolver:rejecter:)
  func getInfo(resolve: @escaping RCTPromiseResolveBlock,
               reject: @escaping RCTPromiseRejectBlock) {
    UIDevice.current.isBatteryMonitoringEnabled = true
    resolve([
      "level": UIDevice.current.batteryLevel,
      "charging": UIDevice.current.batteryState == .charging,
    ])
  }
}
```

### 3. Android — Kotlin
```kotlin
class NativeBatteryModule(reactContext: ReactApplicationContext) :
    NativeBatterySpec(reactContext) {  // codegen 이 만든 abstract class

    override fun getName() = "NativeBattery"

    override fun getBatteryLevel(): Double {
        val bm = reactApplicationContext.getSystemService(Context.BATTERY_SERVICE) as BatteryManager
        return bm.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY) / 100.0
    }

    override fun getInfo(promise: Promise) {
        val map = Arguments.createMap().apply {
            putDouble("level", getBatteryLevel())
            putBoolean("charging", isCharging())
        }
        promise.resolve(map)
    }
}
```

### 4. JS 사용
```ts
import NativeBattery from './specs/NativeBattery';

const level = NativeBattery.getBatteryLevel(); // 동기!
const info = await NativeBattery.getInfo();
```

### Event emitter (native → JS)
```swift
@objc(BatteryEvents)
class BatteryEvents: RCTEventEmitter {
  override func supportedEvents() -> [String] { ["levelChanged"] }
  func notifyLevel(_ level: Float) {
    sendEvent(withName: "levelChanged", body: ["level": level])
  }
}
```

```ts
import { NativeEventEmitter, NativeModules } from 'react-native';

const emitter = new NativeEventEmitter(NativeModules.BatteryEvents);
const sub = emitter.addListener('levelChanged', e => console.log(e.level));
return () => sub.remove();
```

## 🤔 의사결정 기준
| 필요 | 도구 |
|---|---|
| 기존 native API 노출 | TurboModule |
| 무거운 native 처리 (이미지, ML) | TurboModule + JSI direct |
| 기존 RN 라이브러리로 충분 | 커뮤니티 라이브러리 우선 |
| Expo 환경 | config plugin + Expo Modules |
| 한 platform 만 | Platform-specific module |

## ❌ 안티패턴
- **bridge spam (per-frame native call)**: 큰 부하. batched API 권장.
- **순환 참조 (RN ↔ Native)**: leak.
- **callback 만 + Promise X**: 모던 코드는 Promise.
- **Codegen 안 쓰고 NativeModuleSpec 수동 작성**: type safety 잃음.
- **iOS / Android API 비대칭**: cross-platform JS 깨짐. spec 일관.
- **에러를 generic Error 로**: 디버깅 어려움. 명시적 code + message.

## 🤖 LLM 활용 힌트
- New Architecture 가정. Codegen + TurboModule.
- iOS Swift / Android Kotlin 양쪽 같이 작성.

## 🔗 관련 문서
- [[React_Native_Bridge_Performance]]
- [[iOS_Swift_Concurrency_async_await]]