React Native + Expo + Metro + 네이티브 구현 완전 해설

flowchart LR
  subgraph OLD["구 아키텍처 (Bridge)"]
    direction TB
    J1["JS 스레드<br/>React 로직"] -->|"JSON 직렬화"| BR["Bridge<br/>비동기 큐 ⚠"]
    BR -->|"JSON 역직렬화"| N1["네이티브 스레드<br/>UIKit / Android View"]
    SH["Shadow 스레드<br/>Yoga 레이아웃"] --> N1
  end
  subgraph NEW["신 아키텍처 (JSI)"]
    direction TB
    HM["Hermes 엔진<br/>바이트코드 실행"] -->|"C++ 직접 참조"| JSI["JSI<br/>Host Objects"]
    JSI --> FAB["Fabric<br/>동기 렌더러"]
    JSI --> TM["TurboModules<br/>지연 초기화"]
    FAB --> N2["네이티브 레이어"]
    TM --> N2
  end

flowchart TD
  SPEC["JS Spec 파일<br/>TypeScript / Flow로 타입 정의"]

  subgraph BUILD["빌드 시"]
    CG["Codegen<br/>pod install / Gradle 시 실행"]
  end

  subgraph OUT["생성되는 결과물"]
    CPP["C++ 추상 클래스<br/>TurboModule 기반 인터페이스"]
    DESC["Component Descriptor<br/>Fabric 네이티브 컴포넌트용"]
    JSTYPE["JS 타입 정의<br/>.d.ts 상당"]
  end

  subgraph NATIVE["네이티브 구현"]
    IOS["iOS<br/>Swift / Obj-C로 구현"]
    AND["Android<br/>Kotlin / Java로 구현"]
  end

  RUNTIME["JSI 경유<br/>타입 안전 · 동기 호출"]

  SPEC --> CG
  CG --> CPP & DESC & JSTYPE
  CPP --> IOS & AND
  DESC --> IOS & AND
  IOS --> RUNTIME
  AND --> RUNTIME

flowchart LR
  SRC[".js / .ts / .tsx<br/>소스 파일"]
  RES["해석<br/>import 경로 해결"]
  TRA["변환<br/>Babel ES 변환"]
  SER["직렬화<br/>번들 생성"]
  DEV["단말기에 전달<br/>HTTP :8081"]
  HMR["HMR<br/>변경 모듈만 재전송"]
  CACHE["파일 시스템 캐시<br/>2회차부터 고속"]

  SRC --> RES --> TRA --> SER --> DEV
  TRA -.->|"파일 변경 감지"| HMR
  HMR -.->|"상태 유지하며 반영"| DEV
  TRA <-.->|"변환 결과 캐시"| CACHE

flowchart TD
  APP["내 앱<br/>App.tsx / screens / hooks"]
  SDK["Expo SDK<br/>expo-camera / expo-location / expo-router …"]
  EMC["expo-modules-core<br/>Swift / Kotlin DSL로 타입 안전 기술"]
  RN["React Native Core<br/>View / Text / Animated / StyleSheet"]
  IOS["iOS<br/>UIKit / AVFoundation / CoreLocation"]
  AND["Android<br/>View / Camera2 / LocationManager"]
  GO["Expo Go<br/>QR 스캔으로 즉시 실행"]
  EASB["EAS Build<br/>클라우드에서 .ipa / .apk 생성"]
  EASU["EAS Update<br/>OTA로 JS 번들만 배포"]
  STORE["App Store / Google Play"]

  APP --> SDK
  EMC --> SDK
  SDK --> RN
  RN --> IOS & AND
  GO -->|"개발 시 호스팅"| APP
  EASB --> STORE
  EASU -->|"App Store 심사 없음"| APP

flowchart TD
  START["필요한 네이티브 기능은?"]

  START --> Q1{"Expo SDK / 공개 라이브러리로<br/>커버 가능?"}
  Q1 -->|"예"| MANAGED["Managed Workflow<br/>네이티브 코드 불필요<br/>npx expo start만으로 완결"]
  Q1 -->|"아니오"| Q2{"Config Plugin으로<br/>설정 변경만으로 해결 가능?<br/>(Info.plist / AndroidManifest 추가 등)"}
  Q2 -->|"예"| PLUGIN["Config Plugin 작성<br/>app.json에 추가<br/>prebuild로 자동 적용"]
  Q2 -->|"아니오"| Q3{"독자 네이티브 코드의 규모는?"}
  Q3 -->|"경량<br/>(기존 SDK 래핑)"| BARE["Bare Workflow<br/>npx expo prebuild<br/>→ ios/ android/ 직접 관리"]
  Q3 -->|"본격적<br/>(독자 모듈 / UI)"| MODULE{"무엇을 만드나?"}
  MODULE -->|"로직 계열<br/>Bluetooth / 결제 / 암호화"| TM["TurboModule<br/>+ Codegen"]
  MODULE -->|"UI 컴포넌트 계열<br/>커스텀 카메라 뷰 등"| FAB["Fabric Component<br/>+ Codegen"]
  BARE --> TM & FAB
  PLUGIN --> BARE

