Codegen: qué es, generación de código y arquitectura de Fabric

¿Qué es Codegen?

Codegen (abreviatura de Code Generator) es una utilidad de línea de comandos incluida en React Native que genera automáticamente código de puente para la interacción entre JavaScript y las plataformas nativas (iOS, Android). Codegen es una parte integral de la nueva arquitectura de React Native y se utiliza tanto para Fabric (renderizador) como para TurboModules (módulos nativos).

La idea principal de Codegen es la separación de responsabilidades: el desarrollador describe «qué» debe hacer una función (su firma), y Codegen genera «cómo» se transmitirá al lado nativo. Esto elimina la necesidad de escribir manualmente envoltorios C++ para JSI, stubs Objective-C para iOS y clases Java para Android. Una única fuente de verdad — la especificación TypeScript — garantiza que los tipos coincidan en todos los niveles, eliminando toda una clase de errores relacionados con la falta de coincidencia de tipos entre JS y el código nativo.

Codegen se presentó junto con la primera versión estable de la nueva arquitectura de React Native (0.70+) y desde entonces se ha convertido en una herramienta obligatoria para crear módulos nativos. Sin Codegen, los desarrolladores tendrían que escribir manualmente JSI Host Objects, lo que requiere un conocimiento profundo de C++ y la comprensión del funcionamiento interno de los motores JavaScript.

Evolución: del puente manual a la generación automática

Antes de Codegen, el desarrollo de un módulo nativo para React Native implicaba tres pasos: escribir una interfaz JavaScript, implementar el módulo nativo en Java/Objective-C y escribir el puente manualmente. Al cambiar la firma de un método, era necesario actualizar sincrónicamente los tres archivos. Codegen automatiza esta rutina: los cambios se realizan solo en la especificación TypeScript, y todo lo demás se regenera.

Integración con el sistema de compilación

Codegen se integra en el proceso de compilación de React Native a través de Metro y CocoaPods. Al compilar, Codegen analiza las especificaciones TypeScript, genera archivos C++ y de plataforma, y los coloca en el directorio de compilación. Esto significa que el código generado siempre coincide con las especificaciones actuales y no requiere actualizaciones manuales.

¿Cómo funciona Codegen?

El flujo de trabajo de Codegen consta de tres etapas: análisis de especificaciones, construcción de una representación intermedia y generación de archivos destino. Cada etapa está aislada, lo que facilita añadir soporte para nuevas plataformas o lenguajes de generación.

En la primera etapa, Codegen lee archivos de especificación en formato TypeScript o Flow. La especificación describe la interfaz del módulo nativo: nombres de métodos, tipos de parámetros y tipos de retorno. Codegen admite tipos primitivos (number, string, boolean), así como tipos complejos: objetos, arrays, Promise y Callback. Las especificaciones se almacenan en archivos .ts o .js en un directorio especial del proyecto.

En la segunda etapa, Codegen construye un Árbol de Sintaxis Abstracta (AST) a partir de las especificaciones analizadas. El AST representa la estructura de datos en un formato neutro no vinculado a ningún lenguaje de generación específico. Esto permite generar código C++ para Fabric, Objective-C para iOS y Java para Android desde un único AST — no se requiere trabajo adicional para soportar todas las plataformas.

En la tercera etapa, Codegen utiliza un motor de plantillas (basado en Mustache) para generar los archivos de las plataformas destino. Cada plantilla maneja un tipo de archivo específico: cabecera C++ (.h), implementación (.cpp), protocolo Objective-C (.h) o implementación (.mm), clase Java. Las plantillas se distribuyen con React Native, pero pueden personalizarse para necesidades específicas del proyecto.

Diagrama de funcionamiento 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')

En este ejemplo, la especificación describe el módulo NativeCalculator con dos métodos: add y multiply. Ambos aceptan Double y devuelven Double. La cadena 'NativeCalculator' en TurboModuleRegistry especifica el nombre del módulo que se usará en el lado nativo. Codegen basado en esta especificación generará todos los archivos necesarios para Fabric y TurboModules.

Codegen en la arquitectura Fabric

En el contexto de Fabric (el nuevo renderizador de React Native), Codegen juega un papel especial. Fabric requiere que cada componente UI nativo tenga una representación en C++ que pueda crearse y gestionarse a través de JSI. Codegen genera estas representaciones en C++ automáticamente basándose en las especificaciones de los componentes.

Generación para componentes UI

Para componentes UI, Codegen genera no solo la clase Shadow Node en C++, sino también representaciones específicas de plataforma. Por ejemplo, para un componente Button personalizado en iOS, Codegen crea una clase Objective-C que registra el componente en Fabric y lo vincula con la Shadow Node en C++. El desarrollador solo necesita describir las propiedades del componente (color, tamaño, manejadores) en la especificación TypeScript.

