Где кончается готовый клиент: свой dev client

Приложение на телефоне состоит из двух половин. Нативная — бинарник: Hermes, React Native, нативные модули, Info.plist и манифест с именем, иконкой, схемами и строками разрешений. Её собирают Xcode и Gradle, и в магазин уходит именно она. Вторая половина — бандл: ваш код, собранный Metro. В отладке он не зашит в бинарник, а скачивается с Metro при каждом запуске, поэтому правка в редакторе видна на телефоне через секунду.

Expo Go подменяет только нативную половину. Это готовый бинарник, в который Expo вшила модули своего SDK и фиксированный список сторонних библиотек, а ваш бандл он скачивает с Metro, как любая отладочная сборка. Своя сборка отличается от него ровно одним: бинарник собран из вашего проекта.

Вопрос «хватит ли Expo Go» сводится к реестру из статьи «Модуль — это запись в реестре»: пакет ищет свой модуль по имени, а найдётся ли он, решает бинарник. Даже isRunningInExpoGo() из пакета expo 57 устроена так же — это поиск модуля ExpoGo, который есть только в бинарнике Expo Go. В пакете поиск делается один раз при импорте, в миниатюре — при каждом вызове. Сам пакет expo в песочнице не соберётся: expo-modules-core тянет TurboModuleRegistry, которого у react-native-web нет. Поэтому обе функции примера переписаны с исходников.

В подложке — реестр и цепочка поиска из той статьи. Один и тот же «бандл» загружается в два бинарника: в Expo Go и в свою сборку. Бандлу нужны три модуля: ExpoSecureStore из SDK Expo, RNCSafeAreaContext из react-native-safe-area-context и AppMetrica — SDK аналитики Яндекса, который стоит в приложении автора. Последние два ищутся не через requireNativeModule, а через TurboModuleRegistry React Native: так написано в их спецификациях. AppMetrica зовёт getEnforcing, который бросает, безопасные зоны — мягкий get, который вернёт null; миниатюре хватает одного getEnforcing. Прогноз: что напечатает каждый бинарник и на каком модуле споткнётся Expo Go?

declare function requireNativeModule<T>(name: string): T;
declare var expo: { modules: Record<string, object> } | undefined;
declare var __turboModuleProxy: ((name: string) => object | null) | undefined;

// isRunningInExpoGo из пакета expo 57: это тоже поиск в реестре
function isRunningInExpoGo(): boolean {
  try {
    requireNativeModule("ExpoGo");
    return true;
  } catch {
    return false;
  }
}

// TurboModuleRegistry.getEnforcing из react-native 0.86 — так свой модуль ищет AppMetrica
function getEnforcing(name: string): object {
  const module = globalThis.__turboModuleProxy?.(name) ?? null;
  if (module == null) {
    throw new Error("TurboModuleRegistry.getEnforcing(...): '" + name + "' could not be found. Verify that a module by this name is registered in the native binary.");
  }
  return module;
}

// бинарник — это набор модулей, вшитый при сборке; бандл от Metro в обоих случаях один
function boot(binary: string, expoModules: string[], turboModules: string[]): void {
  globalThis.expo = { modules: Object.fromEntries(expoModules.map((name) => [name, {}])) };
  globalThis.__turboModuleProxy = (name) => (turboModules.includes(name) ? {} : null);
  console.log(binary + " · в Expo Go: " + isRunningInExpoGo());
  try {
    requireNativeModule("ExpoSecureStore");
    getEnforcing("RNCSafeAreaContext");
    getEnforcing("AppMetrica");
    console.log(binary + " · бандл загрузился");
  } catch (e) {
    console.log(binary + " · " + (e as Error).message);
  }
}

boot("Expo Go", ["ExpoGo", "ExpoSecureStore", "ExponentImagePicker"], ["RNCSafeAreaContext"]);
boot("своя сборка", ["ExpoSecureStore", "ExponentImagePicker", "DevLauncherModule"], ["RNCSafeAreaContext", "AppMetrica"]);

Expo Go знает ExpoSecureStore — в нём весь SDK Expo — и RNCSafeAreaContext: библиотека безопасных зон входит в его список. AppMetrica в список не входит, и строка ошибки дословно та, что бросает TurboModuleRegistry.getEnforcing в react-native 0.86. Своя сборка прошла все три: autolinking нашёл AppMetrica в node_modules и вшил её. Зато модуля ExpoGo в ней нет, и isRunningInExpoGo() честно отвечает false.

Одно отличие от телефона. В миниатюре ошибку ловит try, а в пакете getEnforcing стоит на верхнем уровне файла: export default TurboModuleRegistry.getEnforcing("AppMetrica"). Он выполняется при первом импорте, то есть при загрузке бандла, и на телефоне вместо экрана «Подхода» появляется красный экран с этой строкой. Падает не кнопка аналитики, а весь запуск.

