Что Expo делает за вас: prebuild, конфиг и плагины

До этой главы Expo был для нас командой expo start, Metro и QR-кодом. В приложении автора (Expo SDK 57, React Native 0.86) нет ни папки ios/, ни android/ — и это не упущение, а замысел. Нативные проекты не хранятся в репозитории, а выводятся из конфига; Expo называет это Continuous Native Generation, сокращённо CNG. Выводит их одна команда:

$ npx expo prebuild --no-install

За тремя строками — три шага. Сначала из npm берётся шаблон expo-template-bare-minimum@sdk-57 — тот самый «голый» проект React Native. Его папки копируются рядом с app.config.js, а заглушка HelloWorld в именах и файлах меняется на имя приложения. Затем правится package.json: скрипты ios и android переводятся на expo run:*, а если менять нечего, строка кончится пометкой | no changes. Последний шаг, «Running prebuild», — тот, ради которого написана статья: конфиг проходит через плагины, и результат ложится в файлы. Флаг --no-install нужен, чтобы на маке следом не запустился pod install.

Вот что появится. Дерево — не вывод команды: оно собрано по составу шаблона и по путям, которые читают и пишут моды @expo/config-plugins 57. Комментарии справа — чем эти файлы наполняет конфиг.

# главное из того, что появилось рядом с app.config.js
ios/
  Podfile                                   # use_react_native! и use_expo_modules!
  Podfile.properties.json                   # ios.useFrameworks и другие свойства от плагинов
  Prilozhenie.xcodeproj/project.pbxproj     # PRODUCT_BUNDLE_IDENTIFIER
  Prilozhenie/
    AppDelegate.swift
    Info.plist                              # имя, версия, схема, ориентация, строки разрешений
    Prilozhenie.entitlements                # aps-environment от expo-notifications
    Supporting/Expo.plist                   # настройки expo-updates
    Images.xcassets/AppIcon.appiconset/     # иконка из icon
    SplashScreen.storyboard
android/
  settings.gradle                           # com.facebook.react.settings и expo-autolinking-settings
  gradle.properties                         # флаги сборки, которые пишут плагины
  app/build.gradle                          # applicationId, versionName, versionCode
  app/src/main/AndroidManifest.xml          # разрешения, схема, ориентация, meta-data плагинов
  app/src/main/java/com/appstarter/app/MainActivity.kt
  app/src/main/java/com/appstarter/app/MainApplication.kt
  app/src/main/res/values/strings.xml       # app_name

Prilozhenie — не опечатка. У приложения автора name: "Приложение", а для имён папок и цели Xcode Expo пропускает имя через sanitizedName, которая транслитерирует кириллицу; «Подход» стал бы Podhod. Проверено запуском самой функции из @expo/config-plugins. На экране телефона останется «Приложение»: отображаемое имя живёт отдельно, в CFBundleDisplayName.

Главное в этом дереве — чего в нём нет. Особой «экспо-сборки» здесь нет: Podfile зовёт use_react_native!, settings.gradle включает com.facebook.react.settings — React Native подключён как обычная зависимость CocoaPods и Gradle, как в проекте без всякого Expo. Expo добавил поверх две вещи: use_expo_modules! в Podfile и плагин expo-autolinking-settings в Gradle. Обе обходят node_modules, находят пакеты с нативным кодом и вписывают их в сборку, а на iOS ещё и генерируют ExpoModulesProvider.swift — список модулей, по которому приложение при запуске заполняет реестр. Тот самый, что вы собирали в статье «Модуль — это запись в реестре».

В CNG папки ios/ и android/ — артефакт сборки, как dist/: их не правят руками и не хранят в git. Всё, что должно в них оказаться, пишется в конфиг.

app.config.js — не JSON, а модуль Node, поэтому конфиг может вычисляться. У автора так и сделано: Firebase подключается, только если в окружении есть файлы с ключами, иначе проект не собрал бы никто, у кого их нет.

// app.config.js приложения автора, сокращено
const fs = require("node:fs");
const googleServices = process.env.GOOGLE_SERVICES_JSON;
const hasFirebase = Boolean(googleServices && fs.existsSync(googleServices));