Tipificación de propiedades

Codegen admite la transferencia de datos tanto directa como inversa. Los Eventos Directos (por ejemplo, onPress) se generan como estructuras C++ con campos que se serializan automáticamente al pasarse a JS. EventEmitter permite que el lado nativo envíe eventos a JS sin una solicitud desde JS. Codegen genera envoltorios tipificados para ambas direcciones, eliminando errores de discrepancia en nombres de campos.

Codegen para bibliotecas de terceros

Los desarrolladores de bibliotecas pueden incluir especificaciones Codegen con su paquete npm. Al instalar la biblioteca, Codegen detecta automáticamente las especificaciones y genera código de puente para la plataforma actual. Esto es especialmente importante para bibliotecas nativas, ya que los usuarios de la biblioteca no necesitan entender C++, Objective-C o Java — solo importan los tipos TypeScript y usan los componentes listos.

¿Qué archivos genera Codegen?

Codegen genera archivos para tres entornos destino: C++ (JSI), Objective-C (iOS) y Java (Android). Cada archivo tiene un rol y una estructura estrictamente definidos. Comprender qué archivos se crean ayuda en la depuración y, si es necesario, en el ajuste manual del código generado.

Archivos C++ (JSI)

Para cada módulo nativo, Codegen crea dos archivos C++: un archivo de cabecera (.h) con la declaración de la clase Host Object y un archivo de implementación (.cpp) con métodos que llaman a las funciones correspondientes de la plataforma. El archivo de cabecera contiene una clase heredada de jsi::HostObject con un método get sobrescrito para acceder a las funciones del módulo. El archivo de implementación contiene funciones lambda que, al ser llamadas desde JS, delegan la ejecución al módulo nativo.

Archivos iOS (Objective-C)

Para iOS, Codegen genera un protocolo Objective-C y una categoría. El protocolo declara los métodos que deben ser implementados por el módulo nativo. La categoría en RCTCxxBridge contiene el código de puente que registra el módulo en RCTTurboModuleManager. Esto permite llamar a métodos del módulo Objective-C desde C++ JSI a través del mecanismo estándar RCTBridge.

Archivos Android (Java)

Para Android, Codegen genera una interfaz Java y una clase abstracta. La interfaz contiene declaraciones de métodos con tipos Java correctos. La clase abstracta implementa la interfaz TurboModule y contiene la lógica básica para registrar el módulo en ReactPackage. El desarrollador hereda de esta clase e implementa solo la lógica de negocio de los métodos.

Estructura de archivos generados

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

Toda esta estructura se crea automáticamente durante la compilación del proyecto. Los desarrolladores no deben editar los archivos generados — se sobrescribirán en la próxima compilación. Si es necesario cambiar el comportamiento del módulo, las modificaciones se realizan solo en el código fuente de la implementación nativa (Java/Objective-C) o en la especificación TypeScript.

Ejemplos del flujo de trabajo de Codegen

Recorramos el flujo de trabajo completo de Codegen creando un módulo nativo para almacenar datos en Keychain. Esta es una tarea típica que requiere acceso a la API nativa de iOS y Android.

Paso 1: Especificación

El desarrollador crea un archivo de especificación que describe la interfaz del módulo KeychainStorage. Los métodos save y read aceptan una cadena y devuelven una Promise, ya que trabajar con Keychain puede ser asíncrono en algunas plataformas.

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

Paso 2: Ejecutar Codegen

Codegen se ejecuta automáticamente al compilar un proyecto React Native. Si es necesario ejecutarlo manualmente, se usa el comando npx react-native codegen. Codegen analiza la especificación y crea todos los archivos necesarios en build/generated/. El desarrollador ve los archivos C++, Objective-C y Java generados, pero no debe editarlos.

# 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

Paso 3: Uso en JS

Después de la generación y compilación, el desarrollador importa el módulo como un tipo TypeScript normal. El IDE sugiere automáticamente las firmas de los métodos gracias a los archivos .d.ts generados. TypeScript garantiza que los tipos de parámetros y valores de retorno coincidan con la implementación nativa — si la especificación indica string, el lado nativo recibirá exactamente una cadena.

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

Este ejemplo muestra que el código JS no contiene instrucciones específicas de plataforma — es el mismo para iOS y Android. Todos los detalles específicos de plataforma están ocultos dentro del código generado por Codegen. Codegen se encarga de todo el trabajo rutinario de crear puentes, dejando al desarrollador solo la lógica de negocio y la verificación de tipos a través de TypeScript.