npm install меняет только JS-половину. Доставить модуль в бинарник Expo Go нельзя никак: его собрали без вас и до вас.

Стена выглядит по-разному, но причина всегда одна: нужное живёт в нативной половине, а она чужая.

Второй симптом легко принять за мелочь. Вот как expo-notifications 57.0.14 проверяет, где он запущен:

// expo-notifications 57.0.14 · build/warnOfExpoGoPushUsage.js, кавычки двойные, ссылка в тексте сокращена
export const warnOfExpoGoPushUsage = () => {
  if (isRunningInExpoGo() && !didWarn) {
    const message = `expo-notifications: Android Push notifications (remote notifications) functionality provided by expo-notifications was removed from Expo Go with the release of SDK 53. Use a development build instead of Expo Go. Learn more at …`;
    if (Platform.OS === "android") {
      throw new Error(message);
    } else if (__DEV__) {
      didWarn = true;
      console.warn(message);
    }
  }
};

На Android это не предупреждение, а исключение. Зовут проверку функции токенов и подписки на темы — всё, что нужно для пушей с сервера, а они вырезаны из Expo Go начиная с SDK 53. Сам пакет при импорте печатает ещё одно предупреждение: `expo-notifications` functionality is not fully supported in Expo Go — с советом собрать development build. Для «Подхода» это значит: локальное уведомление об окончании отдыха из главы 9 в Expo Go ещё работает, а токен для пушей с сервера на Android уже не получить.

Первые два симптома можно обойти кодом, но не вылечить. Автор так и поступил с аналитикой: SDK подключается не импортом, а через require внутри try, и без нативной половины приложение просто работает без статистики.

// apps/mobile · src/shared/analytics/appmetrica/appmetrica.ts, сокращено, кавычки двойные
function sdk(): AppMetricaModule | null {
  if (unavailable || !API_KEY) return null;
  try {
    // статический import выполнился бы при загрузке бандла и уронил бы старт в Expo Go
    const imported = require("@appmetrica/react-native-analytics") as { default: AppMetricaModule };
    return imported.default;
  } catch (error) {
    unavailable = true;
    console.warn("[appmetrica] SDK недоступен — приложение работает без него", error);
    return null;
  }
}

Для необязательного это правильный ответ: ради аналитики не стоит ронять запуск. Но если модуль — то, над чем вы работаете сейчас, такая обёртка лишь спрячет, что он не работает. Правило простое: когда фича живёт в нативном коде, которого в Expo Go нет, нужна своя сборка. Для всего остального Expo Go по-прежнему хорош: чистый JS, прототип, показать экран коллеге с его телефона. Какие пакеты тянут за собой свою сборку, а каким хватает Expo Go, разбирает полка React Native и Expo — по трём вопросам: знает ли пакет SDK, есть ли у него нативная половина и вшит ли его модуль в Expo Go.

Своя отладочная сборка — это ваше приложение в конфигурации Debug плюс две вещи, за которые любят Expo Go: экран-лаунчер, который находит Metro и загружает бандл, и меню разработчика. Это пакеты expo-dev-launcher и expo-dev-menu, а expo-dev-client ставит их вместе. Для SDK 57 последняя версия — expo-dev-client 57.0.19; исходники, на которые дальше ссылается статья, — из 57.0.5 того же SDK.

$ npx expo install expo-dev-client

app.config.js после этой команды не меняется, и это не забывчивость. expo-dev-client стоит в том же встроенном списке @expo/prebuild-config, из-за которого в прошлой статье сам собой применился expo-image-picker: prebuild применит его плагин, едва найдёт пакет. А expo install пакеты из этого списка в plugins не дописывает — в autoAddConfigPlugins.js для них стоит отдельная проверка.

Не уедет ли лаунчер в магазин? Нет, хотя платформы решают это по-разному. На iOS в expo-module.config.json обоих пакетов, в секции apple, стоит "debugOnly": true, и их поды подключаются только к Debug. На Android такого флага нет: пакеты компилируются и в релиз, но из набора исходников disableInRelease, где лаунчер и меню выключены. Настоящий код попадёт туда, только если явно включить свойства Gradle expo.devlauncher.configureInRelease и expo.devmenu.configureInRelease. Релизная сборка того же проекта — профили preview и production из следующей статьи — выйдет без работающего лаунчера и меню.

Кроме подключения двух соседей плагин expo-dev-client делает главное — даёт сборке свою URL-схему. Expo Go открывается по ссылкам exp://, а QR-код от expo start должен открыть не его, а вашу сборку. Схема выводится из slug функцией getDefaultScheme, и над заменой символов в ней стоит комментарий «Remove unallowed characters. Also remove `-` to keep this shorter.»