module.exports = {
  expo: {
    name: "Приложение",
    version: "1.0.0",
    scheme: "appstarter",
    orientation: "portrait",
    userInterfaceStyle: "light",
    ios: { bundleIdentifier: "com.appstarter.app" },
    android: { package: "com.appstarter.app", edgeToEdgeEnabled: true },
    plugins: [
      // Firebase — только если в окружении есть файлы с ключами
      ...(hasFirebase ? [["@react-native-firebase/app", { disableSPM: true }]] : []),
      "expo-router",
      "expo-secure-store",
      "expo-updates",
      ["expo-notifications", { icon: "./public/icon-192.png", color: "#171717" }],
    ],
  },
};

Какие поля какими нативными ключами становятся — в таблице. Эти превращения делают плагины @expo/config-plugins, которые prebuild применяет всегда, даже при пустом списке plugins.

Смотреть на это глазами удобнее, чем по таблице, и генерировать папки для этого не нужно. npx expo config --type introspect прогоняет те же плагины и те же моды вхолостую, против встроенных заготовок файлов, и печатает, что легло бы в Info.plist и AndroidManifest.xml. Настоящий запуск на полном конфиге автора — выше он сокращён:

$ npx expo config --type introspect

Первые две строки — предупреждения самих плагинов, и обе по делу: edgeToEdgeEnabled больше ничего не значит, потому что Android 16 делает отрисовку под системными панелями обязательной, а userInterfaceStyle на Android без пакета expo-system-ui не применится. Дальше таблица сбывается построчно: name стал CFBundleDisplayName, scheme — CFBundleURLSchemes, orientation — две портретные ориентации. А вот чего таблица не предсказывала.

В Info.plist стоят строки про фотографии, камеру и микрофон, а на Android — разрешение RECORD_AUDIO. Ни один плагин из списка их не просил, и звук приложение не пишет. Источник виден в pluginHistory того же вывода: там есть expo-image-picker, которого в plugins нет. Это тот же пикер, что в статье «Фото из галереи и отправка файла», — у автора он стоит ради аватара. А у prebuild есть свой список пакетов, чьи плагины он применяет сам, стоит пакету найтись в проекте: expo-camera, expo-location, expo-image-picker и ещё почти три десятка. Плагин пикера по умолчанию просит и микрофон — на случай съёмки видео.

Строки к тому же английские и безликие: «Allow $(PRODUCT_NAME) to access your microphone». Apple требует, чтобы строка назначения объясняла, зачем приложению доступ, а разрешение на микрофон у приложения, которое ничего не записывает, — лишний повод для вопросов на модерации. Лечится это не правкой Info.plist, а тем же конфигом: плагин пикера перечисляют явно и отдают ему параметры.

plugins: [
  "expo-router",
  ["expo-image-picker", {
    photosPermission: "Фото нужно, чтобы поставить аватар в профиле",
    microphonePermission: false,
  }],
  // … остальные плагины без изменений
],

false сильнее, чем пропуск: плагин удаляет ключ из Info.plist и помечает разрешение в манифесте на удаление, чтобы его не вернула никакая другая библиотека. Тот же запуск после правки — строки про микрофон в выводе больше нет, про фото — своя, а в манифесте:

$ npx expo config --type introspect

Как плагин выглядит изнутри, видно по настоящему. Вот expo-secure-store — тот, что вписал в вывод выше строку про Face ID и правила резервного копирования. В пакете он лежит собранным JS, здесь сокращён:

// expo-secure-store: plugin/build/withSecureStore.js, сокращено
const withSecureStore = (config, { faceIDPermission, configureAndroidBackup = true } = {}) => {
  IOSConfig.Permissions.createPermissionsPlugin({
    NSFaceIDUsageDescription: FACEID_USAGE,
  })(config, { NSFaceIDUsageDescription: faceIDPermission });

  withAndroidManifest(config, (config) => {
    // … вписывает в <application> правила резервного копирования
    return config;
  });
  return config;
};

export default createRunOncePlugin(withSecureStore, pkg.name, pkg.version);

