Обробка вбудованих папок як результату збірки за допомогою Expo Prebuild та CNG

Протягом багатьох років команди React Native в Expo стикалися з однаковою проблемою: як тільки проекту потрібен був власний нативний модуль, фоновий аудіо чи SDK від постачальника, рішенням було expo eject, і охайний JavaScript-проект раптово отримував повні каталоги ios та android. Відтоді команда також мусила піклуватися про CocoaPods, редагувати build.gradle та вирішувати проблеми в Xcode. Технології Continuous Native Generation (CNG) та Expo Prebuild усувають цей компроміс. У цьому посібнику пояснюється, як працює ця модель, як плагіни конфігурації замінюють ручну редагування нативного коду, як відновити пошкоджені локальні проекти для Android та як передати конфіденційну інформацію у хмарні проекти без її збереження.

Нативний код як артефакт будови

CNG ґрунтується на одному принципі: нативні проекти — це те, що ви генеруєте, а не те, що підтримуєте вручну.

Виконання команди npx expo prebuild створює папки ios та android на основі єдиного джерела інформації — вашого файлу app.json або app.config.js. Функція Prebuild читає цю конфігурацію, застосовує описані в ній зміни та генерує повні проекти для компіляції.

Оскільки ці папки можна створити заново в будь-який момент, багато команд додають папки /ios та /android до файла .gitignore. Якщо залежність типу native опиняється у несправному стані або під час оновлення React Native, ці папки видаляються та створюються заново. Щоденне питання змінюється з „Що хтось змінив у проекті Xcode?“ на „Що вказано в конфігурації?“.

Це також встановлює єдине правило моделі: як тільки створюються нативні папки, їх не слід редагувати вручну. Будь-які ручні зміни зникають під час наступної попередньої обробки. Якщо вам потрібна зміна, її необхідно вказати у конфігурації.

Плагіни конфігурації замінюють ручне редагування нативних файлів

Це піднімає очевидне запитання: як додати права до AndroidManifest.xml або змінити AppDelegate.mm, якщо створені файли є недоступними?

Відповіддю є плагіни конфігурації. Плагін конфігурації — це функція JavaScript, яка виконується під час попередньої обробки та змінює нативний проект у контрольований, повторюваний спосіб. Додатки з високими вимогами до нативного коду, такі як обробка реального часу мовлення або відтворення 3D-моделей, залежать від бібліотек, які потребують глибоких інтеграцій з нативним кодом, і ці бібліотеки зазвичай постачають власні плагіни.

Замість редагування нативного коду ви вказуєте плагін та його параметри у файлі app.json. У наведеному нижче прикладі використовується expo-build-properties для встановлення значення Android compileSdkVersion на 34, що інакше мало б знаходитися у файлі Gradle:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 34
          }
        }
      ]
    ]
  }
}

Під час наступної попередньої компіляції плагін записує це значення у створений проект для Android. Оскільки зміна оголошується, а не вноситься вручну, вона зберігається під час кожної перегенерації та є видимою під час перевірки коду.

Підтримка належного стану локальних проектів для Android

Expo Go чудово підходить для раннього створення прототипів, але включає лише нативні модулі, які йдуть разом з ним. Як тільки ви починаєте використовувати власний нативний код, тестування проводиться за допомогою версій для розробки, використовуючи npx expo run:android або npx expo run:ios. Це особливо важливо для додатків, які виконують обчислення безпосередньо на пристрої, наприклад з використанням функцій ШІ, де необхідно побачити справжню продуктивність на пристрої чи емуляторі.

Інструментальний комплекс для Android має репутацію систем із нестабільними кешами. Типова ситуація: ви додаєте залежність, і наступна локальна компіляція провалюється через незрозумілу помилку Java чи Gradle. Причиною зазвичай є застарілі результати компіляції, а не ваш код.

Спочатку варто спробувати провести чисту компіляцію. Зайдіть у створений каталог android, запустіть завдання Gradle «clean», щоб видалити кешовані результати, потім поверніться до кореня проекту та знову скомпілюйте його:

