Обработка встроенных папок как результата сборки с использованием 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. Если нативная зависимость оказывается неисправной или при обновлении React Native, эти папки удаляются и сгенерируются заново. Ежедневный вопрос меняется с «Что кто-то изменил в проекте Xcode?» на «Что указано в конфигурации?».

Это также устанавливает единственное правило модели: как только генерируются файлы нативного кода, их нельзя редактировать вручную. Любые изменения, сделанные вручную, исчезают при следующей подготовке к сборке. Если вам нужно внести изменения, они должны быть указаны в конфигурации.

Плагины конфигурации заменяют ручные изменения нативного кода

Это вызывает очевидный вопрос: как добавить разрешение в AndroidManifest.xml или скорректировать AppDelegate.mm, если генерируемые файлы недоступны для редактирования?

Ответ — плагины конфигурации. Плагин конфигурации — это функция на JavaScript, которая выполняется во время подготовки к сборке и изменяет проект нативного кода контролируемым и воспроизводимым способом. Приложения с высокими требованиями к нативному коду, такие как обработка речи в реальном времени или отрисовка 3D-моделей, зависят от библиотек, требующих глубокой интеграции с нативным кодом, и эти библиотеки обычно поставляют собственные плагины.

Вместо редактирования исходного кода вы указываете плагин и его параметры в файле app.json. В приведённом ниже примере используется expo-build-properties для установки значения compileSdkVersion в Android равным 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

Если простое выполнение команды с параметром —clean не помогает, CNG предлагает более эффективный вариант: команда npx expo prebuild --clean полностью удаляет и воссоздаёт папки с нативным кодом, что безопасно именно потому, что в них нет элементов, требующих ручного управления. Включение обеих этих практик в вашу рутину помогает избежать длительных сессий отладки.

Предоставление конфиденциальных данных для облачной сборки EAS

CNG наиболее эффективен при использовании вместе с EAS (Expo Application Services) для облачной сборки.

Возьмём, к примеру, мониторинг ошибок. Продакшн-приложения в нём нуждаются, а интеграция с Sentry подразумевает загрузку карт исходного кода, для чего требуется SENTRY_AUTH_TOKEN. Раньше этот токен должен был попадать в каждую среду сборки, оставаясь при этом вне репозитория, что затрудняло его управление.

При использовании CNG и EAS достаточно добавить плагин конфигурации Sentry в файл app.json, не сохраняя при этом токен. Вместо этого его регистрируют в качестве переменной окружения в EAS с помощью CLI, предоставляя ему доступ только в режиме секрета и ограничивая его действие проектом, так что он будет доступен во время сборки, но не отобразится после неё. Выполните команду один раз, заменив местоименный значок на ваш настоящий токен:

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 запускает этап предсборки для генерации нативных проектов, плагин 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, плавных интерфейсах и функциях продукта.

Связанные материалы

• Подключение внутриприложенного Turbo Module от начала до конца с использованием React Native Codegen — определение типизированного спецификация, запуск процесса генерации кода и реализация Turbo Module на iOS и Android с использованием синхронных методов, Promise, обратных вызовов и эмиттеров событий.
• Поддержка постоянной смены тем в React Native с использованием Context и Hooks — Создание инструмента для смены тем в React Native с применением Context, useState и useEffect: навигация между вкладками, выбор темы, сохранение настроек с помощью AsyncStorage и защита от загрузки во время запуска приложения.