Всё, что делает плагин, — берёт конфиг и параметры и возвращает конфиг. Строка в списке plugins — имя пакета: Node находит в нём файл app.plugin.js. Кортеж — то же имя плюс параметры, которые приходят вторым аргументом. А сам список применяет функция withPlugins, и в @expo/config-plugins она занимает одну строку:

// @expo/config-plugins 57.0.9: build/plugins/withPlugins.js
const withPlugins = (config, plugins) => {
  assert(Array.isArray(plugins), "withPlugins expected a valid array of plugins or plugin module paths");
  return plugins.reduce((prev, plugin) => withStaticPlugin(prev, { plugin }), config);
};

withStaticPlugin превращает строку или кортеж в вызов функции, остальное делает reduce. Настоящего @expo/config-plugins в песочнице нет: это пакет для Node, он читает и пишет файлы проекта. Поэтому соберём то же самое: два плагина по образцу настоящих и реестр вместо поиска по node_modules. Прогноз перед запуском: какие ключи окажутся в infoPlist и изменился ли исходный appConfig?

type Plist = Record<string, string>;
interface AppConfig {
  name: string;
  ios?: { infoPlist?: Plist };
}
type PluginProps = Record<string, string | false>;
type ConfigPlugin = (config: AppConfig, props?: PluginProps) => AppConfig;
type PluginEntry = string | [string, PluginProps];

// как createPermissionsPlugin: false удаляет строку, иначе — своя, прежняя или по умолчанию
function permission(key: string, prop: string, fallback: string): ConfigPlugin {
  return (config, props) => {
    const infoPlist = { ...config.ios?.infoPlist };
    const value = props?.[prop];
    if (value === false) delete infoPlist[key];
    else infoPlist[key] = value || infoPlist[key] || fallback;
    return { ...config, ios: { ...config.ios, infoPlist } };
  };
}

// в Expo имя разрешает require: пакет отдаёт свой app.plugin.js
const registry: Record<string, ConfigPlugin> = {
  "expo-secure-store": permission("NSFaceIDUsageDescription", "faceIDPermission", "Allow $(PRODUCT_NAME) to access your Face ID biometric data."),
  "expo-image-picker": permission("NSMicrophoneUsageDescription", "microphonePermission", "Allow $(PRODUCT_NAME) to access your microphone"),
};

function withPlugins(config: AppConfig, plugins: PluginEntry[]): AppConfig {
  return plugins.reduce((prev, entry) => {
    const [name, props]: [string, PluginProps?] = typeof entry === "string" ? [entry] : entry;
    const plugin = registry[name];
    if (!plugin) throw new Error("плагин не найден: " + name);
    return plugin(prev, props);
  }, config);
}

const appConfig: AppConfig = { name: "Подход" };
const final = withPlugins(appConfig, [
  ["expo-secure-store", { faceIDPermission: "Face ID открывает дневник без пароля" }],
  "expo-image-picker",
]);
console.log(final.ios?.infoPlist);
console.log(appConfig);

Ключей два, хотя параметры получил только первый плагин: второй вписал строку по умолчанию — ровно так она и попала в приложение автора. appConfig не тронут: наши плагины каждый раз собирают новый объект, и reduce передаёт следующему то, что вернул предыдущий. Настоящие плагины чаще правят объект на месте и возвращают его же — цепочке это безразлично. Ей важно одно: плагин обязан что-то вернуть. Забытый return настоящий withPlugins встречает так: TypeError: Cannot read properties of undefined (reading '_internal') — следующему плагину достался undefined.

Теперь случай, ради которого у настоящего плагина последняя строка — createRunOncePlugin. В истории плагинов из вывода выше, кроме expo-image-picker, есть и пакеты, которых в проекте нет вовсе: react-native-maps с версией UNVERSIONED. Это встроенная копия его плагина из @expo/prebuild-config: свои списки prebuild применяет после вашего, на всякий случай, и без установленного пакета такая копия ничего не меняет. Но если пакет установлен, один и тот же плагин приходит дважды — из вашего списка с параметрами и из встроенного без них. Прогноз: что останется в infoPlist, если в своём списке микрофон выключен?

