Codegen: Was es ist, Codegenerierung und Fabric-Architektur

Was ist Codegen?

Codegen (Kurzform von Code Generator) ist ein Befehlszeilentool, das in React Native enthalten ist und automatisch Brückencode für die Interaktion zwischen JavaScript und nativen Plattformen (iOS, Android) generiert. Codegen ist ein integraler Bestandteil der neuen React Native-Architektur und wird sowohl für Fabric (Renderer) als auch für TurboModules (native Module) verwendet.

Die Hauptidee von Codegen ist die Trennung von Verantwortlichkeiten: Der Entwickler beschreibt „was" eine Funktion tun soll (ihre Signatur), und Codegen generiert „wie" sie an die native Seite übergeben wird. Dies macht die manuelle Erstellung von C++-Wrappern für JSI, Objective-C-Stubs für iOS und Java-Klassen für Android überflüssig. Eine einzige Quelle der Wahrheit — die TypeScript-Spezifikation — stellt sicher, dass die Typen auf allen Ebenen übereinstimmen, wodurch eine ganze Klasse von Fehlern im Zusammenhang mit Typenkonflikten zwischen JS und nativem Code beseitigt wird.

Codegen wurde mit der ersten stabilen Version der neuen React Native-Architektur (0.70+) eingeführt und ist seitdem ein obligatorisches Werkzeug für die Erstellung nativer Module. Ohne Codegen müssten Entwickler JSI Host Objects manuell schreiben, was tiefgehende Kenntnisse von C++ und Verständnis der inneren Struktur von JavaScript-Engines erfordert.

Evolution: Von der manuellen Brücke zur automatischen Generierung

Vor Codegen umfasste die Entwicklung eines nativen Moduls für React Native drei Schritte: Schreiben einer JavaScript-Schnittstelle, Implementieren des nativen Moduls in Java/Objective-C und manuelles Schreiben der Brücke. Bei einer Änderung der Methodensignatur mussten alle drei Dateien synchron aktualisiert werden. Codegen automatisiert diese Routine: Änderungen werden nur an der TypeScript-Spezifikation vorgenommen, alles andere wird neu generiert.

Integration mit dem Build-System

Codegen integriert sich über Metro und CocoaPods in den React Native-Build-Prozess. Beim Starten des Builds analysiert Codegen die TypeScript-Spezifikationen, generiert C++- und Plattformdateien und legt sie im Build-Verzeichnis ab. Das bedeutet, dass der generierte Code immer den aktuellen Spezifikationen entspricht und keine manuellen Aktualisierungen erforderlich sind.

Wie funktioniert Codegen?

Der Codegen-Workflow besteht aus drei Phasen: Parsen der Spezifikationen, Erstellen einer Zwischendarstellung und Generieren der Zieldateien. Jede Phase ist isoliert, was das Hinzufügen von Unterstützung für neue Plattformen oder Generierungssprachen erleichtert.

In der ersten Phase liest Codegen Spezifikationsdateien im TypeScript- oder Flow-Format. Die Spezifikation beschreibt die native Modulschnittstelle: Methodennamen, Parametertypen und Rückgabetypen. Codegen unterstützt primitive Typen (number, string, boolean) sowie komplexe Typen — Objekte, Arrays, Promise und Callback. Die Spezifikationen werden in .ts- oder .js-Dateien in einem speziellen Projektverzeichnis gespeichert.

In der zweiten Phase erstellt Codegen einen abstrakten Syntaxbaum (AST) aus den geparsten Spezifikationen. Der AST stellt die Datenstruktur in einem neutralen Format dar, das an keine bestimmte Generierungssprache gebunden ist. Dies ermöglicht die Generierung von C++-Code für Fabric, Objective-C für iOS und Java für Android aus einem einzigen AST — es ist keine zusätzliche Arbeit erforderlich, um alle Plattformen zu unterstützen.

In der dritten Phase verwendet Codegen eine Template-Engine (basierend auf Mustache) zum Generieren der Zieldateien. Jede Vorlage ist für einen bestimmten Dateityp verantwortlich: C++-Header (.h), Implementierung (.cpp), Objective-C-Protokoll (.h) oder Implementierung (.mm), Java-Klasse. Die Vorlagen werden mit React Native geliefert, können aber für spezifische Projektanforderungen angepasst werden.

