React Native + Expo + Metro + ネイティブ実装の完全解説

flowchart LR
  subgraph OLD["旧アーキテクチャ（Bridge）"]
    direction TB
    J1["JS Thread<br/>React ロジック"] -->|"JSON serialize"| BR["Bridge<br/>非同期キュー ⚠"]
    BR -->|"JSON deserialize"| N1["Native Thread<br/>UIKit / Android View"]
    SH["Shadow Thread<br/>Yoga layout"] --> N1
  end
  subgraph NEW["新アーキテクチャ（JSI）"]
    direction TB
    HM["Hermes Engine<br/>バイトコード実行"] -->|"C++ 直接参照"| JSI["JSI<br/>Host Objects"]
    JSI --> FAB["Fabric<br/>同期 Renderer"]
    JSI --> TM["TurboModules<br/>遅延初期化"]
    FAB --> N2["Native Layer"]
    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["Resolution<br/>import パス解決"]
  TRA["Transformation<br/>Babel でES変換"]
  SER["Serialization<br/>バンドル生成"]
  DEV["端末へ配信<br/>HTTP :8081"]
  HMR["HMR<br/>差分モジュールのみ再送"]
  CACHE["FSキャッシュ<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 -->|"Dev 時にホスト"| APP
  EASB --> STORE
  EASU -->|"App Store 審査なし"| APP

flowchart TD
  START["必要なネイティブ機能は？"]

  START --> Q1{"Expo SDK / 公開ライブラリで<br/>カバーできる？"}
  Q1 -->|"Yes"| MANAGED["Managed Workflow<br/>ネイティブコード不要<br/>npx expo start だけで完結"]
  Q1 -->|"No"| Q2{"Config Plugin で<br/>設定変更だけで済む？<br/>(Info.plist / AndroidManifest 追記など)"}
  Q2 -->|"Yes"| PLUGIN["Config Plugin 作成<br/>app.json に追記<br/>prebuild で自動適用"]
  Q2 -->|"No"| Q3{"独自ネイティブコードが<br/>必要な規模は？"}
  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["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 Renderer"]
  end

  subgraph NATIVE_IOS["iOS ネイティブ実装"]
    SWIFT["Swift / Obj-C 実装クラス<br/>(C++ 抽象クラスを継承)"]
    SDK_IOS["社内SDK / 外部.framework<br/>e.g. CoreBluetooth / Stripe"]
    UIVIEW["UIView サブクラス<br/>(カスタム UI コンポーネント)"]
  end

  subgraph NATIVE_AND["Android ネイティブ実装"]
    KOTLIN["Kotlin / Java 実装クラス<br/>(C++ 抽象クラスを継承)"]
    SDK_AND["社内SDK / 外部.aar<br/>e.g. 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 経由 or 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["動作確認 OK"]
  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 でストア向けバイナリ生成