type Plist = Record<string, string>;
interface AppConfig {
  name: string;
  ios?: { infoPlist?: Plist };
  _internal?: { pluginHistory?: Record<string, string> };
}
type PluginProps = Record<string, string | false>;
type ConfigPlugin = (config: AppConfig, props?: PluginProps) => AppConfig;
type PluginEntry = string | [string, PluginProps];
// из подложки — реестр и цепочка из прошлого примера
declare const registry: Record<string, ConfigPlugin>;
declare function withPlugins(config: AppConfig, plugins: PluginEntry[]): AppConfig;

// сперва getConfig применяет ваш список, потом prebuild — свой встроенный
function prebuildConfig(): AppConfig {
  const yours = withPlugins({ name: "Подход" }, [["expo-image-picker", { microphonePermission: false }]]);
  return withPlugins(yours, ["expo-image-picker"]);
}
console.log(prebuildConfig().ios?.infoPlist);

function createRunOncePlugin(plugin: ConfigPlugin, name: string, version: string): ConfigPlugin {
  return (config, props) => {
    if (config._internal?.pluginHistory?.[name]) return config;
    const pluginHistory = { ...config._internal?.pluginHistory, [name]: version };
    return plugin({ ...config, _internal: { ...config._internal, pluginHistory } }, props);
  };
}

registry["expo-image-picker"] = createRunOncePlugin(registry["expo-image-picker"], "expo-image-picker", "57.0.13");
const once = prebuildConfig();
console.log(once.ios?.infoPlist);
console.log(once._internal?.pluginHistory);

Без страховки встроенный проход вернул строку по умолчанию: он пришёл без параметров, ключа не нашёл и вписал свой. С createRunOncePlugin второй вызов видит имя в истории и отдаёт конфиг нетронутым, и ваше false уцелело. Так ведут себя плагины, которые, как наши, пишут прямо в объект конфига. Настоящий пикер строки разрешений ставит иначе — модом, а у модов свой порядок выполнения; к пикеру вернёмся в следующей секции. История лежит в том же поле, что и в настоящем выводе, — _internal.pluginHistory, только там вместо строки объект { name, version }. Живёт она один прогон конфига: следующий prebuild считает всё заново.

Наши плагины писали прямо в объект конфига, и так поступают многие настоящие: ios.infoPlist и android.permissions потом разберут встроенные плагины. Но файлов плагин не трогает никогда. withInfoPlist и withAndroidManifest только кладут в config.mods функцию над содержимым файла — мод. В выводе npx expo config --type prebuild для приложения автора их видно поимённо:

$ npx expo config --type prebuild

Сам файл читается позже, на последнем шаге prebuild, и ровно один раз: «поставщик» читает AndroidManifest.xml, пропускает содержимое через всю цепочку модов и записывает результат. Манифест в приложении автора правят пятнадцать модов, и разбирать XML на каждый было бы и медленно, и хрупко. Цепочку каждый новый мод строит так: сперва он сам, потом всё, что было записано до него. Прогноз: два плагина ставят один и тот же ключ, A стоит в списке первым. Какие строки напечатаются и чьё значение запишется в файл?

type Plist = Record<string, string>;
type Mod = (plist: Plist) => Plist;
interface AppConfig {
  name: string;
  mods?: { infoPlist?: Mod };
}
type ConfigPlugin = (config: AppConfig) => AppConfig;

// как withInfoPlist: файл не трогает, а ставит правку в цепочку модов
function withInfoPlist(config: AppConfig, action: Mod): AppConfig {
  const next: Mod = config.mods?.infoPlist ?? ((plist) => plist);
  return { ...config, mods: { ...config.mods, infoPlist: (plist) => next(action(plist)) } };
}

function statusBar(label: string, style: string): ConfigPlugin {
  return (config) => {
    console.log("плагин " + label);
    return withInfoPlist(config, (plist) => {
      console.log("мод " + label);
      return { ...plist, UIStatusBarStyle: style };
    });
  };
}

const initial: AppConfig = { name: "Подход" };
const plugins = [statusBar("A", "UIStatusBarStyleLightContent"), statusBar("B", "UIStatusBarStyleDarkContent")];
const config = plugins.reduce((prev, plugin) => plugin(prev), initial);

