[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/RN_Native_Module_Bridging.md

@@ -0,0 +1,140 @@
+---
+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]]