Codegen-Workflow-Diagramm

// NativeCalculator.ts — native module specification
import { TurboModule, TurboModuleRegistry } from 'react-native'
import { Double } from 'react-native/Libraries/Types/CodegenTypes'

export interface NativeCalculatorSpec extends TurboModule {
    add(a: Double, b: Double): Double
    multiply(a: Double, b: Double): Double
}

export default TurboModuleRegistry.<NativeCalculatorSpec>('NativeCalculator')

In diesem Beispiel beschreibt die Spezifikation das NativeCalculator-Modul mit zwei Methoden: add und multiply. Beide akzeptieren Double und geben Double zurück. Die Zeichenfolge 'NativeCalculator' in TurboModuleRegistry gibt den Modulnamen an, der auf der nativen Seite verwendet wird. Codegen wird basierend auf dieser Spezifikation alle erforderlichen Dateien für Fabric und TurboModules generieren.

Codegen in der Fabric-Architektur

Im Kontext von Fabric (dem neuen React Native-Renderer) spielt Codegen eine besondere Rolle. Fabric erfordert, dass jede native UI-Komponente eine C++-Darstellung hat, die über JSI erstellt und verwaltet werden kann. Codegen generiert diese C++-Darstellungen automatisch basierend auf den Komponentenspezifikationen.

Generierung für UI-Komponenten

Für UI-Komponenten generiert Codegen nicht nur die C++-Shadow-Node-Klasse, sondern auch plattformspezifische Darstellungen. Für eine benutzerdefinierte Button-Komponente auf iOS erstellt Codegen beispielsweise eine Objective-C-Klasse, die die Komponente in Fabric registriert und mit der C++-Shadow-Node verbindet. Der Entwickler muss nur die Komponenteneigenschaften (Farbe, Größe, Handler) in der TypeScript-Spezifikation beschreiben.

Eigenschaftstypisierung

Codegen unterstützt sowohl direkte als auch umgekehrte Datenübertragung. Direkte Ereignisse (z. B. onPress) werden als C++-Strukturen mit Feldern generiert, die bei der Übergabe an JS automatisch serialisiert werden. EventEmitter ermöglicht es der nativen Seite, Ereignisse an JS zu senden, ohne dass eine Anfrage von JS erforderlich ist. Codegen generiert typisierte Wrapper für beide Richtungen und beseitigt Fehler durch Feldnamenkonflikte.

Codegen für Drittanbieter-Bibliotheken

Bibliotheksentwickler können Codegen-Spezifikationen mit ihrem npm-Paket bereitstellen. Bei der Installation der Bibliothek erkennt Codegen automatisch die Spezifikationen und generiert Brückencode für die aktuelle Plattform. Dies ist besonders wichtig für native Bibliotheken, da die Bibliotheksnutzer C++, Objective-C oder Java nicht verstehen müssen — sie importieren einfach TypeScript-Typen und verwenden die fertigen Komponenten.

Welche Dateien generiert Codegen?

Codegen generiert Dateien für drei Zielumgebungen: C++ (JSI), Objective-C (iOS) und Java (Android). Jede Datei hat eine streng definierte Rolle und Struktur. Zu verstehen, welche Dateien erstellt werden, hilft bei der Fehlersuche und gegebenenfalls bei der manuellen Anpassung des generierten Codes.

C++-Dateien (JSI)

Für jedes native Modul erstellt Codegen zwei C++-Dateien: eine Header-Datei (.h) mit der Deklaration der Host-Object-Klasse und eine Implementierungsdatei (.cpp) mit Methoden, die die entsprechenden Funktionen auf der Plattform aufrufen. Die Header-Datei enthält eine von jsi::HostObject abgeleitete Klasse mit einer überschriebenen get-Methode für den Zugriff auf Modulfunktionen. Die Implementierungsdatei enthält Lambda-Funktionen, die bei Aufruf von JS die Ausführung an das native Modul delegieren.

iOS-Dateien (Objective-C)

