Codegen: cos'è, generazione di codice e architettura di Fabric

Cos'è Codegen?

Codegen (abbreviazione di Code Generator) è un'utilità da riga di comando inclusa in React Native che genera automaticamente codice di collegamento per l'interazione tra JavaScript e le piattaforme native (iOS, Android). Codegen è parte integrante della nuova architettura React Native e viene utilizzato sia per Fabric (renderizzatore) che per TurboModules (moduli nativi).

L'idea principale di Codegen è la separazione delle responsabilità: lo sviluppatore descrive «cosa» dovrebbe fare una funzione (la sua firma), e Codegen genera «come» verrà passata al lato nativo. Ciò elimina la necessità di scrivere manualmente wrapper C++ per JSI, stub Objective-C per iOS e classi Java per Android. Un'unica fonte di verità — la specifica TypeScript — garantisce che i tipi corrispondano a tutti i livelli, eliminando un'intera classe di errori relativi a discrepanze di tipi tra JS e codice nativo.

Codegen è stato introdotto con la prima versione stabile della nuova architettura React Native (0.70+) e da allora è diventato uno strumento obbligatorio per la creazione di moduli nativi. Senza Codegen, gli sviluppatori dovrebbero scrivere manualmente JSI Host Objects, richiedendo una conoscenza approfondita del C++ e la comprensione del funzionamento interno dei motori JavaScript.

Evoluzione: dal ponte manuale alla generazione automatica

Prima di Codegen, lo sviluppo di un modulo nativo per React Native prevedeva tre fasi: scrivere un'interfaccia JavaScript, implementare il modulo nativo in Java/Objective-C e scrivere manualmente il ponte. Quando la firma di un metodo cambiava, tutti e tre i file dovevano essere aggiornati in modo sincrono. Codegen automatizza questa routine: le modifiche vengono apportate solo alla specifica TypeScript e tutto il resto viene rigenerato.

Integrazione con il sistema di build

Codegen si integra nel processo di build di React Native attraverso Metro e CocoaPods. All'avvio della build, Codegen analizza le specifiche TypeScript, genera file C++ e di piattaforma e li colloca nella directory di build. Ciò significa che il codice generato corrisponde sempre alle specifiche correnti e non richiede aggiornamenti manuali.

Come funziona Codegen?

Il flusso di lavoro di Codegen si compone di tre fasi: analisi delle specifiche, costruzione di una rappresentazione intermedia e generazione dei file di destinazione. Ogni fase è isolata, facilitando l'aggiunta di supporto per nuove piattaforme o linguaggi di generazione.

Nella prima fase, Codegen legge i file di specifica in formato TypeScript o Flow. La specifica descrive l'interfaccia del modulo nativo: nomi dei metodi, tipi di parametri e tipi di ritorno. Codegen supporta tipi primitivi (number, string, boolean) e tipi complessi — oggetti, array, Promise e Callback. Le specifiche sono memorizzate in file .ts o .js in una directory speciale del progetto.

Nella seconda fase, Codegen costruisce un albero sintattico astratto (AST) dalle specifiche analizzate. L'AST rappresenta la struttura dei dati in un formato neutro non legato a un linguaggio di generazione specifico. Ciò consente di generare codice C++ per Fabric, Objective-C per iOS e Java per Android da un singolo AST — non è richiesto alcun lavoro aggiuntivo per supportare tutte le piattaforme.

Nella terza fase, Codegen utilizza un motore di template (basato su Mustache) per generare i file delle piattaforme di destinazione. Ogni template gestisce un tipo specifico di file: header C++ (.h), implementazione (.cpp), protocollo Objective-C (.h) o implementazione (.mm), classe Java. I template sono forniti con React Native, ma possono essere personalizzati per esigenze specifiche del progetto.

Diagramma di funzionamento di Codegen

// 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 questo esempio, la specifica descrive il modulo NativeCalculator con due metodi: add e multiply. Entrambi accettano Double e restituiscono Double. La stringa 'NativeCalculator' in TurboModuleRegistry specifica il nome del modulo che verrà utilizzato sul lato nativo. Codegen basato su questa specifica genererà tutti i file necessari per Fabric e TurboModules.

Codegen nell'architettura Fabric

Nel contesto di Fabric (il nuovo renderizzatore React Native), Codegen svolge un ruolo speciale. Fabric richiede che ogni componente UI nativo abbia una rappresentazione C++ che possa essere creata e gestita attraverso JSI. Codegen genera automaticamente queste rappresentazioni C++ in base alle specifiche dei componenti.

Generazione per componenti UI

Per i componenti UI, Codegen genera non solo la classe Shadow Node in C++, ma anche rappresentazioni specifiche della piattaforma. Ad esempio, per un componente Button personalizzato su iOS, Codegen crea una classe Objective-C che registra il componente in Fabric e lo collega allo Shadow Node C++. Lo sviluppatore deve solo descrivere le proprietà del componente (colore, dimensione, gestori) nella specifica TypeScript.

