Codegen : qu'est-ce que c'est, génération de code et architecture de Fabric

Qu'est-ce que Codegen ?

Codegen (abréviation de Code Generator) est un utilitaire en ligne de commande inclus dans React Native qui génère automatiquement du code de pont pour l'interaction entre JavaScript et les plateformes natives (iOS, Android). Codegen fait partie intégrante de la nouvelle architecture React Native et est utilisé à la fois pour Fabric (moteur de rendu) et TurboModules (modules natifs).

L'idée principale de Codegen est la séparation des responsabilités : le développeur décrit « ce que » doit faire une fonction (sa signature), et Codegen génère « comment » elle sera transmise au côté natif. Cela élimine la nécessité d'écrire manuellement des wrappers C++ pour JSI, des stubs Objective-C pour iOS et des classes Java pour Android. Une source unique de vérité — la spécification TypeScript — garantit que les types correspondent à tous les niveaux, éliminant toute une classe d'erreurs liées aux incompatibilités de types entre JS et le code natif.

Codegen a été présenté avec la première version stable de la nouvelle architecture React Native (0.70+) et est depuis devenu un outil obligatoire pour la création de modules natifs. Sans Codegen, les développeurs devraient écrire manuellement des JSI Host Objects, ce qui nécessite une connaissance approfondie du C++ et une compréhension du fonctionnement interne des moteurs JavaScript.

Évolution : du pont manuel à la génération automatique

Avant Codegen, le développement d'un module natif pour React Native comprenait trois étapes : écrire une interface JavaScript, implémenter le module natif en Java/Objective-C et écrire le pont manuellement. Lors de la modification de la signature d'une méthode, les trois fichiers devaient être mis à jour de manière synchrone. Codegen automatise cette routine : les modifications sont apportées uniquement à la spécification TypeScript, et tout le reste est régénéré.

Intégration avec le système de build

Codegen s'intègre dans le processus de build de React Native via Metro et CocoaPods. Lors du build, Codegen analyse les spécifications TypeScript, génère des fichiers C++ et plateforme et les place dans le répertoire de build. Cela signifie que le code généré correspond toujours aux spécifications actuelles et ne nécessite pas de mises à jour manuelles.

Comment fonctionne Codegen ?

Le flux de travail de Codegen comprend trois étapes : l'analyse des spécifications, la construction d'une représentation intermédiaire et la génération des fichiers cibles. Chaque étape est isolée, ce qui facilite l'ajout de support pour de nouvelles plateformes ou langages de génération.

Dans la première étape, Codegen lit les fichiers de spécification au format TypeScript ou Flow. La spécification décrit l'interface du module natif : noms des méthodes, types de paramètres et types de retour. Codegen prend en charge les types primitifs (number, string, boolean) ainsi que les types complexes — objets, tableaux, Promise et Callback. Les spécifications sont stockées dans des fichiers .ts ou .js dans un répertoire spécial du projet.

Dans la deuxième étape, Codegen construit un arbre de syntaxe abstraite (AST) à partir des spécifications analysées. L'AST représente la structure de données dans un format neutre non lié à un langage de génération spécifique. Cela permet de générer du code C++ pour Fabric, Objective-C pour iOS et Java pour Android à partir d'un seul AST — aucun travail supplémentaire n'est nécessaire pour prendre en charge toutes les plateformes.

Dans la troisième étape, Codegen utilise un moteur de templates (basé sur Mustache) pour générer les fichiers des plateformes cibles. Chaque template gère un type de fichier spécifique : en-tête C++ (.h), implémentation (.cpp), protocole Objective-C (.h) ou implémentation (.mm), classe Java. Les templates sont fournis avec React Native, mais peuvent être personnalisés pour les besoins spécifiques du projet.

Diagramme de fonctionnement de 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')

Dans cet exemple, la spécification décrit le module NativeCalculator avec deux méthodes : add et multiply. Les deux acceptent Double et retournent Double. La chaîne 'NativeCalculator' dans TurboModuleRegistry spécifie le nom du module qui sera utilisé côté natif. Codegen basé sur cette spécification générera tous les fichiers nécessaires pour Fabric et TurboModules.

Codegen dans l'architecture Fabric

Dans le contexte de Fabric (le nouveau moteur de rendu React Native), Codegen joue un rôle particulier. Fabric exige que chaque composant d'interface utilisateur natif ait une représentation C++ qui peut être créée et gérée via JSI. Codegen génère automatiquement ces représentations C++ à partir des spécifications des composants.

Génération pour les composants d'interface

Pour les composants d'interface, Codegen génère non seulement la classe Shadow Node en C++, mais aussi des représentations spécifiques à la plateforme. Par exemple, pour un composant Button personnalisé sur iOS, Codegen crée une classe Objective-C qui enregistre le composant dans Fabric et le lie au Shadow Node C++. Le développeur n'a qu'à décrire les propriétés du composant (couleur, taille, gestionnaires) dans la spécification TypeScript.