Für iOS generiert Codegen ein Objective-C-Protokoll und eine Kategorie. Das Protokoll deklariert Methoden, die vom nativen Modul implementiert werden müssen. Die Kategorie auf RCTCxxBridge enthält Brückencode, der das Modul im RCTTurboModuleManager registriert. Dies ermöglicht es, Objective-C-Modulmethoden von C++ JSI über den Standard-RCTBridge-Mechanismus aufzurufen.

Android-Dateien (Java)

Für Android generiert Codegen ein Java-Interface und eine abstrakte Klasse. Das Interface enthält Methodendeklarationen mit korrekten Java-Typen. Die abstrakte Klasse implementiert das TurboModule-Interface und enthält die grundlegende Logik zur Registrierung des Moduls im ReactPackage. Der Entwickler erbt von dieser Klasse und implementiert nur die Geschäftslogik der Methoden.

Struktur der generierten Dateien

// Directory structure after Codegen run
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protocol
            NativeCalculatorSpec.mm    // JSI implementation
        android/
            NativeCalculatorSpec.java  // Java interface
            NativeCalculatorModuleBase.java  // Base class
        cxx/
            NativeCalculator.h         // C++ Host Object header
            NativeCalculator.cpp        // C++ JSI implementation

Diese gesamte Struktur wird beim Projektbuild automatisch erstellt. Entwickler sollten die generierten Dateien nicht bearbeiten — sie werden beim nächsten Build überschrieben. Wenn eine Änderung des Modulverhaltens erforderlich ist, werden Änderungen nur am nativen Implementierungsquellcode (Java/Objective-C) oder an der TypeScript-Spezifikation vorgenommen.

Beispiele für den Codegen-Workflow

Gehen wir den vollständigen Codegen-Workflow durch, indem wir ein natives Modul zum Speichern von Daten in Keychain erstellen. Dies ist eine typische Aufgabe, die Zugriff auf die native iOS- und Android-API erfordert.

Schritt 1: Spezifikation

Der Entwickler erstellt eine Spezifikationsdatei, die die KeychainStorage-Modulschnittstelle beschreibt. Die Methoden save und read akzeptieren einen String und geben ein Promise zurück, da die Arbeit mit Keychain auf einigen Plattformen asynchron sein kann.

import { TurboModule, TurboModuleRegistry } from 'react-native'

export interface KeychainStorageSpec extends TurboModule {
    save(key: string, value: string): Promise<void>
    read(key: string): Promise<string | null>
    delete(key: string): Promise<boolean>
}

export default TurboModuleRegistry.<KeychainStorageSpec>('KeychainStorage')

Schritt 2: Codegen ausführen

Codegen wird beim Build eines React Native-Projekts automatisch ausgeführt. Wenn eine manuelle Ausführung erforderlich ist, wird der Befehl npx react-native codegen verwendet. Codegen parst die Spezifikation und erstellt alle erforderlichen Dateien in build/generated/. Der Entwickler sieht die generierten C++-, Objective-C- und Java-Dateien, sollte sie aber nicht bearbeiten.

# Run Codegen manually
npx react-native codegen --target-path ./build/generated

# After generation — build the project
npx react-native run-ios
npx react-native run-android

Schritt 3: Verwendung in JS

Nach Generierung und Build importiert der Entwickler das Modul als normalen TypeScript-Typ. Die IDE schlägt dank der generierten .d.ts-Dateien automatisch Methodensignaturen vor. TypeScript garantiert, dass Parameter- und Rückgabetypen mit der nativen Implementierung übereinstimmen — wenn die Spezifikation string angibt, erhält die native Seite genau einen String.

import KeychainStorage from './NativeKeychainStorage'

async function storeToken(token: string) {
    await KeychainStorage.save('auth_token', token)
}

async function getToken(): Promise<string | null> {
    return KeychainStorage.read('auth_token')
}

Dieses Beispiel zeigt, dass der JS-Code keine plattformspezifischen Anweisungen enthält — er ist für iOS und Android identisch. Alle plattformspezifischen Details sind im Codegen-generierten Code verborgen. Codegen übernimmt die gesamte Routinearbeit der Brückenerstellung und lässt dem Entwickler nur die Geschäftslogik und die Typprüfung durch TypeScript.