Codegen: ce este, generarea codului și arhitectura Fabric

Ce este Codegen?

Codegen (prescurtare de la Code Generator) este un instrument de linie de comandă inclus în React Native, care generează automat codul de legătură pentru comunicarea între JavaScript și platformele native (iOS, Android). Codegen este o parte indispensabilă a noii arhitecturi React Native și este utilizat atât pentru Fabric (renderer), cât și pentru TurboModules (module native).

Ideea principală a Codegen constă în separarea responsabilităților: dezvoltatorul descrie „ce” ar trebui să facă funcția (semnătura sa), iar Codegen generează „cum” va fi transmis acest lucru către partea nativă. Aceasta elimină necesitatea de a scrie manual legături C++ pentru JSI, stub-uri Objective-C pentru iOS și clase Java pentru Android. Sursa unică de adevăr — specificația TypeScript — garantează că tipurile la toate nivelurile coincid, ceea ce elimină o întreagă clasă de erori legate de nepotrivirea tipurilor între JS și codul nativ.

Codegen a fost prezentat împreună cu prima versiune stabilă a noii arhitecturi React Native (0.70+) și de atunci a devenit un instrument obligatoriu pentru crearea modulelor native. Fără Codegen, dezvoltatorul ar trebui să scrie manual JSI Host Objects, ceea ce necesită cunoștințe profunde de C++ și înțelegerea funcționării interne a motoarelor JavaScript.

Evoluția: de la puntea manuală la generarea automată

Înainte de apariția Codegen, dezvoltarea unui modul nativ pentru React Native includea trei pași: scrierea interfeței JavaScript, implementarea modulului nativ în Java/Objective-C și scrierea manuală a punții. La modificarea semnăturii unei metode, trebuiau actualizate sincron toate cele trei fișiere. Codegen automatizează această rutină: modificările se fac doar în specificația TypeScript, iar restul este regenerat.

Integrarea cu sistemul de build

Codegen se integrează în procesul de build al React Native prin Metro și CocoaPods. La pornirea build-ului, Codegen analizează specificațiile TypeScript, generează fișierele C++ și de platformă și le plasează în directorul build. Aceasta înseamnă că codul generat corespunde întotdeauna specificațiilor curente și nu necesită actualizare manuală.

Cum funcționează Codegen?

Procesul de funcționare a Codegen constă din trei etape: parsarea specificațiilor, construirea reprezentării intermediare și generarea fișierelor țintă. Fiecare etapă este izolată, ceea ce permite adăugarea ușoară a suportului pentru noi platforme sau limbaje de generare.

În prima etapă, Codegen citește fișierele de specificații în format TypeScript sau Flow. Specificația descrie interfața modulului nativ: numele metodelor, tipurile parametrilor și valorilor returnate. Codegen suportă tipuri primitive (number, string, boolean), precum și tipuri complexe — obiecte, array-uri, Promise și Callback. Specificațiile sunt stocate în fișiere cu extensia .ts sau .js într-un director special al proiectului.

În a doua etapă, Codegen construiește un arbore de sintaxă abstractă (AST) din specificațiile citite. AST reprezintă structura datelor într-un format neutru, nelegat de un limbaj de generare specific. Acest lucru permite generarea codului C++ pentru Fabric, Objective-C pentru iOS și Java pentru Android dintr-un AST unic — nu este necesară nicio muncă suplimentară pentru suportul tuturor platformelor.

În a treia etapă, Codegen folosește un motor de șabloane (bazat pe Mustache) pentru generarea fișierelor platformelor țintă. Fiecare șablon răspunde de un tip specific de fișier: fișier header C++ (.h), implementare (.cpp), protocol Objective-C (.h) sau implementare (.mm), clasă Java. Șabloanele sunt livrate împreună cu React Native, dar pot fi personalizate pentru nevoi specifice ale proiectului.

Schema de funcționare a Codegen

// NativeCalculator.ts — specificația modulului nativ
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')

În acest exemplu, specificația descrie modulul NativeCalculator cu două metode: add și multiply. Ambele primesc Double și returnează Double. Șirul 'NativeCalculator' din TurboModuleRegistry indică numele modulului care va fi utilizat pe partea nativă. Codegen pe baza acestei specificații va genera toate fișierele necesare pentru Fabric și TurboModules.

Codegen în arhitectura Fabric

În contextul Fabric (noul renderer React Native), Codegen joacă un rol special. Fabric necesită ca fiecare componentă nativă UI să aibă o reprezentare C++ care poate fi creată și gestionată prin JSI. Codegen generează aceste reprezentări C++ automat pe baza specificațiilor componentelor.

Generarea pentru componente UI

Pentru componentele UI, Codegen generează nu numai clasa C++ Shadow Node, ci și reprezentările de platformă. De exemplu, pentru o componentă personalizată Button pe iOS, Codegen va crea o clasă Objective-C care înregistrează componenta în Fabric și o leagă de C++ Shadow Node. Dezvoltatorul trebuie doar să descrie proprietățile componentei (culoare, dimensiune, handler-e) în specificația TypeScript.

Tipizarea proprietăților

