Codegen: wat is het, codegeneratie en architectuur van Fabric

Wat is Codegen?

Codegen (afkorting van Code Generator) is een commandoregelhulpprogramma dat deel uitmaakt van React Native en automatisch de verbindende code genereert voor communicatie tussen JavaScript en native platforms (iOS, Android). Codegen is een integraal onderdeel van de nieuwe React Native architectuur en wordt gebruikt voor zowel Fabric (renderer) als TurboModules (native modules).

Het belangrijkste idee van Codegen is de scheiding van verantwoordelijkheden: de ontwikkelaar beschrijft „wat” de functie moet doen (de signatuur), en Codegen genereert „hoe” dit naar de native kant wordt overgebracht. Dit elimineert de noodzaak om handmatig C++ verbindingen voor JSI, Objective-C stubs voor iOS en Java klassen voor Android te schrijven. Eén enkele bron van waarheid — de TypeScript-specificatie — garandeert dat de types op alle niveaus overeenkomen, wat een hele klasse fouten elimineert die verband houden met type-mismatches tussen JS en native code.

Codegen werd geïntroduceerd samen met de eerste stabiele versie van de nieuwe React Native architectuur (0.70+) en is sindsdien een verplichte tool geworden voor het maken van native modules. Zonder Codegen zou de ontwikkelaar handmatig JSI Host Objects moeten schrijven, wat diepgaande kennis van C++ en begrip van de interne werking van JavaScript-engines vereist.

Evolutie: van handmatige brug naar automatische generatie

Vóór de komst van Codegen omvatte de ontwikkeling van een native module voor React Native drie stappen: het schrijven van de JavaScript-interface, het implementeren van de native module in Java/Objective-C en het handmatig schrijven van de brug. Bij het wijzigen van een methodesignatuur moesten alle drie bestanden synchroon worden bijgewerkt. Codegen automatiseert deze routine: wijzigingen worden alleen in de TypeScript-specificatie aangebracht en de rest wordt opnieuw gegenereerd.

Integratie met het buildsysteem

Codegen integreert in het buildproces van React Native via Metro en CocoaPods. Bij het starten van de build analyseert Codegen de TypeScript-specificaties, genereert C++ en platformbestanden en plaatst ze in de build-directory. Dit betekent dat de gegenereerde code altijd overeenkomt met de huidige specificaties en geen handmatige update vereist.

Hoe werkt Codegen?

Het werkproces van Codegen bestaat uit drie fasen: het parsen van specificaties, het bouwen van een tussentijdse representatie en het genereren van doelbestanden. Elke fase is geïsoleerd, waardoor eenvoudig ondersteuning voor nieuwe platforms of generatietalen kan worden toegevoegd.

In de eerste fase leest Codegen de specificatiebestanden in TypeScript- of Flow-formaat. De specificatie beschrijft de interface van de native module: methodenamen, parametertypes en retourwaarden. Codegen ondersteunt primitieve types (number, string, boolean) en complexe types — objecten, arrays, Promise en Callback. Specificaties worden opgeslagen in bestanden met de extensie .ts of .js in een speciale directory van het project.

In de tweede fase bouwt Codegen een abstracte syntaxisboom (AST) uit de gelezen specificaties. De AST vertegenwoordigt de gegevensstructuur in een neutraal formaat, niet gebonden aan een specifieke generatietaal. Dit maakt het mogelijk om C++-code voor Fabric, Objective-C voor iOS en Java voor Android te genereren vanuit één AST — er is geen extra werk nodig om alle platforms te ondersteunen.

In de derde fase gebruikt Codegen een templatesysteem (gebaseerd op Mustache) voor het genereren van bestanden van de doelplatforms. Elke template is verantwoordelijk voor een specifiek bestandstype: C++ headerbestand (.h), implementatie (.cpp), Objective-C protocol (.h) of implementatie (.mm), Java klasse. Templates worden meegeleverd met React Native, maar kunnen worden aangepast voor specifieke projectbehoeften.

Werkschema van Codegen

// NativeCalculator.ts — specificatie van native module
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 dit voorbeeld beschrijft de specificatie de module NativeCalculator met twee methoden: add en multiply. Beide ontvangen Double en retourneren Double. De tekenreeks 'NativeCalculator' in TurboModuleRegistry geeft de modulenaam aan die aan de native kant wordt gebruikt. Codegen zal op basis van deze specificatie alle benodigde bestanden voor Fabric en TurboModules genereren.

Codegen in de Fabric architectuur

In de context van Fabric (de nieuwe React Native renderer) speelt Codegen een bijzondere rol. Fabric vereist dat elke native UI-component een C++-representatie heeft die kan worden gemaakt en beheerd via JSI. Codegen genereert deze C++-representaties automatisch op basis van componentspecificaties.

Generatie voor UI-componenten

Voor UI-componenten genereert Codegen niet alleen de C++ Shadow Node klasse, maar ook platformrepresentaties. Bijvoorbeeld, voor een aangepaste Button component op iOS zal Codegen een Objective-C klasse maken die de component registreert in Fabric en deze verbindt met de C++ Shadow Node. De ontwikkelaar hoeft alleen de eigenschappen van de component (kleur, grootte, handlers) in de TypeScript-specificatie te beschrijven.

Typering van eigenschappen