flowchart TB
  subgraph JS["JS 레이어 (Hermes)"]
    APP["앱 코드 / React 컴포넌트"]
    SPEC["JS Spec<br/>(TypeScript + TurboModuleRegistry)"]
  end

  subgraph CODEGEN["Codegen (빌드 시 자동 생성)"]
    GEN_CPP["C++ 추상 클래스<br/>TurboModule / ComponentDescriptor"]
    GEN_SHADOW["ShadowNode / Props 정의"]
  end

  subgraph JSI_LAYER["JSI 레이어 (C++)"]
    JSI["JSI Host Object"]
    FABRIC["Fabric 렌더러"]
  end

  subgraph NATIVE_IOS["iOS 네이티브 구현"]
    SWIFT["Swift / Obj-C 구현 클래스<br/>(C++ 추상 클래스 상속)"]
    SDK_IOS["사내 SDK / 외부 .framework<br/>예: CoreBluetooth / Stripe"]
    UIVIEW["UIView 서브클래스<br/>(커스텀 UI 컴포넌트)"]
  end

  subgraph NATIVE_AND["Android 네이티브 구현"]
    KOTLIN["Kotlin / Java 구현 클래스<br/>(C++ 추상 클래스 상속)"]
    SDK_AND["사내 SDK / 외부 .aar<br/>예: BluetoothGatt / Stripe"]
    ANDROIDVIEW["View 서브클래스<br/>(커스텀 UI 컴포넌트)"]
  end

  SPEC -->|"타입 정의 읽기"| CODEGEN
  GEN_CPP --> JSI
  GEN_SHADOW --> FABRIC
  APP -->|"동기 / 비동기 호출"| JSI
  JSI --> SWIFT & KOTLIN
  FABRIC --> UIVIEW & ANDROIDVIEW
  SWIFT --> SDK_IOS
  KOTLIN --> SDK_AND

// src/specs/NativeBluetoothModule.ts
import type { TurboModule, CodegenTypes } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export type ScanResult = {
  id: string;
  name: string;
  rssi: number;
};

export interface Spec extends TurboModule {
  startScan(serviceUUIDs: string[]): void;
  stopScan(): void;
  connect(deviceId: string): Promise<boolean>;
  readonly onDeviceFound: CodegenTypes.EventEmitter<ScanResult>;
}

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

flowchart LR
  SPEC["NativeBluetoothModule.ts<br/>(개발자가 작성)"]

  subgraph AUTO["자동 생성 코드"]
    CPP["C++ glue code<br/>JSI / Codegen 생성물"]
    IOS_H["iOS glue code<br/>Obj-C++ / header 생성물"]
    AND_J["Android glue code<br/>JNI / Spec 클래스 생성물"]
  end

  subgraph IMPL["개발자가 구현"]
    SWIFT_IMPL["NativeBluetoothModule.swift<br/>생성된 Spec을 구현하고 CoreBluetooth 호출"]
    KOTLIN_IMPL["NativeBluetoothModule.kt<br/>생성된 Spec을 구현하고 BluetoothGatt 호출"]
  end

  SPEC --> CPP
  SPEC --> IOS_H
  SPEC --> AND_J
  CPP --> SWIFT_IMPL & KOTLIN_IMPL
  IOS_H --> SWIFT_IMPL
  AND_J --> KOTLIN_IMPL

// ios/NativeBluetoothModule.swift
import CoreBluetooth

@objc(NativeBluetoothModule)
class NativeBluetoothModule: NativeBluetoothModuleSpec, CBCentralManagerDelegate {
  private var centralManager: CBCentralManager!

  override func startScan(_ serviceUUIDs: [String]) {
    let uuids = serviceUUIDs.map { CBUUID(string: $0) }
    centralManager.scanForPeripherals(withServices: uuids)
  }

