Codegen: o que é, geração de código e arquitetura do Fabric

O que é Codegen?

Codegen (abreviação de Code Generator) é um utilitário de linha de comando incluído no React Native que gera automaticamente código de ponte para interação entre JavaScript e plataformas nativas (iOS, Android). O Codegen é parte integrante da nova arquitetura do React Native e é usado tanto para Fabric (renderizador) quanto para TurboModules (módulos nativos).

A ideia principal do Codegen é a separação de responsabilidades: o desenvolvedor descreve «o que» uma função deve fazer (sua assinatura), e o Codegen gera «como» ela será passada para o lado nativo. Isso elimina a necessidade de escrever manualmente wrappers C++ para JSI, stubs Objective-C para iOS e classes Java para Android. Uma única fonte de verdade — a especificação TypeScript — garante que os tipos coincidam em todos os níveis, eliminando toda uma classe de erros relacionados a incompatibilidades de tipos entre JS e código nativo.

O Codegen foi apresentado junto com a primeira versão estável da nova arquitetura do React Native (0.70+) e desde então se tornou uma ferramenta obrigatória para criar módulos nativos. Sem o Codegen, os desenvolvedores teriam que escrever manualmente JSI Host Objects, exigindo conhecimento profundo de C++ e compreensão do funcionamento interno dos motores JavaScript.

Evolução: da ponte manual à geração automática

Antes do Codegen, o desenvolvimento de um módulo nativo para React Native envolvia três etapas: escrever uma interface JavaScript, implementar o módulo nativo em Java/Objective-C e escrever a ponte manualmente. Ao alterar a assinatura de um método, era necessário atualizar sincronicamente os três arquivos. O Codegen automatiza essa rotina: as alterações são feitas apenas na especificação TypeScript, e todo o resto é regenerado.

Integração com o sistema de build

O Codegen integra-se ao processo de build do React Native através do Metro e CocoaPods. Ao executar o build, o Codegen analisa as especificações TypeScript, gera arquivos C++ e de plataforma e os coloca no diretório de build. Isso significa que o código gerado sempre corresponde às especificações atuais e não requer atualizações manuais.

Como o Codegen funciona?

O fluxo de trabalho do Codegen consiste em três etapas: análise das especificações, construção de uma representação intermediária e geração dos arquivos de destino. Cada etapa é isolada, facilitando a adição de suporte para novas plataformas ou linguagens de geração.

Na primeira etapa, o Codegen lê arquivos de especificação no formato TypeScript ou Flow. A especificação descreve a interface do módulo nativo: nomes dos métodos, tipos dos parâmetros e tipos de retorno. O Codegen suporta tipos primitivos (number, string, boolean), bem como tipos complexos — objetos, arrays, Promise e Callback. As especificações são armazenadas em arquivos .ts ou .js em um diretório especial do projeto.

Na segunda etapa, o Codegen constrói uma Árvore de Sintaxe Abstrata (AST) a partir das especificações analisadas. A AST representa a estrutura de dados em um formato neutro não vinculado a nenhuma linguagem de geração específica. Isso permite gerar código C++ para Fabric, Objective-C para iOS e Java para Android a partir de uma única AST — nenhum trabalho adicional é necessário para suportar todas as plataformas.

Na terceira etapa, o Codegen usa um mecanismo de templates (baseado em Mustache) para gerar os arquivos das plataformas de destino. Cada template lida com um tipo específico de arquivo: cabeçalho C++ (.h), implementação (.cpp), protocolo Objective-C (.h) ou implementação (.mm), classe Java. Os templates são distribuídos com o React Native, mas podem ser personalizados para necessidades específicas do projeto.

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

Neste exemplo, a especificação descreve o módulo NativeCalculator com dois métodos: add e multiply. Ambos aceitam Double e retornam Double. A string 'NativeCalculator' no TurboModuleRegistry especifica o nome do módulo que será usado no lado nativo. O Codegen com base nesta especificação gerará todos os arquivos necessários para Fabric e TurboModules.

Codegen na arquitetura Fabric

No contexto do Fabric (o novo renderizador do React Native), o Codegen desempenha um papel especial. O Fabric exige que cada componente de UI nativo tenha uma representação em C++ que possa ser criada e gerenciada através do JSI. O Codegen gera essas representações em C++ automaticamente com base nas especificações dos componentes.

Geração para componentes de UI

Para componentes de UI, o Codegen gera não apenas a classe Shadow Node em C++, mas também representações específicas de plataforma. Por exemplo, para um componente Button personalizado no iOS, o Codegen cria uma classe Objective-C que registra o componente no Fabric e o vincula ao Shadow Node em C++. O desenvolvedor só precisa descrever as propriedades do componente (cor, tamanho, manipuladores) na especificação TypeScript.