Соберём это на цепочке плагинов из прошлой статьи: она в подложке, и наш плагин встаёт в тот же реестр. В списке он дважды — так бывает, если вписать его в plugins руками, скажем ради параметра launchMode, а prebuild применит ещё и встроенную копию. Прогноз: какие схемы окажутся в Info.plist, какой адрес уйдёт в QR-код и что выйдет из slug Podhod_App и подход?

interface UrlType {
  CFBundleURLSchemes: string[];
}
interface AppConfig {
  name: string;
  slug: string;
  ios?: { infoPlist?: { CFBundleURLTypes?: UrlType[] } };
}
type ConfigPlugin = (config: AppConfig) => AppConfig;
// из подложки — реестр и цепочка из статьи «Что Expo делает за вас»
declare const registry: Record<string, ConfigPlugin>;
declare function withPlugins(config: AppConfig, plugins: string[]): AppConfig;

// expo-dev-client 57 · plugin/build/getDefaultScheme.js, без проверок типа аргумента
function getDefaultScheme(config: { slug: string }): string {
  let scheme = config.slug.replace(/[^A-Za-z0-9+\-.]/g, "");
  if (scheme.length === 0) {
    throw new Error(`Unable to generate a scheme based on the "slug" (${config.slug}), because it does not contain any URL-friendly characters.`);
  }
  scheme = scheme.toLowerCase();
  return `exp+${scheme}`;
}

// iOS-половина плагина: повторяет withGeneratedIosScheme из expo-dev-client 57
registry["expo-dev-client"] = (config) => {
  const scheme = getDefaultScheme(config);
  const types = config.ios?.infoPlist?.CFBundleURLTypes ?? [];
  if (types.some((type) => type.CFBundleURLSchemes.includes(scheme))) return config;
  const infoPlist = { ...config.ios?.infoPlist, CFBundleURLTypes: [...types, { CFBundleURLSchemes: [scheme] }] };
  return { ...config, ios: { ...config.ios, infoPlist } };
};

const before: AppConfig = {
  name: "Приложение",
  slug: "stack-starter",
  ios: { infoPlist: { CFBundleURLTypes: [{ CFBundleURLSchemes: ["appstarter", "com.appstarter.app"] }] } },
};
const after = withPlugins(before, ["expo-dev-client", "expo-dev-client"]);
console.log(after.ios?.infoPlist?.CFBundleURLTypes);

// так CLI собирает адрес для QR: схема сборки плюс адрес Metro, закодированный целиком
const scheme = getDefaultScheme(after);
console.log(`${scheme}://expo-development-client/?url=${encodeURIComponent("http://192.168.1.5:8081")}`);
console.log(getDefaultScheme({ slug: "Podhod_App" }));
getDefaultScheme({ slug: "подход" });

Дефис остался. Комментарий обещает его убрать, а класс символов [^A-Za-z0-9+\-.] его разрешает — и правильно разрешает: по RFC 3986 дефис в схеме допустим. Верьте коду, а не комментарию. Второй проход ничего не задвоил: плагин сперва ищет, нет ли уже такой схемы, как hasScheme в настоящем, а сам настоящий плагин вдобавок обёрнут в createRunOncePlugin.

Подчёркивание из Podhod_App выброшено по тому же RFC, и это кстати: constructDevClientUrl в @expo/cli отказывается строить адрес со схемой, где есть _, — в комментарии сказано, что Node такой URL не разберёт. Кириллический slug даёт ошибку уже здесь, поэтому slug держат латиницей, а русское имя живёт в name — как «Приложение» у автора.

Вторая строка — ровно тот формат, что строит UrlCreator.constructDevClientUrl в @expo/cli 57.0.18: схема сборки, служебный хост expo-development-client и адрес Metro в параметре url. Адрес закодирован целиком, иначе его : и / смешались бы с частями внешней ссылки. Телефон получает ссылку с незнакомой схемой, спрашивает систему, кто её зарегистрировал, и открывает вашу сборку, а та идёт за бандлом по адресу из параметра.

Путей два. Локальный — npx expo run:android или npx expo run:ios. Если папки платформы нет, команда сама запускает prebuild — только для этой платформы, — затем собирает проект Gradle или Xcode в Debug, ставит результат на эмулятор или подключённый телефон и запускает Metro. Для Android нужен Android Studio с SDK, для iOS — Xcode, а значит, Mac. Вот что печатает первый запуск:

$ npx expo run:android

Строка «Opening» — та самая ссылка из миниатюры: CLI открыл сборку по её собственной схеме. Второй запуск пойдёт быстрее: папка android/ уже есть, prebuild пропускается, и Gradle пересобирает только изменённое.

