React Native + Expo + Metro + Implémentation Native : Guide Complet

flowchart LR
  subgraph OLD["Ancienne Architecture (Bridge)"]
    direction TB
    J1["Thread JS<br/>Logique React"] -->|"Sérialisation JSON"| BR["Bridge<br/>File d'attente async ⚠"]
    BR -->|"Désérialisation JSON"| N1["Thread Natif<br/>UIKit / Android View"]
    SH["Thread Shadow<br/>Layout Yoga"] --> N1
  end
  subgraph NEW["Nouvelle Architecture (JSI)"]
    direction TB
    HM["Moteur Hermes<br/>Exécution bytecode"] -->|"Référence C++ directe"| JSI["JSI<br/>Host Objects"]
    JSI --> FAB["Fabric<br/>Rendu synchrone"]
    JSI --> TM["TurboModules<br/>Initialisation paresseuse"]
    FAB --> N2["Couche Native"]
    TM --> N2
  end

flowchart TD
  SPEC["Fichier JS Spec<br/>Définitions de types en TypeScript / Flow"]

  subgraph BUILD["Temps de Compilation"]
    CG["Codegen<br/>S'exécute lors du pod install / Gradle"]
  end

  subgraph OUT["Artefacts Générés"]
    CPP["Classes C++ Abstraites<br/>Interfaces de base TurboModule"]
    DESC["Component Descriptor<br/>Pour les composants natifs Fabric"]
    JSTYPE["Définitions de Types JS<br/>Équivalent .d.ts"]
  end

  subgraph NATIVE["Implémentation Native"]
    IOS["iOS<br/>Implémenté en Swift / Obj-C"]
    AND["Android<br/>Implémenté en Kotlin / Java"]
  end

  RUNTIME["Via JSI<br/>Type-safe, appels synchrones"]

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

flowchart LR
  SRC[".js / .ts / .tsx<br/>Fichiers source"]
  RES["Résolution<br/>Résolution des chemins d'import"]
  TRA["Transformation<br/>Transforms ES via Babel"]
  SER["Sérialisation<br/>Génération du bundle"]
  DEV["Livraison à l'appareil<br/>HTTP :8081"]
  HMR["HMR<br/>Renvoie only les modules modifiés"]
  CACHE["Cache FS<br/>Plus rapide dès le 2e lancement"]

  SRC --> RES --> TRA --> SER --> DEV
  TRA -.->|"Détection de changement"| HMR
  HMR -.->|"Reflète sans perdre le state"| DEV
  TRA <-.->|"Met en cache les résultats"| CACHE

flowchart TD
  APP["Votre App<br/>App.tsx / screens / hooks"]
  SDK["Expo SDK<br/>expo-camera / expo-location / expo-router …"]
  EMC["expo-modules-core<br/>DSL type-safe en Swift / Kotlin"]
  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/>Lancement immédiat par scan QR"]
  EASB["EAS Build<br/>Générer .ipa / .apk dans le cloud"]
  EASU["EAS Update<br/>Livrer uniquement le JS bundle via OTA"]
  STORE["App Store / Google Play"]

  APP --> SDK
  EMC --> SDK
  SDK --> RN
  RN --> IOS & AND
  GO -->|"Héberge en développement"| APP
  EASB --> STORE
  EASU -->|"Sans review App Store"| APP

flowchart TD
  START["Quelle fonctionnalité native vous faut-il ?"]

  START --> Q1{"Couverte par le SDK Expo<br/>ou une bibliothèque publique ?"}
  Q1 -->|"Oui"| MANAGED["Managed Workflow<br/>Pas de code natif nécessaire<br/>Juste npx expo start"]
  Q1 -->|"Non"| Q2{"Seulement des changements de config ?<br/>(Ajouts Info.plist / AndroidManifest)"}
  Q2 -->|"Oui"| PLUGIN["Créer un Config Plugin<br/>Ajouter à app.json<br/>Appliqué automatiquement par prebuild"]
  Q2 -->|"Non"| Q3{"Volume de code natif personnalisé ?"}
  Q3 -->|"Léger<br/>(wrapper d'un SDK existant)"| BARE["Bare Workflow<br/>npx expo prebuild<br/>→ Gérer ios/ android/ directement"]
  Q3 -->|"Complet<br/>(module / UI personnalisé)"| MODULE{"Qu'est-ce qui est construit ?"}
  MODULE -->|"Logique<br/>Bluetooth / paiement / crypto"| TM["TurboModule<br/>+ Codegen"]
  MODULE -->|"Composant UI<br/>Vue caméra personnalisée, etc."| FAB["Fabric Component<br/>+ Codegen"]
  BARE --> TM & FAB
  PLUGIN --> BARE