Tipagem de propriedades

O Codegen suporta transferência de dados direta e reversa. Eventos Diretos (por exemplo, onPress) são gerados como estruturas C++ com campos que são serializados automaticamente ao serem passados para JS. O EventEmitter permite que o lado nativo envie eventos para JS sem uma solicitação do JS. O Codegen gera wrappers tipados para ambas as direções, eliminando erros de incompatibilidade de nomes de campos.

Codegen para bibliotecas de terceiros

Os desenvolvedores de bibliotecas podem incluir especificações do Codegen com seu pacote npm. Ao instalar a biblioteca, o Codegen detecta automaticamente as especificações e gera código de ponte para a plataforma atual. Isso é especialmente importante para bibliotecas nativas, pois os usuários da biblioteca não precisam entender C++, Objective-C ou Java — eles apenas importam os tipos TypeScript e usam os componentes prontos.

Quais arquivos o Codegen gera?

O Codegen gera arquivos para três ambientes de destino: C++ (JSI), Objective-C (iOS) e Java (Android). Cada arquivo tem uma função e uma estrutura estritamente definidas. Entender quais arquivos são criados ajuda na depuração e, se necessário, no ajuste manual do código gerado.

Arquivos C++ (JSI)

Para cada módulo nativo, o Codegen cria dois arquivos C++: um arquivo de cabeçalho (.h) com a declaração da classe Host Object e um arquivo de implementação (.cpp) com métodos que chamam as funções correspondentes na plataforma. O arquivo de cabeçalho contém uma classe herdada de jsi::HostObject com um método get sobrescrito para acessar as funções do módulo. O arquivo de implementação contém funções lambda que, quando chamadas do JS, delegam a execução ao módulo nativo.

Arquivos iOS (Objective-C)

Para iOS, o Codegen gera um protocolo Objective-C e uma categoria. O protocolo declara os métodos que devem ser implementados pelo módulo nativo. A categoria no RCTCxxBridge contém o código de ponte que registra o módulo no RCTTurboModuleManager. Isso permite chamar métodos do módulo Objective-C a partir do C++ JSI através do mecanismo padrão RCTBridge.

Arquivos Android (Java)

Para Android, o Codegen gera uma interface Java e uma classe abstrata. A interface contém declarações de métodos com tipos Java corretos. A classe abstrata implementa a interface TurboModule e contém a lógica básica para registrar o módulo no ReactPackage. O desenvolvedor herda desta classe e implementa apenas a lógica de negócio dos métodos.

Estrutura de arquivos gerados

// 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 essa estrutura é criada automaticamente durante o build do projeto. Os desenvolvedores não devem editar os arquivos gerados — eles serão sobrescritos no próximo build. Se for necessário alterar o comportamento do módulo, as modificações são feitas apenas no código fonte da implementação nativa (Java/Objective-C) ou na especificação TypeScript.

Exemplos de fluxo de trabalho do Codegen

Vamos percorrer o fluxo de trabalho completo do Codegen criando um módulo nativo para armazenar dados no Keychain. Esta é uma tarefa típica que requer acesso à API nativa do iOS e Android.

Passo 1: Especificação

O desenvolvedor cria um arquivo de especificação descrevendo a interface do módulo KeychainStorage. Os métodos save e read aceitam uma string e retornam uma Promise, já que trabalhar com o Keychain pode ser assíncrono em algumas 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')

Passo 2: Executar o Codegen

O Codegen é executado automaticamente ao compilar um projeto React Native. Se for necessário executá-lo manualmente, usa-se o comando npx react-native codegen. O Codegen analisa a especificação e cria todos os arquivos necessários em build/generated/. O desenvolvedor vê os arquivos C++, Objective-C e Java gerados, mas não deve editá-los.

# 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: Uso em JS

Após a geração e compilação, o desenvolvedor importa o módulo como um tipo TypeScript normal. O IDE sugere automaticamente as assinaturas dos métodos graças aos arquivos .d.ts gerados. O TypeScript garante que os tipos dos parâmetros e valores de retorno correspondam à implementação nativa — se a especificação indicar string, o lado nativo receberá exatamente uma 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')
}

Este exemplo mostra que o código JS não contém instruções específicas de plataforma — é o mesmo para iOS e Android. Todos os detalhes específicos de plataforma estão ocultos dentro do código gerado pelo Codegen. O Codegen cuida de todo o trabalho rotineiro de criar pontes, deixando para o desenvolvedor apenas a lógica de negócio e a verificação de tipos através do TypeScript.