React Native + Expo + Metro + Native-Implementierung: Eine vollständige Anleitung

flowchart LR
  subgraph OLD["Alte Architektur (Bridge)"]
    direction TB
    J1["JS-Thread<br/>React-Logik"] -->|"JSON serialisieren"| BR["Bridge<br/>Asynchrone Warteschlange ⚠"]
    BR -->|"JSON deserialisieren"| N1["Nativer Thread<br/>UIKit / Android View"]
    SH["Shadow-Thread<br/>Yoga-Layout"] --> N1
  end
  subgraph NEW["Neue Architektur (JSI)"]
    direction TB
    HM["Hermes-Engine<br/>Bytecode-Ausführung"] -->|"Direkter C++-Verweis"| JSI["JSI<br/>Host Objects"]
    JSI --> FAB["Fabric<br/>Synchroner Renderer"]
    JSI --> TM["TurboModules<br/>Verzögerte Initialisierung"]
    FAB --> N2["Native Schicht"]
    TM --> N2
  end

flowchart TD
  SPEC["JS-Spec-Datei<br/>Typdefinitionen in TypeScript / Flow"]

  subgraph BUILD["Build-Zeit"]
    CG["Codegen<br/>Läuft bei pod install / Gradle"]
  end

  subgraph OUT["Generierte Artefakte"]
    CPP["Abstrakte C++-Klassen<br/>TurboModule-Basisschnittstellen"]
    DESC["Component Descriptor<br/>Für Fabric-native Komponenten"]
    JSTYPE["JS-Typdefinitionen<br/>.d.ts-Äquivalent"]
  end

  subgraph NATIVE["Native Implementierung"]
    IOS["iOS<br/>Implementiert in Swift / Obj-C"]
    AND["Android<br/>Implementiert in Kotlin / Java"]
  end

  RUNTIME["Über JSI<br/>Typsicher, synchrone Aufrufe"]

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

flowchart LR
  SRC[".js / .ts / .tsx<br/>Quelldateien"]
  RES["Auflösung<br/>Import-Pfad-Auflösung"]
  TRA["Transformation<br/>ES-Transforms via Babel"]
  SER["Serialisierung<br/>Bundle-Generierung"]
  DEV["Auslieferung ans Gerät<br/>HTTP :8081"]
  HMR["HMR<br/>Nur geänderte Module neu senden"]
  CACHE["FS-Cache<br/>Ab dem 2. Lauf schneller"]

  SRC --> RES --> TRA --> SER --> DEV
  TRA -.->|"Dateiänderung erkannt"| HMR
  HMR -.->|"Ohne State-Verlust reflektieren"| DEV
  TRA <-.->|"Transformierte Ergebnisse cachen"| CACHE

flowchart TD
  APP["Ihre App<br/>App.tsx / screens / hooks"]
  SDK["Expo SDK<br/>expo-camera / expo-location / expo-router …"]
  EMC["expo-modules-core<br/>Typsicheres DSL in 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/>Sofort per QR-Scan starten"]
  EASB["EAS Build<br/>.ipa / .apk in der Cloud generieren"]
  EASU["EAS Update<br/>Nur JS-Bundle per OTA ausliefern"]
  STORE["App Store / Google Play"]

  APP --> SDK
  EMC --> SDK
  SDK --> RN
  RN --> IOS & AND
  GO -->|"Während der Entwicklung hosten"| APP
  EASB --> STORE
  EASU -->|"Ohne App-Store-Review"| APP

