Codegen: що це, генерація коду та архітектура Fabric

Що таке Codegen?

Codegen (скорочення від Code Generator) — це утиліта командного рядка, що входить до складу React Native, яка автоматично генерує зв'язуючий код для взаємодії між JavaScript і нативними платформами (iOS, Android). Codegen є невід'ємною частиною нової архітектури React Native і використовується як для Fabric (рендерер), так і для TurboModules (нативні модулі).

Основна ідея Codegen полягає в розділенні відповідальності: розробник описує «що» має робити функція (її сигнатуру), а Codegen генерує «як» це буде передано на нативну сторону. Це усуває необхідність вручну писати C++ обв'язки для JSI, Objective-C заглушки для iOS і Java класи для Android. Єдине джерело істини — TypeScript-специфікація — гарантує, що типи на всіх рівнях збігаються, що виключає цілий клас помилок, пов'язаних із невідповідністю типів між JS і нативним кодом.

Codegen був представлений разом із першою стабільною версією нової архітектури React Native (0.70+) і з тих пір став обов'язковим інструментом для створення нативних модулів. Без Codegen розробнику довелося б вручну писати JSI Host Objects, що вимагає глибоких знань C++ і розуміння внутрішнього устрою JavaScript-двигунів.

Еволюція: від ручного мосту до автоматичної генерації

До появи Codegen розробка нативного модуля для React Native включала три кроки: написання JavaScript-інтерфейсу, реалізація нативного модуля на Java/Objective-C і ручне написання мосту. При зміні сигнатури методу потрібно було синхронно оновлювати всі три файли. Codegen автоматизує цю рутину: зміни вносяться тільки в TypeScript-специфікацію, а все інше генерується заново.

Інтеграція з системою збірки

Codegen інтегрується в процес збірки React Native через Metro і CocoaPods. При запуску збірки Codegen аналізує TypeScript-специфікації, генерує C++ і платформенні файли та поміщає їх у build-директорію. Це означає, що згенерований код завжди відповідає поточним специфікаціям і не вимагає ручного оновлення.

Як працює Codegen?

Процес роботи Codegen складається з трьох етапів: парсинг специфікацій, побудова проміжного представлення та генерація цільових файлів. Кожен етап ізольований, що дозволяє легко додавати підтримку нових платформ або мов генерації.

На першому етапі Codegen читає файли специфікацій у форматі TypeScript або Flow. Специфікація описує інтерфейс нативного модуля: назви методів, типи параметрів і значень, що повертаються. Codegen підтримує примітивні типи (number, string, boolean), а також складні — об'єкти, масиви, Promise і Callback. Специфікації зберігаються у файлах із розширенням .ts або .js у спеціальній директорії проекту.

На другому етапі Codegen будує абстрактне синтаксичне дерево (AST) із прочитаних специфікацій. AST представляє структуру даних у нейтральному форматі, не прив'язаному до конкретної мови генерації. Це дозволяє генерувати C++ код для Fabric, Objective-C для iOS і Java для Android з єдиного AST — ніякої додаткової роботи для підтримки всіх платформ не потрібно.

На третьому етапі Codegen використовує шаблонізатор (на основі Mustache) для генерації файлів цільових платформ. Кожен шаблон відповідає за конкретний тип файлу: заголовний файл C++ (.h), реалізацію (.cpp), Objective-C протокол (.h) або реалізацію (.mm), Java клас. Шаблони постачаються разом із React Native, але можуть бути кастомізовані для специфічних потреб проекту.

Схема роботи 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')

У цьому прикладі специфікація описує модуль NativeCalculator із двома методами: add і multiply. Обидва приймають Double і повертають Double. Рядок 'NativeCalculator' у TurboModuleRegistry вказує ім'я модуля, яке буде використовуватися на нативній стороні. Codegen на основі цієї специфікації згенерує всі необхідні файли для Fabric і TurboModules.

Codegen в архітектурі Fabric

У контексті Fabric (новий рендерер React Native) Codegen відіграє особливу роль. Fabric вимагає, щоб кожен нативний компонент UI мав C++ представлення, яке може бути створене та кероване через JSI. Codegen генерує ці C++ представлення автоматично на основі специфікацій компонентів.

Генерація для компонентів UI

