2nd/10_Wiki/Topics/Coding/RN_Native_Module_Bridging.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
rn-native-module-bridging	RN Native Module — TurboModule (New Arch)	Coding	draft	B	conceptual	2026-05-09	2026-05-09	react-native native-module turbomodule vibe-coding	language applicable_to TS / Swift / Kotlin React Native		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

// 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

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

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 사용

import NativeBattery from './specs/NativeBattery';

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

Event emitter (native → JS)

@objc(BatteryEvents)
class BatteryEvents: RCTEventEmitter {
  override func supportedEvents() -> [String] { ["levelChanged"] }
  func notifyLevel(_ level: Float) {
    sendEvent(withName: "levelChanged", body: ["level": level])
  }
}

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