flowchart TD
  START["Welche native Funktion brauchen Sie?"]

  START --> Q1{"Durch Expo SDK /<br/>öffentliche Bibliothek abgedeckt?"}
  Q1 -->|"Ja"| MANAGED["Managed Workflow<br/>Kein nativer Code nötig<br/>Nur npx expo start"]
  Q1 -->|"Nein"| Q2{"Nur Konfigurationsänderungen nötig?<br/>(Info.plist / AndroidManifest-Ergänzungen)"}
  Q2 -->|"Ja"| PLUGIN["Config Plugin erstellen<br/>In app.json eintragen<br/>Automatisch per prebuild angewendet"]
  Q2 -->|"Nein"| Q3{"Umfang des nativen Codes?"}
  Q3 -->|"Leichtgewichtig<br/>(vorhandenes SDK wrappen)"| BARE["Bare Workflow<br/>npx expo prebuild<br/>→ ios/ android/ direkt verwalten"]
  Q3 -->|"Umfangreich<br/>(eigenes Modul / UI)"| MODULE{"Was wird gebaut?"}
  MODULE -->|"Logik<br/>Bluetooth / Payment / Krypto"| TM["TurboModule<br/>+ Codegen"]
  MODULE -->|"UI-Komponente<br/>Benutzerdefinierte Kamera-View"| FAB["Fabric Component<br/>+ Codegen"]
  BARE --> TM & FAB
  PLUGIN --> BARE

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

  subgraph CODEGEN["Codegen (Automatisch zur Build-Zeit generiert)"]
    GEN_CPP["Abstrakte C++-Klassen<br/>TurboModule / ComponentDescriptor"]
    GEN_SHADOW["ShadowNode / Props-Definitionen"]
  end

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

  subgraph NATIVE_IOS["iOS Native Implementierung"]
    SWIFT["Swift / Obj-C Implementierung<br/>(Erbt abstrakte C++-Klasse)"]
    SDK_IOS["Internes SDK / Externes .framework<br/>z.B. CoreBluetooth / Stripe"]
    UIVIEW["UIView-Unterklasse<br/>(Benutzerdefinierte UI-Komponente)"]
  end

  subgraph NATIVE_AND["Android Native Implementierung"]
    KOTLIN["Kotlin / Java Implementierung<br/>(Erbt abstrakte C++-Klasse)"]
    SDK_AND["Internes SDK / Externes .aar<br/>z.B. BluetoothGatt / Stripe"]
    ANDROIDVIEW["View-Unterklasse<br/>(Benutzerdefinierte UI-Komponente)"]
  end

  SPEC -->|"Typdefinitionen lesen"| CODEGEN
  GEN_CPP --> JSI
  GEN_SHADOW --> FABRIC
  APP -->|"Synchrone / asynchrone Aufrufe"| 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/>(Vom Entwickler geschrieben)"]

  subgraph AUTO["Automatisch generierter Code"]
    CPP["C++ Glue Code<br/>JSI / Codegen-Ausgabe"]
    IOS_H["iOS Glue Code<br/>Obj-C++ / Header-Ausgabe"]
    AND_J["Android Glue Code<br/>JNI / Spec-Klassen-Ausgabe"]
  end

  subgraph IMPL["Vom Entwickler implementiert"]
    SWIFT_IMPL["NativeBluetoothModule.swift<br/>Implementiert generierte Spec, ruft CoreBluetooth auf"]
    KOTLIN_IMPL["NativeBluetoothModule.kt<br/>Implementiert generierte Spec, ruft BluetoothGatt auf"]
  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 konvertiert Float → CGFloat / float
  torchEnabled?: boolean;
  onFrameCaptured?: DirectEventHandler<FrameCapturedEvent>;
}

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

# ios/Podfile
pod 'CompanyPaymentSDK', :path => '../vendor/ios/CompanyPaymentSDK'
# oder für xcframework
pod 'CompanyPaymentSDK', :podspec => '../vendor/ios/CompanyPaymentSDK.podspec'