Облачный путь — EAS Build, ему посвящена следующая статья. Пока хватит того, что в eas.json приложения автора профиль для отладочной сборки уже есть:

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "channel": "development",
      "ios": { "simulator": true }
    }
  }
}

developmentClient: true — собрать Debug с лаунчером, distribution: internal — раздавать ссылкой, а не через магазин. И вот ловушка, на которую проект автора наступит при первом же eas build --profile development: профиль просит dev client, а пакета expo-dev-client в package.json нет. eas-cli проверяет это ещё до отправки в облако:

$ eas build --profile development --platform android

Проекту без папок ios/ и android/ eas-cli предлагает поставить пакет сам, а отказ обрывает сборку. В проекте с закоммиченными папками он только предупреждает — «If you proceed anyway, you might not get the build you want.» — и собирает, если согласиться. Выйдет сборка без лаунчера и без схемы exp+, и QR-коду открыть будет нечего.

Готовая сборка попадает на устройство по-разному — смотря для чего она собрана:

У автора профиль development собирает iOS только под симулятор. Чтобы отлаживать на своём iPhone, нужен второй профиль — без ios.simulator — и зарегистрированный телефон.

В eas-cli 24 есть и короткий путь для эмулятора и симулятора: eas build:dev ищет готовую dev-сборку с тем же отпечатком нативной части и собирает новую, только если такой нет. Профиль автора ему подходит: команда требует developmentClient: true, distribution: internal, а для iOS ещё ios.simulator: true или withoutCredentials: true. Но назвать его придётся явно, eas build:dev --profile development: по умолчанию команда ищет профиль development-simulator и, не найдя, предлагает его создать. Что такое отпечаток и почему по нему можно не пересобирать, разберёт глава 11.

Запустите сборку без Metro — откроется лаунчер: раздел «Development Servers», подсказка «Start a local development server with: npx expo start» и кнопка «Enter URL manually», если адрес проще вбить руками. Metro лаунчер ищет в локальной сети, и на iOS для этого нужно разрешение «Локальная сеть». Откажете в системном запросе — список серверов останется пустым, а лаунчер покажет экран «Local Network Access Disabled». Это первое, что стоит проверить, когда сборка «не видит» Metro.

С установленным expo-dev-client команда npx expo start сама переключается на сборку: в detectDevClient.js CLI смотрит, есть ли пакет в dependencies или devDependencies. Фрагмент вывода:

$ npx expo start

В строке «Metro:» стоит не http://, а ссылка со схемой сборки — её же и кодирует QR-код. Клавиша s возвращает к Expo Go. Если переключиться на него при установленном пакете, CLI перед открытием проверит, нет ли на устройстве вашей сборки, а не найдя её, скажет прямо: «The expo-dev-client package is installed, but a development build is not installed on …» — и откроет Expo Go.

Меню разработчика открывается так:

Подписи взяты из исходников expo-dev-menu 57.0.5, из SwiftUI-версии для iOS. В Compose-версии для Android они те же, только «Fast Refresh» с большой буквы. На обеих платформах внизу меню есть ещё кнопка «Open React Native dev menu» — старое меню самого React Native.

j или «Open DevTools» открывает React Native DevTools в Chrome или Edge. Это фронтенд браузерных DevTools, подключённый не к вкладке, а к Hermes на телефоне: консоль с вашими console.log, Sources с точками останова прямо в исходниках TypeScript, память — и вкладки React DevTools с профайлером, который записывает коммиты, — о нём шла речь в статье «Что на самом деле тормозит» части IV. Приёмы из «Отладки в браузере» части I работают почти без изменений. Нет только вкладки Elements: DOM у приложения нет, его место занимает инспектор элементов из меню.

Осталось решить, когда собирать клиент заново. Сборка содержит нативную половину такой, какой она была в момент сборки. Правки TS и JS, новые экраны, пакеты без нативного кода приезжают через Metro, как и в Expo Go. Пересборка нужна, когда меняется бинарник: пакет с нативным кодом, поля конфига, которые проходят через prebuild, — плагины, разрешения, схема, иконка, имя, — и версия SDK. Ошибиться можно и в обратную сторону: expo-haptics в Expo Go есть, а в вашей сборке его не будет, пока вы её не пересоберёте.

И последнее: dev client — сборка Debug, бандл в ней не минифицирован, а React работает в режиме разработки. Скорость приложения на ней не меряют — для этого есть сборка preview. Как отвечать на вопрос «нужна ли пересборка» не на глаз, а вычислением, покажет глава 11. А следующая статья — о профилях eas.json и сборке в облаке без Xcode.