Codegen: co to je, generování kódu a architektura Fabric

Co je Codegen?

Codegen (zkratka pro Code Generator) je nástroj příkazového řádku, který je součástí React Native a automaticky generuje propojovací kód pro komunikaci mezi JavaScriptem a nativními platformami (iOS, Android). Codegen je neoddělitelnou součástí nové architektury React Native a používá se jak pro Fabric (renderer), tak pro TurboModules (nativní moduly).

Hlavní myšlenka Codegen spočívá v oddělení odpovědností: vývojář popisuje „co” má funkce dělat (její signaturu) a Codegen generuje „jak” to bude předáno nativní straně. To eliminuje potřebu ručně psát C++ propojení pro JSI, Objective-C stuby pro iOS a Java třídy pro Android. Jediný zdroj pravdy — specifikace TypeScript — zaručuje, že typy na všech úrovních souhlasí, což eliminuje celou třídu chyb souvisejících s neshodou typů mezi JS a nativním kódem.

Codegen byl představen spolu s první stabilní verzí nové architektury React Native (0.70+) a od té doby se stal povinným nástrojem pro vytváření nativních modulů. Bez Codegen by vývojář musel ručně psát JSI Host Objects, což vyžaduje hluboké znalosti C++ a pochopení vnitřního fungování JavaScriptových enginů.

Evoluce: od ručního mostu k automatickému generování

Před příchodem Codegen zahrnoval vývoj nativního modulu pro React Native tři kroky: napsání JavaScriptového rozhraní, implementace nativního modulu v Java/Objective-C a ruční napsání mostu. Při změně signatury metody bylo potřeba synchronně aktualizovat všechny tři soubory. Codegen tuto rutinu automatizuje: změny se provádějí pouze ve specifikaci TypeScript a vše ostatní se generuje znovu.

Integrace se systémem sestavení

Codegen se integruje do procesu sestavení React Native přes Metro a CocoaPods. Při spuštění sestavení Codegen analyzuje specifikace TypeScript, generuje C++ a platformové soubory a umístí je do build adresáře. To znamená, že generovaný kód vždy odpovídá aktuálním specifikacím a nevyžaduje ruční aktualizaci.

Jak funguje Codegen?

Proces fungování Codegen se skládá ze tří fází: parsování specifikací, vytvoření mezilehlé reprezentace a generování cílových souborů. Každá fáze je izolovaná, což umožňuje snadno přidávat podporu pro nové platformy nebo jazyky generování.

V první fázi Codegen čte soubory specifikací ve formátu TypeScript nebo Flow. Specifikace popisuje rozhraní nativního modulu: názvy metod, typy parametrů a návratových hodnot. Codegen podporuje primitivní typy (number, string, boolean) a také složité typy — objekty, pole, Promise a Callback. Specifikace jsou uloženy v souborech s příponou .ts nebo .js ve speciálním adresáři projektu.

Ve druhé fázi Codegen vytváří abstraktní syntaktický strom (AST) z přečtených specifikací. AST představuje datovou strukturu v neutrálním formátu, nezávislém na konkrétním jazyce generování. To umožňuje generovat kód C++ pro Fabric, Objective-C pro iOS a Java pro Android z jediného AST — není vyžadována žádná další práce pro podporu všech platforem.

Ve třetí fázi Codegen používá šablonovací engine (založený na Mustache) pro generování souborů cílových platforem. Každá šablona je zodpovědná za konkrétní typ souboru: hlavičkový soubor C++ (.h), implementaci (.cpp), protokol Objective-C (.h) nebo implementaci (.mm), třídu Java. Šablony jsou dodávány spolu s React Native, ale mohou být přizpůsobeny pro specifické potřeby projektu.

Schéma fungování Codegen

// NativeCalculator.ts — specifikace nativního modulu
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')

V tomto příkladu specifikace popisuje modul NativeCalculator se dvěma metodami: add a multiply. Obě přijímají Double a vracejí Double. Řetězec 'NativeCalculator' v TurboModuleRegistry označuje název modulu, který bude použit na nativní straně. Codegen na základě této specifikace vygeneruje všechny potřebné soubory pro Fabric a TurboModules.

Codegen v architektuře Fabric

V kontextu Fabric (nový renderer React Native) hraje Codegen zvláštní roli. Fabric vyžaduje, aby každá nativní UI komponenta měla reprezentaci v C++, která může být vytvořena a spravována přes JSI. Codegen tyto C++ reprezentace generuje automaticky na základě specifikací komponent.

Generování pro UI komponenty

Pro UI komponenty Codegen generuje nejen třídu C++ Shadow Node, ale také platformové reprezentace. Například pro vlastní komponentu Button na iOS Codegen vytvoří Objective-C třídu, která registruje komponentu ve Fabric a propojuje ji s C++ Shadow Node. Vývojář potřebuje pouze popsat vlastnosti komponenty (barva, velikost, obsluhy) ve specifikaci TypeScript.

Typizace vlastností