flowchart TB
  subgraph JS["Couche JS (Hermes)"]
    APP["Code App / Composants React"]
    SPEC["JS Spec<br/>(TypeScript + TurboModuleRegistry)"]
  end

  subgraph CODEGEN["Codegen (Auto-généré au moment de la compilation)"]
    GEN_CPP["Classes C++ Abstraites<br/>TurboModule / ComponentDescriptor"]
    GEN_SHADOW["Définitions ShadowNode / Props"]
  end

  subgraph JSI_LAYER["Couche JSI (C++)"]
    JSI["JSI Host Object"]
    FABRIC["Fabric Renderer"]
  end

  subgraph NATIVE_IOS["Implémentation Native iOS"]
    SWIFT["Implémentation Swift / Obj-C<br/>(Hérite de la classe C++ abstraite)"]
    SDK_IOS["SDK Interne / .framework Externe<br/>ex: CoreBluetooth / Stripe"]
    UIVIEW["Sous-classe UIView<br/>(Composant UI Personnalisé)"]
  end

  subgraph NATIVE_AND["Implémentation Native Android"]
    KOTLIN["Implémentation Kotlin / Java<br/>(Hérite de la classe C++ abstraite)"]
    SDK_AND["SDK Interne / .aar Externe<br/>ex: BluetoothGatt / Stripe"]
    ANDROIDVIEW["Sous-classe View<br/>(Composant UI Personnalisé)"]
  end

  SPEC -->|"Lire les définitions de types"| CODEGEN
  GEN_CPP --> JSI
  GEN_SHADOW --> FABRIC
  APP -->|"Appels sync / async"| 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/>(Écrit par le développeur)"]

  subgraph AUTO["Code auto-généré"]
    CPP["Code C++ glue<br/>Sortie JSI / Codegen"]
    IOS_H["Code iOS glue<br/>Sortie Obj-C++ / header"]
    AND_J["Code Android glue<br/>Sortie JNI / classe Spec"]
  end

  subgraph IMPL["Implémenté par le développeur"]
    SWIFT_IMPL["NativeBluetoothModule.swift<br/>Implémente la Spec générée, appelle CoreBluetooth"]
    KOTLIN_IMPL["NativeBluetoothModule.kt<br/>Implémente la Spec générée, appelle 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 convertit Float → CGFloat / float
  torchEnabled?: boolean;
  onFrameCaptured?: DirectEventHandler<FrameCapturedEvent>;
}

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

# ios/Podfile
pod 'CompanyPaymentSDK', :path => '../vendor/ios/CompanyPaymentSDK'
# ou pour xcframework
pod 'CompanyPaymentSDK', :podspec => '../vendor/ios/CompanyPaymentSDK.podspec'