Tipizzazione delle proprietà

Codegen supporta il trasferimento dati diretto e inverso. Gli eventi diretti (ad esempio onPress) vengono generati come strutture C++ con campi che vengono automaticamente serializzati quando passati a JS. EventEmitter consente al lato nativo di inviare eventi a JS senza una richiesta da JS. Codegen genera wrapper tipizzati per entrambe le direzioni, eliminando errori di disallineamento dei nomi dei campi.

Codegen per librerie di terze parti

Gli sviluppatori di librerie possono fornire specifiche Codegen con il loro pacchetto npm. Quando la libreria viene installata, Codegen rileva automaticamente le specifiche e genera codice di collegamento per la piattaforma corrente. Questo è particolarmente importante per le librerie native, poiché gli utenti della libreria non hanno bisogno di comprendere C++, Objective-C o Java — importano semplicemente i tipi TypeScript e utilizzano i componenti pronti.

Quali file genera Codegen?

Codegen genera file per tre ambienti di destinazione: C++ (JSI), Objective-C (iOS) e Java (Android). Ogni file ha un ruolo e una struttura strettamente definiti. Capire quali file vengono creati aiuta nel debugging e, se necessario, nella regolazione manuale del codice generato.

File C++ (JSI)

Per ogni modulo nativo, Codegen crea due file C++: un file header (.h) con la dichiarazione della classe Host Object e un file di implementazione (.cpp) con metodi che chiamano le funzioni corrispondenti sulla piattaforma. Il file header contiene una classe ereditata da jsi::HostObject con un metodo get sovrascritto per accedere alle funzioni del modulo. Il file di implementazione contiene funzioni lambda che, quando chiamate da JS, delegano l'esecuzione al modulo nativo.

File iOS (Objective-C)

Per iOS, Codegen genera un protocollo Objective-C e una categoria. Il protocollo dichiara i metodi che devono essere implementati dal modulo nativo. La categoria su RCTCxxBridge contiene il codice di collegamento che registra il modulo in RCTTurboModuleManager. Ciò consente di chiamare i metodi del modulo Objective-C da C++ JSI attraverso il meccanismo standard RCTBridge.

File Android (Java)

Per Android, Codegen genera un'interfaccia Java e una classe astratta. L'interfaccia contiene dichiarazioni di metodi con tipi Java corretti. La classe astratta implementa l'interfaccia TurboModule e contiene la logica di base per registrare il modulo in ReactPackage. Lo sviluppatore eredita da questa classe e implementa solo la logica di business dei metodi.

Struttura dei file generati

// 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

L'intera struttura viene creata automaticamente durante la build del progetto. Gli sviluppatori non devono modificare i file generati — verranno sovrascritti alla prossima build. Se è necessario modificare il comportamento del modulo, le modifiche vengono apportate solo al codice sorgente dell'implementazione nativa (Java/Objective-C) o alla specifica TypeScript.

Esempi del flusso di lavoro di Codegen

Esaminiamo il flusso di lavoro completo di Codegen creando un modulo nativo per memorizzare dati in Keychain. Questo è un compito tipico che richiede l'accesso all'API nativa di iOS e Android.

Passo 1: Specifica

Lo sviluppatore crea un file di specifica che descrive l'interfaccia del modulo KeychainStorage. I metodi save e read accettano una stringa e restituiscono una Promise, poiché il lavoro con Keychain può essere asincrono su alcune piattaforme.

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

Passo 2: Esecuzione di Codegen

Codegen viene eseguito automaticamente durante la build di un progetto React Native. Se è necessario eseguirlo manualmente, si usa il comando npx react-native codegen. Codegen analizza la specifica e crea tutti i file necessari in build/generated/. Lo sviluppatore vede i file C++, Objective-C e Java generati, ma non deve modificarli.

# 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

Passo 3: Utilizzo in JS

Dopo la generazione e la build, lo sviluppatore importa il modulo come un normale tipo TypeScript. L'IDE suggerisce automaticamente le firme dei metodi grazie ai file .d.ts generati. TypeScript garantisce che i tipi dei parametri e dei valori restituiti corrispondano all'implementazione nativa — se la specifica indica string, il lato nativo riceverà esattamente una stringa.

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

Questo esempio mostra che il codice JS non contiene istruzioni specifiche della piattaforma — è lo stesso per iOS e Android. Tutti i dettagli specifici della piattaforma sono nascosti all'interno del codice generato da Codegen. Codegen gestisce tutto il lavoro di routine della creazione dei ponti, lasciando allo sviluppatore solo la logica di business e il controllo dei tipi attraverso TypeScript.