Codegen ondersteunt directe en omgekeerde gegevensoverdracht. Direct Event (bijv. onPress) worden gegenereerd als C++-structuren met velden die automatisch worden geserialiseerd bij overdracht naar JS. EventEmitter stelt de native kant in staat om gebeurtenissen naar JS te sturen zonder een verzoek van JS. Codegen genereert getypeerde wrappers voor beide richtingen, waardoor fouten door niet-overeenkomende veldnamen worden geëlimineerd.

Codegen voor bibliotheken van derden

Bibliotheekontwikkelaars kunnen Codegen-specificaties samen met het npm-pakket leveren. Bij installatie van de bibliotheek detecteert Codegen automatisch de specificaties en genereert de verbindende code voor het huidige platform. Dit is vooral belangrijk voor native bibliotheken, omdat de gebruiker van de bibliotheek geen C++, Objective-C of Java hoeft te kennen — het importeren van TypeScript-types en het gebruiken van kant-en-klare componenten is voldoende.

Welke bestanden genereert Codegen?

Codegen genereert bestanden voor drie doelomgevingen: C++ (JSI), Objective-C (iOS) en Java (Android). Elk bestand heeft een strikt gedefinieerde rol en structuur. Begrijpen welke bestanden worden gemaakt, helpt bij het debuggen en, indien nodig, handmatige correctie van de gegenereerde code.

C++ bestanden (JSI)

Voor elke native module maakt Codegen twee C++ bestanden: een headerbestand (.h) met de declaratie van de Host Object klasse en een implementatiebestand (.cpp) met methoden die de bijbehorende functies op het platform aanroepen. Het headerbestand bevat een klasse die overerft van jsi::HostObject met een overschreven get-methode voor toegang tot de functies van de module. Het implementatiebestand bevat lambda-functies die bij aanroep vanuit JS de uitvoering delegeren aan de native module.

iOS bestanden (Objective-C)

Voor iOS genereert Codegen een Objective-C protocol en een categorie. Het protocol declareert de methoden die door de native module moeten worden geïmplementeerd. De categorie op RCTCxxBridge bevat de verbindende code die de module registreert in de RCTTurboModuleManager. Dit maakt het mogelijk om methoden van de Objective-C module vanuit C++ JSI aan te roepen via het standaard RCTBridge mechanisme.

Android bestanden (Java)

Voor Android genereert Codegen een Java-interface en een abstracte klasse. De interface bevat declaraties van de modulemethoden met de juiste Java-types. De abstracte klasse implementeert de TurboModule interface en bevat de basale logica voor het registreren van de module in ReactPackage. De ontwikkelaar erft van deze klasse en implementeert alleen de bedrijfslogica van de methoden.

Structuur van gegenereerde bestanden

// Directorystructuur na Codegen uitvoering
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protocol
            NativeCalculatorSpec.mm    // JSI implementatie
        android/
            NativeCalculatorSpec.java  // Java interface
            NativeCalculatorModuleBase.java  // Basisklasse
        cxx/
            NativeCalculator.h         // C++ Host Object header
            NativeCalculator.cpp        // C++ JSI implementatie

Deze hele structuur wordt automatisch aangemaakt tijdens het builden van het project. De ontwikkelaar moet de gegenereerde bestanden niet bewerken — bij de volgende build worden ze overschreven. Als het gedrag van de module moet worden gewijzigd, worden aanpassingen alleen gedaan in de broncode van de native implementatie (Java/Objective-C) of in de TypeScript-specificatie.

Voorbeelden van Codegen werkstromen

Laten we de volledige werkcyclus met Codegen bekijken aan de hand van het maken van een native module voor het opslaan van gegevens in Keychain. Dit is een typische taak die toegang vereist tot de native API van iOS en Android.

Stap 1: Specificatie

De ontwikkelaar maakt een specificatiebestand dat de interface van de KeychainStorage module beschrijft. De methoden save en read ontvangen een string en retourneren een Promise, omdat werken met Keychain op sommige platforms asynchroon kan zijn.

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')

Stap 2: Codegen uitvoeren

Codegen wordt automatisch gestart bij het builden van een React Native project. Als handmatige uitvoering nodig is, wordt het commando npx react-native codegen gebruikt. Codegen parst de specificatie en maakt alle benodigde bestanden aan in build/generated/. De ontwikkelaar ziet het resultaat in de vorm van gegenereerde C++, Objective-C en Java bestanden, maar mag deze niet bewerken.

# Codegen handmatig uitvoeren
npx react-native codegen --target-path ./build/generated

# Na generatie — bouw het project
npx react-native run-ios
npx react-native run-android

Stap 3: Gebruik in JS

Na generatie en build importeert de ontwikkelaar de module als een gewoon TypeScript-type. De IDE suggereert automatisch methodesignaturen dankzij de gegenereerde .d.ts bestanden. TypeScript garandeert dat de types van parameters en retourwaarden overeenkomen met de native implementatie — als in de specificatie string staat, ontvangt de native kant precies een 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')
}

In dit voorbeeld is te zien dat de JS-code geen enkele platformaanduiding bevat — deze is hetzelfde voor iOS en Android. Alle platformspecificiteit is verborgen in de door Codegen gegenereerde code. Codegen neemt al het routinematige werk van het maken van bruggen over, waardoor de ontwikkelaar alleen de bedrijfslogica en typecontrole via TypeScript overhoudt.