Codegen podporuje přímý a zpětný přenos dat. Direct Event (např. onPress) jsou generovány jako C++ struktury s poli, která se automaticky serializují při přenosu do JS. EventEmitter umožňuje nativní straně odesílat události do JS bez požadavku ze strany JS. Codegen generuje typizované obaly pro oba směry, čímž eliminuje chyby neshody názvů polí.

Codegen pro knihovny třetích stran

Vývojáři knihoven mohou dodávat specifikace Codegen spolu s npm balíčkem. Při instalaci knihovny Codegen automaticky detekuje specifikace a generuje propojovací kód pro aktuální platformu. To je zvláště důležité pro nativní knihovny, protože uživatel knihovny nemusí znát C++, Objective-C nebo Java — stačí importovat TypeScript typy a používat hotové komponenty.

Jaké soubory Codegen generuje?

Codegen generuje soubory pro tři cílová prostředí: C++ (JSI), Objective-C (iOS) a Java (Android). Každý soubor má přesně definovanou roli a strukturu. Pochopení, jaké soubory se vytvářejí, pomáhá při ladění a v případě potřeby ruční korekci generovaného kódu.

C++ soubory (JSI)

Pro každý nativní modul Codegen vytváří dva C++ soubory: hlavičkový soubor (.h) s deklarací třídy Host Object a implementační soubor (.cpp) s metodami, které volají odpovídající funkce na platformě. Hlavičkový soubor obsahuje třídu dědící z jsi::HostObject s přepsanou metodou get pro přístup k funkcím modulu. Implementační soubor obsahuje lambda funkce, které při volání z JS delegují provedení nativnímu modulu.

iOS soubory (Objective-C)

Pro iOS Codegen generuje Objective-C protokol a kategorii. Protokol deklaruje metody, které musí být implementovány nativním modulem. Kategorie na RCTCxxBridge obsahuje propojovací kód, který registruje modul v RCTTurboModuleManager. To umožňuje volat metody Objective-C modulu z C++ JSI přes standardní mechanismus RCTBridge.

Android soubory (Java)

Pro Android Codegen generuje Java rozhraní a abstraktní třídu. Rozhraní obsahuje deklarace metod modulu se správnými Java typy. Abstraktní třída implementuje rozhraní TurboModule a obsahuje základní logiku pro registraci modulu v ReactPackage. Vývojář dědí z této třídy a implementuje pouze obchodní logiku metod.

Struktura generovaných souborů

// Struktura adresáře po spuštění Codegen
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protokol
            NativeCalculatorSpec.mm    // Implementace JSI
        android/
            NativeCalculatorSpec.java  // Java rozhraní
            NativeCalculatorModuleBase.java  // Základní třída
        cxx/
            NativeCalculator.h         // C++ Host Object hlavička
            NativeCalculator.cpp        // Implementace JSI C++

Celá tato struktura se vytváří automaticky při sestavení projektu. Vývojář by neměl upravovat generované soubory — při příštím sestavení budou přepsány. Pokud je potřeba změnit chování modulu, změny se provádějí pouze ve zdrojovém kódu nativní implementace (Java/Objective-C) nebo ve specifikaci TypeScript.

Příklady pracovního postupu Codegen

Podívejme se na celý cyklus práce s Codegen na příkladu vytvoření nativního modulu pro ukládání dat do Keychain. To je typický úkol, který vyžaduje přístup k nativnímu API iOS a Android.

Krok 1: Specifikace

Vývojář vytvoří soubor specifikace popisující rozhraní modulu KeychainStorage. Metody save a read přijímají řetězec a vracejí Promise, protože práce s Keychain může být na některých platformách asynchronní.

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

Krok 2: Spuštění Codegen

Codegen se spouští automaticky při sestavení projektu React Native. Pokud je potřeba ruční spuštění, použije se příkaz npx react-native codegen. Codegen parsuje specifikaci a vytváří všechny potřebné soubory v build/generated/. Vývojář vidí výsledek v podobě generovaných C++, Objective-C a Java souborů, ale neměl by je upravovat.

# Spustit Codegen ručně
npx react-native codegen --target-path ./build/generated

# Po vygenerování — sestavit projekt
npx react-native run-ios
npx react-native run-android

Krok 3: Použití v JS

Po vygenerování a sestavení vývojář importuje modul jako běžný TypeScript typ. IDE automaticky navrhuje signatury metod díky generovaným .d.ts souborům. TypeScript zaručuje, že typy parametrů a návratových hodnot souhlasí s nativní implementací — pokud je ve specifikaci uveden string, nativní strana obdrží přesně řetězec.

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

V tomto příkladu je vidět, že JS kód neobsahuje žádné označení platformy — je stejný pro iOS a Android. Veškerá specifika platformy jsou skryta uvnitř kódu generovaného Codegen. Codegen přebírá veškerou rutinní práci při vytváření mostů a ponechává vývojáři pouze obchodní logiku a kontrolu typů přes TypeScript.