// prebuild: прочитать файл один раз, прогнать через моды, записать один раз
console.log("prebuild читает Info.plist");
const read: Plist = { CFBundleDisplayName: "Подход" };
const written = config.mods?.infoPlist?.(read) ?? read;
console.log(written.UIStatusBarStyle);

Плагины отработали по порядку, а моды — задом наперёд: B раньше A, и последнее слово осталось за A, первым в списке. Такое легко принять за причуду миниатюры, поэтому сверимся с настоящим Expo. Значение мы проверили отдельно: два плагина через настоящий withInfoPlist в том же порядке — и в файл легло значение A. А порядок Expo покажет сам: с переменной окружения EXPO_DEBUG=1 он печатает каждый мод в момент выполнения. Вот все правки AndroidManifest.xml приложения автора:

$ EXPO_DEBUG=1 npx expo config --type introspect

Первой строкой идёт поставщик — он читает файл. За ним встроенные плагины Expo (withAndroidExpoPlugins), потом пикер, которого prebuild применил сам, и встроенная копия плагина карт. Ваш список — в самом конце и задом наперёд: в app.config.js стоят secure-store, updates, notifications, а выполняются notifications, updates, secure-store. Отсюда практическое следствие: моды встроенных плагинов выполняются раньше ваших, и ваш мод видит файл уже после Expo. Так задумано: свой плагин может поправить то, что записал Expo, а не наоборот.

Этот же порядок закрывает вопрос из прошлой секции. Строки разрешений настоящий пикер ставит модом, и, приди он дважды, мод из вашего списка выполнился бы последним — false уцелело бы и без createRunOncePlugin. Мы проверили это на настоящем expo-image-picker, стерев историю между двумя вызовами: ключа про микрофон в Info.plist нет, а RECORD_AUDIO в манифесте помечено tools:node="remove". Обёртка спасает плагины другого склада: те, что пишут прямо в объект конфига, как наша миниатюра, — второй вызов затрёт их параметры, — и те, что дописывают, не проверяя, — второй вызов задвоит строку. В трассировке выше она стоит у пикера, уведомлений и secure-store: это withRunOnce в их строках.

И второе следствие — для тех, кто пишет свои моды. prebuild без --clean не пересоздаёт папки, а прогоняет моды поверх уже сгенерированных файлов, и мод, который просто дописывает, допишет второй раз. Встроенные плагины от этого защищены: перед вставкой проверяют, нет ли там уже их строки, а вставки в текстовые файлы помечают комментарием @generated begin … - expo prebuild (DO NOT MODIFY), по которому находят их в следующий раз. На этом стоит первая задача к статье.

Раз ios/ и android/ — обычные проекты, из Expo можно выйти в любой момент: сгенерировать папки и начать хранить их как исходники.

$ npx expo prebuild --clean     # снести папки и сгенерировать заново по конфигу
$ git add ios android
$ git commit -m "Нативные проекты — в репозитории"
$ npx expo run:ios              # xcodebuild и Metro, как и раньше

С этой минуты меняется вот что.

Последняя строка и есть ответ на вопрос, как выйти из Expo к голому React Native. Закоммиченные папки с модулями Expo — это проект React Native, в котором подключён реестр модулей; Expo называет такой режим bare workflow. Выбросить и сам пакет expo можно, но вместе с ним уйдёт всё, что стоит на expo-modules-core: роутер, обновления, уведомления, хранилище. На это решаются, когда Expo проекту действительно чужой — например, когда React Native встраивают в давно живущее нативное приложение.

А повод выйти обычно один: какой-то SDK просит правку, для которой в конфиге нет поля, — строку в AppDelegate, свойство в gradle.properties. Такую правку лучше оформить своим плагином: файл рядом с конфигом и строка в списке.

// app.config.js
plugins: [
  "expo-router",
  "./plugins/with-rest-timer-audio.js",   // свой плагин: путь вместо имени пакета
],

Правка тогда живёт в коде: переживает --clean, новый SDK и сборку в EAS, а ios/ и android/ остаются тем, чем были всю часть, — артефактом. Следующая статья — о том, что делать, когда приложению мало Expo Go и нужна своя отладочная сборка.