Codegen suportă transmiterea directă și inversă a datelor. Direct Event (de exemplu, onPress) sunt generate ca structuri C++ cu câmpuri care sunt serializate automat la transmiterea în JS. EventEmitter permite părții native să trimită evenimente în JS fără o cerere din partea JS. Codegen generează wrapper-e tipizate pentru ambele direcții, eliminând erorile de nepotrivire a numelor câmpurilor.

Codegen pentru biblioteci terțe

Dezvoltatorii de biblioteci pot livra specificații Codegen împreună cu pachetul npm. La instalarea bibliotecii, Codegen detectează automat specificațiile și generează codul de legătură pentru platforma curentă. Acest lucru este deosebit de important pentru bibliotecile native, deoarece utilizatorul bibliotecii nu trebuie să cunoască C++, Objective-C sau Java — este suficient să importe tipurile TypeScript și să folosească componentele gata făcute.

Ce fișiere generează Codegen?

Codegen generează fișiere pentru trei medii țintă: C++ (JSI), Objective-C (iOS) și Java (Android). Fiecare fișier are un rol și o structură strict definite. Înțelegerea fișierelor create ajută la depanare și, dacă este necesar, la corectarea manuală a codului generat.

Fișiere C++ (JSI)

Pentru fiecare modul nativ, Codegen creează două fișiere C++: fișier header (.h) cu declarația clasei Host Object și fișier de implementare (.cpp) cu metodele care apelează funcțiile corespunzătoare pe platformă. Fișierul header conține o clasă care moștenește jsi::HostObject cu metoda get suprascrisă pentru accesul la funcțiile modulului. Fișierul de implementare conține funcții lambda care, la apelarea din JS, delegă execuția modulului nativ.

Fișiere iOS (Objective-C)

Pentru iOS, Codegen generează un protocol Objective-C și o categorie. Protocolul declară metodele care trebuie implementate de modulul nativ. Categoria pe RCTCxxBridge conține codul de legătură care înregistrează modulul în RCTTurboModuleManager. Acest lucru permite apelarea metodelor modulului Objective-C din C++ JSI prin mecanismul standard RCTBridge.

Fișiere Android (Java)

Pentru Android, Codegen generează o interfață Java și o clasă abstractă. Interfața conține declarațiile metodelor modulului cu tipuri Java corecte. Clasa abstractă implementează interfața TurboModule și conține logica de bază pentru înregistrarea modulului în ReactPackage. Dezvoltatorul moștenește din această clasă și implementează doar logica de business a metodelor.

Structura fișierelor generate

// Structura directorului după rularea Codegen
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Protocol Objective-C
            NativeCalculatorSpec.mm    // Implementare JSI
        android/
            NativeCalculatorSpec.java  // Interfață Java
            NativeCalculatorModuleBase.java  // Clasa de bază
        cxx/
            NativeCalculator.h         // Header C++ Host Object
            NativeCalculator.cpp        // Implementare JSI C++

Întreaga această structură este creată automat la build-ul proiectului. Dezvoltatorul nu trebuie să editeze fișierele generate — la următorul build vor fi suprascrise. Dacă este necesară modificarea comportamentului modulului, modificările se fac doar în codul sursă al implementării native (Java/Objective-C) sau în specificația TypeScript.

Exemple de flux de lucru Codegen

Să analizăm ciclul complet de lucru cu Codegen pe exemplul creării unui modul nativ pentru stocarea datelor în Keychain. Aceasta este o sarcină tipică care necesită acces la API-ul nativ iOS și Android.

Pasul 1: Specificație

Dezvoltatorul creează un fișier de specificație care descrie interfața modulului KeychainStorage. Metodele save și read primesc un șir de caractere și returnează Promise, deoarece lucrul cu Keychain poate fi asincron pe unele platforme.

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

Pasul 2: Pornirea Codegen

Codegen pornește automat la build-ul proiectului React Native. Dacă este necesară pornirea manuală, se folosește comanda npx react-native codegen. Codegen parsează specificația și creează toate fișierele necesare în build/generated/. Dezvoltatorul vede rezultatul sub formă de fișiere generate C++, Objective-C și Java, dar nu trebuie să le editeze.

# Rulează Codegen manual
npx react-native codegen --target-path ./build/generated

# După generare — construiește proiectul
npx react-native run-ios
npx react-native run-android

Pasul 3: Utilizarea în JS

După generare și build, dezvoltatorul importă modulul ca un tip TypeScript obișnuit. IDE-ul sugerează automat semnăturile metodelor datorită fișierelor .d.ts generate. TypeScript garantează că tipurile parametrilor și valorilor returnate coincid cu implementarea nativă — dacă în specificație este indicat string, partea nativă va primi exact un șir de caractere.

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

În acest exemplu se vede că codul JS nu conține nicio indicație de platformă — este același pentru iOS și Android. Întreaga specifică de platformă este ascunsă în interiorul codului generat de Codegen. Codegen preia întreaga muncă de rutină de creare a punților, lăsând dezvoltatorului doar logica de business și verificarea tipurilor prin TypeScript.