  func centralManager(_ central: CBCentralManager,
                      didDiscover peripheral: CBPeripheral,
                      advertisementData: [String: Any], rssi: NSNumber) {
    emitOnDeviceFound([
      "id": peripheral.identifier.uuidString,
      "name": peripheral.name ?? "",
      "rssi": rssi
    ])
  }
}

// android/src/main/java/NativeBluetoothModule.kt
class NativeBluetoothModule(reactContext: ReactApplicationContext)
    : NativeBluetoothModuleSpec(reactContext), BluetoothGatt.Callback {

  private val adapter = BluetoothAdapter.getDefaultAdapter()

  override fun startScan(serviceUUIDs: ReadableArray) {
    val filters = serviceUUIDs.toArrayList().map { uuid ->
      ScanFilter.Builder().setServiceUuid(ParcelUuid.fromString(uuid as String)).build()
    }
    adapter.bluetoothLeScanner.startScan(filters, ScanSettings.Builder().build(), scanCallback)
  }

  private val scanCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
      val params = Arguments.createMap().apply {
        putString("id", result.device.address)
        putString("name", result.device.name ?: "")
        putInt("rssi", result.rssi)
      }
      emitOnDeviceFound(params)
    }
  }
}

// src/specs/NativeCameraViewSpec.ts
import type { ViewProps } from 'react-native';
import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
import type { DirectEventHandler, Float } from 'react-native/Libraries/Types/CodegenTypes';

type FrameCapturedEvent = Readonly<{
  uri: string;
}>;

interface NativeProps extends ViewProps {
  zoom?: Float;          // Codegen이 Float → CGFloat / float로 변환
  torchEnabled?: boolean;
  onFrameCaptured?: DirectEventHandler<FrameCapturedEvent>;
}

export default codegenNativeComponent<NativeProps>('CameraView');

# ios/Podfile
pod 'CompanyPaymentSDK', :path => '../vendor/ios/CompanyPaymentSDK'
# 또는 xcframework의 경우
pod 'CompanyPaymentSDK', :podspec => '../vendor/ios/CompanyPaymentSDK.podspec'

// android/app/build.gradle
dependencies {
  implementation files('../vendor/android/company-payment-sdk.aar')
  // 또는 사내 Maven 저장소
  implementation 'com.company:payment-sdk:1.4.0'
}

flowchart TD
  INIT["npx create-expo-app MyApp<br/>--template blank-typescript"]

  subgraph START["npx expo start"]
    METRO["Metro Bundler 시작<br/>port 8081"]
    QR["QR 코드 + 단축키 표시<br/>i = iOS  a = Android  w = Web"]
  end

  subgraph DEVICE["연결 대상 선택"]
    SIM["iOS Simulator<br/>Xcode 포함 (Mac 전용)"]
    EMU["Android Emulator<br/>Android Studio AVD"]
    GO["실기기 + Expo Go<br/>LAN 또는 Tunnel"]
  end

  subgraph NATIVE_BUILD["최초에만: 네이티브 빌드"]
    POD["pod install<br/>iOS CocoaPods"]
    GRADLE["Gradle build<br/>Android"]
    CODEGEN_RUN["Codegen 실행<br/>Spec → 네이티브 템플릿"]
  end

  BUNDLE["JS 번들 기기에 전송<br/>Metro HTTP 서버 경유"]
  RENDER["화면 표시"]

  INIT --> START
  METRO --> QR
  QR --> SIM & EMU & GO
  SIM --> NATIVE_BUILD
  EMU --> NATIVE_BUILD
  NATIVE_BUILD --> BUNDLE
  GO --> BUNDLE
  BUNDLE --> RENDER