// android/app/build.gradle
dependencies {
  implementation files('../vendor/android/company-payment-sdk.aar')
  // ou un dépôt Maven interne
  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 démarre<br/>port 8081"]
    QR["Code QR + raccourcis<br/>i = iOS  a = Android  w = Web"]
  end

  subgraph DEVICE["Choisir la cible"]
    SIM["iOS Simulator<br/>Inclus avec Xcode (Mac uniquement)"]
    EMU["Android Emulator<br/>Android Studio AVD"]
    GO["Appareil physique + Expo Go<br/>Via LAN ou Tunnel"]
  end

  subgraph NATIVE_BUILD["Première fois seulement : Build Natif"]
    POD["pod install<br/>iOS CocoaPods"]
    GRADLE["Gradle build<br/>Android"]
    CODEGEN_RUN["Codegen s'exécute<br/>Spec → Échafaudage natif"]
  end

  BUNDLE["Transférer le JS bundle à l'appareil<br/>via le serveur HTTP Metro"]
  RENDER["L'écran s'affiche"]

  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["Branchement par type de changement"]
    JS_ONLY["Changements JS uniquement<br/>Composants / logique / styles"]
    NATIVE_CHANGE["Changements de code natif<br/>Swift / Kotlin / Spec / Podfile"]
  end

  subgraph JS_LOOP["Boucle de Changement JS (Rapide)"]
    METRO_HMR["Metro HMR<br/>Transférer le bundle différentiel<br/>~Centaines de ms"]
    SIM_JS["Visible immédiatement dans l'émulateur<br/>État de l'app préservé"]
  end

  subgraph NATIVE_LOOP["Boucle de Changement Natif (Lent)"]
    CODEGEN_RUN["Re-exécuter Codegen<br/>pod install (iOS)<br/>Gradle sync (Android)"]
    REBUILD["Rebuild natif<br/>npx expo run:ios<br/>npx expo run:android"]
    SIM_NATIVE["Vérifier sur émulateur / appareil"]
  end

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

  SIM_JS -->|"Pas de problème"| DONE["Vérification OK"]
  SIM_NATIVE -->|"Pas de problème"| DONE
  SIM_JS -->|"Bug trouvé"| DEBUG_JS["Hermes Debugger<br/>React DevTools"]
  SIM_NATIVE -->|"Crash natif"| DEBUG_NATIVE["Xcode / Android Studio<br/>Débogueur natif"]
  DEBUG_JS --> JS_ONLY
  DEBUG_NATIVE --> NATIVE_CHANGE

flowchart TD
  SYMPTOM["Observer les symptômes"]

  SYMPTOM --> Q1{"Type de crash"}

  Q1 -->|"Erreur JS<br/>Écran rouge LogBox"| JS_ERR["Investiguer avec Hermes Debugger<br/>Breakpoints, stack trace<br/>Numéros de ligne TS via Source Map"]
  Q1 -->|"Crash natif<br/>L'app freeze / crash"| NAT_ERR["Vérifier les logs de crash"]
  Q1 -->|"Fonctionne mais<br/>mauvais résultat"| BORDER["Suspecter la frontière JS↔Natif"]

  NAT_ERR --> IOS_CRASH["iOS: Xcode<br/>Debug Navigator<br/>+ attacher lldb"]
  NAT_ERR --> AND_CRASH["Android: Android Studio<br/>Stack trace 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["Côté JS: console.log<br/>Vérifier les valeurs de retour TurboModule"]

  IOS_CRASH --> INSTRUMENTS["Instruments<br/>Time Profiler / Allocations<br/>Identifier fuites mémoire / CPU"]
  AND_CRASH --> PROFILER["Android Studio<br/>Memory / CPU Profiler"]

  JS_ERR --> FIXED["Corriger → Visible via Metro HMR"]
  INSTRUMENTS --> FIXED2["Corriger → Vérifier avec npx expo run:ios"]
  PROFILER --> FIXED3["Corriger → Vérifier avec npx expo run:android"]
  LOG_IOS & LOG_AND & JS_LOG --> BORDER2["Identifier la cause racine<br/>→ Corriger Spec / implémentation"]

# iOS: Attacher lldb au simulateur en cours
npx expo run:ios --configuration Debug
# → Xcode s'ouvre automatiquement et attache le débogueur

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

// Côté Swift
os_log("BluetoothModule.connect called: %{public}@", deviceId)
// → Filtrer avec npx react-native log-ios

// Côté Kotlin
Log.d("BluetoothModule", "connect called: $deviceId")
// → Filtrer avec npx react-native log-android

// Côté JS
const result = await BluetoothModule.connect(deviceId);
console.log('connect result:', result); // Sortie dans Metro

npx react-devtools
# → Attend la connexion de l'appareil sur le port 8097

① Écrire la JS Spec (définitions de types en TypeScript)
       ↓
② pod install / gradle build → Codegen auto-génère l'échafaudage C++
       ↓
③ Implémenter en Swift / Kotlin (appeler SDK interne / bibliothèques externes)
       ↓
④ npx expo run:ios / run:android → Build natif & vérification émulateur
       ↓
⑤ Écrire le code d'appel JS → Itération rapide via Metro HMR
       ↓
⑥ Erreurs JS → Hermes Debugger
   Crashes natifs → Débogueur Xcode / Android Studio
   Discordances de frontière → Encadrer avec log-ios / log-android + console.log
       ↓
⑦ Vérifier Bluetooth / caméra / capteurs sur appareils physiques
       ↓
⑧ EAS Build génère les binaires prêts pour les stores