Typage des propriétés

Codegen prend en charge le transfert de données direct et inverse. Les événements directs (par exemple onPress) sont générés comme des structures C++ avec des champs qui sont automatiquement sérialisés lors du passage à JS. EventEmitter permet au côté natif d'envoyer des événements à JS sans demande de JS. Codegen génère des wrappers typés pour les deux directions, éliminant les erreurs de disparité de noms de champs.

Codegen pour les bibliothèques tierces

Les développeurs de bibliothèques peuvent fournir des spécifications Codegen avec leur package npm. Lors de l'installation de la bibliothèque, Codegen détecte automatiquement les spécifications et génère du code de pont pour la plateforme actuelle. Ceci est particulièrement important pour les bibliothèques natives, car les utilisateurs de la bibliothèque n'ont pas besoin de comprendre C++, Objective-C ou Java — ils importent simplement les types TypeScript et utilisent les composants prêts à l'emploi.

Quels fichiers Codegen génère-t-il ?

Codegen génère des fichiers pour trois environnements cibles : C++ (JSI), Objective-C (iOS) et Java (Android). Chaque fichier a un rôle et une structure strictement définis. Comprendre quels fichiers sont créés aide au débogage et, si nécessaire, à l'ajustement manuel du code généré.

Fichiers C++ (JSI)

Pour chaque module natif, Codegen crée deux fichiers C++ : un fichier d'en-tête (.h) avec la déclaration de la classe Host Object et un fichier d'implémentation (.cpp) avec des méthodes qui appellent les fonctions correspondantes sur la plateforme. Le fichier d'en-tête contient une classe héritée de jsi::HostObject avec une méthode get surchargée pour accéder aux fonctions du module. Le fichier d'implémentation contient des fonctions lambda qui, lorsqu'elles sont appelées depuis JS, délèguent l'exécution au module natif.

Fichiers iOS (Objective-C)

Pour iOS, Codegen génère un protocole Objective-C et une catégorie. Le protocole déclare les méthodes qui doivent être implémentées par le module natif. La catégorie sur RCTCxxBridge contient le code de pont qui enregistre le module dans RCTTurboModuleManager. Cela permet d'appeler les méthodes du module Objective-C depuis C++ JSI via le mécanisme standard RCTBridge.

Fichiers Android (Java)

Pour Android, Codegen génère une interface Java et une classe abstraite. L'interface contient des déclarations de méthodes avec des types Java corrects. La classe abstraite implémente l'interface TurboModule et contient la logique de base pour enregistrer le module dans ReactPackage. Le développeur hérite de cette classe et implémente uniquement la logique métier des méthodes.

Structure des fichiers générés

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

Toute cette structure est créée automatiquement lors du build du projet. Les développeurs ne doivent pas modifier les fichiers générés — ils seront écrasés lors du prochain build. Si le comportement du module doit être modifié, les changements sont apportés uniquement au code source de l'implémentation native (Java/Objective-C) ou à la spécification TypeScript.

Exemples de flux de travail Codegen

Parcourons le flux de travail complet de Codegen en créant un module natif pour stocker des données dans Keychain. C'est une tâche typique qui nécessite un accès à l'API native iOS et Android.

Étape 1 : Spécification

Le développeur crée un fichier de spécification décrivant l'interface du module KeychainStorage. Les méthodes save et read acceptent une chaîne et retournent une Promise, car le travail avec Keychain peut être asynchrone sur certaines plateformes.

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

Étape 2 : Exécution de Codegen

Codegen s'exécute automatiquement lors du build d'un projet React Native. Si une exécution manuelle est nécessaire, la commande npx react-native codegen est utilisée. Codegen analyse la spécification et crée tous les fichiers nécessaires dans build/generated/. Le développeur voit les fichiers C++, Objective-C et Java générés, mais ne doit pas les modifier.

# 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

Étape 3 : Utilisation en JS

Après la génération et le build, le développeur importe le module comme un type TypeScript normal. L'IDE suggère automatiquement les signatures des méthodes grâce aux fichiers .d.ts générés. TypeScript garantit que les types des paramètres et des valeurs de retour correspondent à l'implémentation native — si la spécification indique string, le côté natif recevra exactement une chaîne.

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

Cet exemple montre que le code JS ne contient aucune instruction spécifique à la plateforme — il est identique pour iOS et Android. Tous les détails spécifiques à la plateforme sont cachés dans le code généré par Codegen. Codegen gère tout le travail routinier de création des ponts, laissant au développeur uniquement la logique métier et la vérification des types via TypeScript.