flowchart TD
  subgraph CHANGE["변경 종류로 분기"]
    JS_ONLY["JS만 변경<br/>컴포넌트 / 로직 / 스타일"]
    NATIVE_CHANGE["네이티브 코드 변경<br/>Swift / Kotlin / Spec / Podfile"]
  end

  subgraph JS_LOOP["JS 변경 루프 (고속)"]
    METRO_HMR["Metro HMR<br/>차분 번들 전송<br/>수백 ms"]
    SIM_JS["에뮬레이터에 즉시 반영<br/>앱 상태 유지"]
  end

  subgraph NATIVE_LOOP["네이티브 변경 루프 (저속)"]
    CODEGEN_RUN["Codegen 재실행<br/>pod install (iOS)<br/>Gradle sync (Android)"]
    REBUILD["네이티브 재빌드<br/>npx expo run:ios<br/>npx expo run:android"]
    SIM_NATIVE["에뮬레이터 / 실기기에서 확인"]
  end

  JS_ONLY --> METRO_HMR --> SIM_JS
  NATIVE_CHANGE --> CODEGEN_RUN --> REBUILD --> SIM_NATIVE

  SIM_JS -->|"이상 없음"| DONE["동작 확인 완료"]
  SIM_NATIVE -->|"이상 없음"| DONE
  SIM_JS -->|"버그 발견"| DEBUG_JS["Hermes Debugger<br/>React DevTools"]
  SIM_NATIVE -->|"네이티브 크래시"| DEBUG_NATIVE["Xcode / Android Studio<br/>네이티브 디버거"]
  DEBUG_JS --> JS_ONLY
  DEBUG_NATIVE --> NATIVE_CHANGE

flowchart TD
  SYMPTOM["증상 관찰"]

  SYMPTOM --> Q1{"크래시 종류"}

  Q1 -->|"JS 오류<br/>LogBox 빨간 화면"| JS_ERR["Hermes Debugger로 조사<br/>브레이크포인트, 스택 트레이스<br/>Source Map으로 TS 줄번호"]
  Q1 -->|"네이티브 크래시<br/>앱이 종료 / 프리즈"| NAT_ERR["크래시 로그 확인"]
  Q1 -->|"동작은 하지만<br/>결과가 이상함"| BORDER["JS↔Native 경계 의심"]

  NAT_ERR --> IOS_CRASH["iOS: Xcode<br/>Debug Navigator<br/>+ lldb 연결"]
  NAT_ERR --> AND_CRASH["Android: Android Studio<br/>Logcat 스택 트레이스<br/>+ Native Debugger"]

  BORDER --> LOG_IOS["iOS: NSLog / os_log<br/>npx react-native log-ios"]
  BORDER --> LOG_AND["Android: Log.d<br/>npx react-native log-android"]
  BORDER --> JS_LOG["JS 측: console.log로<br/>TurboModule 반환값 확인"]

  IOS_CRASH --> INSTRUMENTS["Instruments<br/>Time Profiler / Allocations<br/>메모리 누수 / CPU 특정"]
  AND_CRASH --> PROFILER["Android Studio<br/>Memory / CPU Profiler"]

  JS_ERR --> FIXED["수정 → Metro HMR로 즉시 반영"]
  INSTRUMENTS --> FIXED2["수정 → npx expo run:ios로 확인"]
  PROFILER --> FIXED3["수정 → npx expo run:android로 확인"]
  LOG_IOS & LOG_AND & JS_LOG --> BORDER2["원인 파악<br/>→ Spec / 구현 수정"]

# iOS: 실행 중인 시뮬레이터에 lldb 연결
npx expo run:ios --configuration Debug
# → Xcode가 자동으로 열리고 디버거가 연결됨

# Android
npx expo run:android
# → "Run > Attach Debugger to Android Process"로 연결

// Swift 측
os_log("BluetoothModule.connect called: %{public}@", deviceId)
// → npx react-native log-ios로 필터링해 확인

// Kotlin 측
Log.d("BluetoothModule", "connect called: $deviceId")
// → npx react-native log-android로 필터링해 확인

// JS 측
const result = await BluetoothModule.connect(deviceId);
console.log('connect result:', result); // Metro에 출력

npx react-devtools
# → 포트 8097에서 기기 연결 대기

① JS Spec 작성 (TypeScript로 타입 정의)
       ↓
② pod install / gradle build → Codegen이 C++ 템플릿 자동 생성
       ↓
③ Swift / Kotlin으로 구현 (사내 SDK / 외부 라이브러리 호출)
       ↓
④ npx expo run:ios / run:android로 네이티브 빌드 & 에뮬레이터 확인
       ↓
⑤ JS 측 호출 코드 작성 → Metro HMR로 고속 이터레이션
       ↓
⑥ JS 오류 → Hermes Debugger
   네이티브 크래시 → Xcode / Android Studio 디버거
   경계 불일치 → log-ios / log-android + console.log로 샌드위치
       ↓
⑦ 실기기에서 Bluetooth / 카메라 / 센서 계열 검증
       ↓
⑧ EAS Build로 스토어용 바이너리 생성