Для UI-компонентів Codegen генерує не тільки C++ клас Shadow Node, але й платформенні представлення. Наприклад, для кастомного компонента Button на iOS Codegen створить Objective-C клас, який реєструє компонент у Fabric і зв'язує його з C++ Shadow Node. Розробнику потрібно лише описати проперті компонента (колір, розмір, обробники) у TypeScript-специфікації.

Типізація проперті

Codegen підтримує пряму та зворотну передачу даних. Direct Event (наприклад, onPress) генеруються як C++ структури з полями, які автоматично серіалізуються при передачі в JS. EventEmitter дозволяє нативній стороні відправляти події в JS без запиту зі сторони JS. Codegen генерує типізовані обгортки для обох напрямків, виключаючи помилки невідповідності імен полів.

Codegen для сторонніх бібліотек

Розробники бібліотек можуть постачати специфікації Codegen разом із пакетом npm. При встановленні бібліотеки Codegen автоматично виявляє специфікації та генерує зв'язуючий код для поточної платформи. Це особливо важливо для нативних бібліотек, оскільки користувачу бібліотеки не потрібно розбиратися в C++, Objective-C або Java — достатньо імпортувати TypeScript-типи та використовувати готові компоненти.

Які файли генерує Codegen?

Codegen генерує файли для трьох цільових середовищ: C++ (JSI), Objective-C (iOS) і Java (Android). Кожен файл має строго визначену роль і структуру. Розуміння того, які файли створюються, допомагає у налагодженні та при необхідності ручного коригування згенерованого коду.

C++ файли (JSI)

Для кожного нативного модуля Codegen створює два C++ файли: заголовний (.h) з оголошенням класу Host Object і файл реалізації (.cpp) з методами, які викликають відповідні функції на платформі. Заголовний файл містить клас, успадкований від jsi::HostObject, з перевизначеним методом get для доступу до функцій модуля. Файл реалізації містить лямбда-функції, які при виклику з JS делегують виконання нативному модулю.

iOS файли (Objective-C)

Для iOS Codegen генерує Objective-C протокол і категорію. Протокол оголошує методи, які мають бути реалізовані нативним модулем. Категорія на RCTCxxBridge містить зв'язуючий код, який реєструє модуль у RCTTurboModuleManager. Це дозволяє викликати методи Objective-C модуля з C++ JSI через стандартний механізм RCTBridge.

Android файли (Java)

Для Android Codegen генерує Java інтерфейс і абстрактний клас. Інтерфейс містить оголошення методів модуля з правильними типами Java. Абстрактний клас реалізує інтерфейс TurboModule і містить базову логіку для реєстрації модуля в ReactPackage. Розробник успадковує від цього класу та реалізує тільки бізнес-логіку методів.

Структура згенерованих файлів

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

Вся ця структура створюється автоматично при збірці проекту. Розробник не повинен редагувати згенеровані файли — при наступній збірці вони будуть перезаписані. Якщо потрібно змінити поведінку модуля, зміни вносяться тільки у вихідний код нативної реалізації (Java/Objective-C) або в TypeScript-специфікацію.

Приклади робочого процесу Codegen

Розглянемо повний цикл роботи з Codegen на прикладі створення нативного модуля для зберігання даних у Keychain. Це типове завдання, яке вимагає доступу до нативного API iOS і Android.

Крок 1: Специфікація

Розробник створює файл специфікації, що описує інтерфейс модуля KeychainStorage. Методи save і read приймають рядок і повертають Promise, оскільки робота з Keychain може бути асинхронною на деяких платформах.

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

Крок 2: Запуск Codegen

Codegen запускається автоматично при збірці React Native проекту. Якщо потрібно запустити його вручну, використовується команда npx react-native codegen. Codegen парсить специфікацію та створює всі необхідні файли в build/generated/. Розробник бачить результат у вигляді згенерованих C++, Objective-C і Java файлів, але не повинен їх редагувати.

# 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

Крок 3: Використання в JS

Після генерації та збірки розробник імпортує модуль як звичайний TypeScript-тип. IDE автоматично підказує сигнатури методів завдяки згенерованим .d.ts файлам. TypeScript гарантує, що типи параметрів і значень, що повертаються, збігаються з нативною реалізацією — якщо в специфікації вказано 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')
}

У цьому прикладі видно, що JS-код не містить жодних вказівок на платформу — він однаковий для iOS і Android. Вся платформенна специфіка прихована всередині згенерованого Codegen коду. Codegen бере на себе всю рутинну роботу зі створення мостів, залишаючи розробнику тільки бізнес-логіку та перевірку типів через TypeScript.