cd android
./gradlew clean
cd ..
npx expo run:android

Якщо лише очищення не допомагає, CNG пропонує більш ефективний варіант: npx expo prebuild --clean повністю видаляє та створює заново папки нативного коду, що є безпечним саме тому, що нічого в них не підтримується вручну. Включення обох цих практик у вашу рутину допомагає уникнути тривалих сеансів виправлення помилок.

Надання конфіденційної інформації для клієнтських серверів EAS

CNG найбільш ефективний у поєднанні з EAS (Expo Application Services) для клієнтських серверів.

Візьмемо моніторинг помилок. Продуктивні додатки його потребують, а інтеграція з Sentry передбачає завантаження карт джерелного коду, що вимагає SENTRY_AUTH_TOKEN. Традиційно цей токен мусив потрапляти до кожного середовища збірки, залишаючись поза репозиторієм, що ускладнювало його керування.

За допомогою CNG та EAS ви додаєте плагін конфігурації Sentry до app.json та ніколи не зберігаєте токен. Натомість ви реєструєте його як змінну середовища в EAS за допомогою CLI, надаючи йому рівень доступу secret та обмежуючи його дію проектом, щоб він був доступний під час збірки, але не відображався після неї. Виконайте команду один раз, підставивши свій справжній токен замість значення-замінника:

eas env:create --name SENTRY_AUTH_TOKEN --value your_token_here --visibility secret --scope projecteas env:create --name SENTRY_AUTH_TOKEN --value your_token_here --visibility secret --scope project

Під час збірки в хмарі EAS запускає крок prebuild для створення нативних проектів; плагін Sentry читає секретну інформацію з середовища, налаштовує нативний SDK та завантажує карти джерела. Жодні нативні файли та жоден токен не потрапляють під контроль версій. Точні параметри команди eas env:create можуть змінюватися між версіями CLI, тому якщо команда відхиляється, перевірте актуальну документацію EAS.

Коли CNG потребує додаткової уваги

Ця модель є потужною, але для деяких ситуацій потрібен попередній планування:

• Бібліотеки без плагінів. Якщо нативний SDK не має плагіна налаштувань, вам може знадобитися самостійно написати невеликий локальний плагін замість того, щоб редагувати створені файли.
• Існуючі проекти типу „браунфілд“. Додатки з роками ручного редагування нативного коду не можна просто видалити — для міграції потрібно спочатку перенести кожну налаштування до конфігураційних файлів.
• Дисципліна команди. CNG працює лише тоді, коли всі ставляться до ios та android як до ресурсів, які можна замінити. Одна швидка зміна в Xcode буде мовчки втрачена під час наступної генерації.

Підсумок

Expo Prebuild та CNG роблять складні додатки React Native промислового рівня значно доступнішими, роблячи нативні шари замінними:

• Оголошіть вимоги до нативного коду у app.json або app.config.js, і нехай prebuild створить решту.

Використовуйте плагіни конфігурації для кожної зміни в нативному коді, щоб вона залишалася після перегенерації.

Очищуйте кеш Gradle або перегенеруйте проект за допомогою prebuild --clean, якщо локальні збірки незрозуміло завершуються з помилками.

Зберігайте токени, такі як SENTRY_AUTH_TOKEN, у змінних середовища EAS, а не в репозиторії.

Оскільки нативні проекти зводяться до результатів збірки, увага команди знову зосереджується на коді React Native, плавних інтерфейсах та функціях продукту.

Пов’язана література

• Підключення In-App Turbo Module від початку до кінця за допомогою React Native Codegen — визначте типову специфікацію, запустіть кодгенерацію та реалізуйте Turbo Module на iOS та Android за допомогою синхронних, Promise-, callback- та event-emitter-методів.
• Зберігання налаштувань теми в React Native за допомогою Context та Hooks — Створіть механізм зміни теми в React Native за допомогою Context, useState та useEffect: навігація між вкладками, вибір теми, зберігання даних у AsyncStorage та захист під час завантаження.