// android/app/build.gradle
dependencies {
  implementation files('../vendor/android/company-payment-sdk.aar')
  // oder ein internes Maven-Repository
  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 startet<br/>Port 8081"]
    QR["QR-Code + Shortcuts<br/>i = iOS  a = Android  w = Web"]
  end

  subgraph DEVICE["Zielgerät wählen"]
    SIM["iOS Simulator<br/>In Xcode enthalten (nur Mac)"]
    EMU["Android Emulator<br/>Android Studio AVD"]
    GO["Physisches Gerät + Expo Go<br/>Über LAN oder Tunnel"]
  end

  subgraph NATIVE_BUILD["Nur beim ersten Mal: Nativer Build"]
    POD["pod install<br/>iOS CocoaPods"]
    GRADLE["Gradle Build<br/>Android"]
    CODEGEN_RUN["Codegen läuft<br/>Spec → Natives Gerüst"]
  end

  BUNDLE["JS Bundle ans Gerät übertragen<br/>über Metro HTTP-Server"]
  RENDER["Bildschirm wird angezeigt"]

  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["Verzweigung nach Änderungstyp"]
    JS_ONLY["Nur JS-Änderungen<br/>Komponenten / Logik / Styles"]
    NATIVE_CHANGE["Native Code-Änderungen<br/>Swift / Kotlin / Spec / Podfile"]
  end

  subgraph JS_LOOP["JS-Änderungsschleife (Schnell)"]
    METRO_HMR["Metro HMR<br/>Differenz-Bundle übertragen<br/>~Hunderte ms"]
    SIM_JS["Sofort im Emulator sichtbar<br/>App-Zustand erhalten"]
  end

  subgraph NATIVE_LOOP["Native Änderungsschleife (Langsam)"]
    CODEGEN_RUN["Codegen erneut ausführen<br/>pod install (iOS)<br/>Gradle sync (Android)"]
    REBUILD["Nativer Rebuild<br/>npx expo run:ios<br/>npx expo run:android"]
    SIM_NATIVE["Auf Emulator / Gerät überprüfen"]
  end

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

  SIM_JS -->|"Keine Probleme"| DONE["Verifikation OK"]
  SIM_NATIVE -->|"Keine Probleme"| DONE
  SIM_JS -->|"Fehler gefunden"| DEBUG_JS["Hermes Debugger<br/>React DevTools"]
  SIM_NATIVE -->|"Nativer Crash"| DEBUG_NATIVE["Xcode / Android Studio<br/>Nativer Debugger"]
  DEBUG_JS --> JS_ONLY
  DEBUG_NATIVE --> NATIVE_CHANGE

flowchart TD
  SYMPTOM["Symptome beobachten"]

  SYMPTOM --> Q1{"Art des Crashes"}

  Q1 -->|"JS-Fehler<br/>LogBox-Rotbildschirm"| JS_ERR["Mit Hermes Debugger untersuchen<br/>Breakpoints, Stack Trace<br/>TS-Zeilennummern via Source Map"]
  Q1 -->|"Nativer Crash<br/>App friert ein / stürzt ab"| NAT_ERR["Crash-Logs prüfen"]
  Q1 -->|"Läuft, aber<br/>falsches Ergebnis"| BORDER["JS↔Native-Grenze verdächtig"]

  NAT_ERR --> IOS_CRASH["iOS: Xcode<br/>Debug Navigator<br/>+ lldb anhängen"]
  NAT_ERR --> AND_CRASH["Android: Android Studio<br/>Logcat Stack Trace<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-Seite: console.log<br/>TurboModule-Rückgabewerte prüfen"]

  IOS_CRASH --> INSTRUMENTS["Instruments<br/>Time Profiler / Allocations<br/>Speicherlecks / CPU identifizieren"]
  AND_CRASH --> PROFILER["Android Studio<br/>Memory / CPU Profiler"]

  JS_ERR --> FIXED["Beheben → Sofort via Metro HMR sichtbar"]
  INSTRUMENTS --> FIXED2["Beheben → Mit npx expo run:ios prüfen"]
  PROFILER --> FIXED3["Beheben → Mit npx expo run:android prüfen"]
  LOG_IOS & LOG_AND & JS_LOG --> BORDER2["Ursache identifizieren<br/>→ Spec / Implementierung beheben"]

# iOS: lldb an laufenden Simulator anhängen
npx expo run:ios --configuration Debug
# → Xcode öffnet sich automatisch und hängt den Debugger an

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

// Swift-Seite
os_log("BluetoothModule.connect called: %{public}@", deviceId)
// → Mit npx react-native log-ios filtern

// Kotlin-Seite
Log.d("BluetoothModule", "connect called: $deviceId")
// → Mit npx react-native log-android filtern

// JS-Seite
const result = await BluetoothModule.connect(deviceId);
console.log('connect result:', result); // Ausgabe in Metro

npx react-devtools
# → Wartet auf Geräteverbindung auf Port 8097

① JS Spec schreiben (Typdefinitionen in TypeScript)
       ↓
② pod install / gradle build → Codegen generiert automatisch C++-Gerüst
       ↓
③ In Swift / Kotlin implementieren (internes SDK / externe Bibliotheken aufrufen)
       ↓
④ npx expo run:ios / run:android → Nativer Build & Emulator-Verifikation
       ↓
⑤ JS-Aufrufcode schreiben → Schnelle Iteration via Metro HMR
       ↓
⑥ JS-Fehler → Hermes Debugger
   Native Crashes → Xcode / Android Studio Debugger
   Grenz-Diskrepanzen → Mit log-ios / log-android + console.log einrahmen
       ↓
⑦ Bluetooth / Kamera / Sensoren auf physischen Geräten verifizieren
       ↓
⑧ EAS Build generiert Store-fertige Binaries