Одно приложение, три платформы

В статье «Что в этой песочнице настоящее» Platform.select оказался одной строкой react-native-web: есть ключ web — берётся он, нет — default. Там же выяснилось, что default — это третья платформа, о которой подумали заранее. Но предпросмотр показывает только веб-половину правила. На телефоне у select на один ключ больше:

// react-native 0.86.0 · Libraries/Utilities/Platform.ios.js — без типов Flow, кавычки двойные
select: (spec) =>
  "ios" in spec ? spec.ios : "native" in spec ? spec.native : spec.default,

// react-native 0.86.0 · Libraries/Utilities/Platform.android.js — так же
select: (spec) =>
  "android" in spec ? spec.android : "native" in spec ? spec.native : spec.default,

// react-native-web 0.21.2 · dist/exports/Platform/index.js — для сравнения
select: obj => "web" in obj ? obj.web : obj.default,

iOS и Android сначала ищут свой ключ, потом native — «любой телефон», — и только потом default. Веб о native не знает вовсе: он не телефон. Проверить это в песочнице напрямую нельзя — Platform.OS здесь всегда "web". Поэтому поступим, как с плотностью в прошлой статье: там densityFor(scale) отвечала за телефон с заданной плотностью, здесь platformFor(os) ответит за телефон с заданной системой — по тем же правилам, что в исходниках выше. Последней строкой сравним её с настоящим Platform.select предпросмотра. Прогноз: что выберет каждая платформа в трёх решениях «Подхода» — шрифт, место для токена и способ вернуться назад?

type OS = "ios" | "android" | "web";
type Spec<T> = { ios?: T; android?: T; web?: T; native?: T; default?: T };
const { Platform } = ReactNative;

// Platform телефона с заданной системой: select — те же правила, что в Platform.ios.js
// и Platform.android.js из react-native 0.86, а для веба — что в react-native-web
function platformFor(os: OS) {
  return {
    OS: os,
    select<T>(spec: Spec<T>): T | undefined {
      if (os === "web") return "web" in spec ? spec.web : spec.default;
      return os in spec ? spec[os] : "native" in spec ? spec.native : spec.default;
    },
  };
}

// три решения «Подхода», которые зависят от платформы
const specs = [
  { ios: "System", android: "sans-serif", default: "system-ui" },
  { native: "SecureStore", default: "localStorage" },
  { android: "системной кнопкой", default: "кнопкой в шапке" },
];

for (const os of ["ios", "android", "web"] as const) {
  const p = platformFor(os);
  console.log(os + ":", specs.map((spec) => p.select(spec)).join(" | "));
}
console.log("предпросмотр:", specs.map((spec) => Platform.select(spec)).join(" | "));

iOS взял свой шрифт System, Android — sans-serif, веб — default. Токен оба телефона положили в SecureStore: своих ключей у них нет, и сработал native. Веб его пропустил и взял default — localStorage. Вернуться назад Android предлагает системной кнопкой, остальные — кнопкой в шапке. Строка предпросмотра совпала со строкой web: наша функция и react-native-web выбирают одинаково. С этого места platformFor лежит в подложке: где предпросмотр отвечает за браузер, она ответит за телефон.

native в select — не платформа, а «любой телефон»: iOS и Android берут его, если своего ключа нет, веб — никогда. Тот же смысл у суффикса .native в имени файла, о нём третий раздел.

Теперь стена, в которую упирается проект. «Подход» хранит токен входа. На телефоне его место — защищённое хранилище системы: Keychain на iOS, Keystore на Android. До него дотягивается expo-secure-store — модуль SDK, верхний этаж. В браузере Keychain нет, остаётся localStorage. Первое, что приходит в голову, — один файл и ветка по Platform.OS в каждом методе. Пакеты Expo в песочнице не собираются, поэтому веб-сборка expo-secure-store изображена ровно тем, что в ней лежит: файл ExpoSecureStore.web.ts — это export default {}, а функции обёртки SecureStore.ts, повторённой в сокращении, зовут методы этого объекта. Прогноз: что напечатают вход и выход в предпросмотре?

const { Platform } = ReactNative;

// веб-сборка expo-secure-store: его ExpoSecureStore.web.ts — это export default {}.
// Пакеты Expo в песочницу не собираются, поэтому обёртка SecureStore.ts повторена в сокращении
const ExpoSecureStore: any = {};
const SecureStore = {
  getItemAsync: (key: string) => ExpoSecureStore.getValueWithKeyAsync(key, {}),
  setItemAsync: (key: string, value: string) => ExpoSecureStore.setValueWithKeyAsync(value, key, {}),
  deleteItemAsync: (key: string) => ExpoSecureStore.deleteValueWithKeyAsync(key, {}),
};
// localStorage в песочнице — заглушка в памяти, поэтому сразу память
const memory = new Map<string, string>();

// хранилище сессии «Подхода»: одна реализация на все платформы, ветки внутри
const sessionStorage = {
  async getItem(key: string): Promise<string | null> {
    if (Platform.OS === "web") return memory.get(key) ?? null;
    return SecureStore.getItemAsync(key);
  },
  async setItem(key: string, value: string): Promise<void> {
    if (Platform.OS === "web") {
      memory.set(key, value);
      return;
    }
    return SecureStore.setItemAsync(key, value);
  },
  async removeItem(key: string): Promise<void> {
    return SecureStore.deleteItemAsync(key);
  },
};

async function session() {
  await sessionStorage.setItem("session", "t-42");
  console.log("вход, токен:", await sessionStorage.getItem("session"));
  try {
    await sessionStorage.removeItem("session");
    console.log("выход: готово");
  } catch (e) {
    console.log("выход:", String(e));
  }
}
session();

Вход сработал: Platform.OS в предпросмотре — "web", и оба метода с проверкой ушли в память. Выход упал: removeItem дописывали позже, проверяли на телефоне, и ветку для веба забыли. Компилятор промолчал — модуль из реестра приходит типом any: у requireNativeModule из expo-modules-core параметр типа по умолчанию any, а ExpoSecureStore.ts вызывает его без параметра. Ошибку увидит пользователь веб-версии, когда нажмёт «Выйти». В этом и стена: платформ три, и каждый новый метод, каждое место, где читают токен, обязано помнить все три. Проверки Platform.OS расползаются по коду, а забытая ломает одну платформу, и только в рантайме.

Второй вопрос — что с таким файлом делает сборка. В коде Platform.OS читается при каждом вызове, но выпускная сборка собирается под одну платформу и знает её заранее. babel-preset-expo в выпускном режиме подставляет вместо Platform.OS строку платформы, а вызов Platform.select со статичными ключами заменяет выбранным значением. Потом transform-worker из @expo/metro-config прогоняет свёртку констант — constantFoldingPlugin из Metro, — и ветка с заведомо ложным условием исчезает. Вот что вышло из настоящих пакетов на файле с той же веткой; служебные строки модуля — хелперы и объявления экспортов — из вывода убраны:

// entities/session/token.ts — одна реализация с веткой, как в примере выше
import { Platform } from "react-native";
import * as SecureStore from "expo-secure-store";

export async function getItem(key: string) {
  if (Platform.OS === "web") return localStorage.getItem(key);
  return SecureStore.getItemAsync(key);
}
export const tokenPlace = Platform.select({ native: "SecureStore", default: "localStorage" });

Ветка чужой платформы и правда исчезла: на iOS от getItem осталось только чтение SecureStore, а select превратился в строку. Но require("expo-secure-store") остался в обеих сборках — свёртка убирает ветки, а не импорты. В веб-версии getItem после return лежит мёртвая строка с SecureStore, а сам модуль попадёт в веб-сборку: tree shaking у Metro в Expo 57 экспериментальный, его включает переменная EXPO_UNSTABLE_TREE_SHAKING, а по умолчанию она выключена. В сборке для разработки не подставляется ничего — тот же прогон в режиме разработки оставил Platform.OS === "web" и вызов select как есть: платформа читается в рантайме, и на месте все ветки. Исключение — process.env.EXPO_OS: его babel-preset-expo заменяет строкой платформы всегда, при разработке тоже.

У самого Metro есть такой же плагин — inline-plugin из metro-transform-plugins, — но в transform-worker Expo строка с ним закомментирована: подстановку делает babel-preset-expo, ещё до перевода модуля в CommonJS. Правила у двух плагинов разные, и это проверено запуском обоих на одном вызове select: для веба плагин Metro подставил «SecureStore», то есть значение native, а плагин Expo — «localStorage», как react-native-web в рантайме.

Второй способ — развести платформы не веткой, а файлом. Два файла с одним именем и разными суффиксами, а импорт — без суффикса и без расширения: import { sessionStorage } from "./session-storage". Какой из файлов подставить, решает сборщик, отдельно для каждой платформы. Так хранилище сессии сделано в мобильном приложении автора. Кавычки заменены на двойные, веб-версия сокращена: у автора каждый вызов там обёрнут в try, потому что в приватном режиме Safari запись бросает исключение.

// entities/session/session-storage.types.ts
/**
 * Хранилище сессии. Реализаций две, Metro выбирает по платформе:
 * session-storage.ts (натив, expo-secure-store) и session-storage.web.ts
 * (браузер, localStorage).
 */
export interface SessionStorage {
  getItem: (key: string) => Promise<string | null>;
  setItem: (key: string, value: string) => Promise<void>;
  removeItem: (key: string) => Promise<void>;
}

// entities/session/session-storage.ts — iOS и Android
import * as SecureStore from "expo-secure-store";
import type { SessionStorage } from "./session-storage.types";

export const sessionStorage: SessionStorage = {
  getItem: (key) => SecureStore.getItemAsync(key),
  setItem: (key, value) => SecureStore.setItemAsync(key, value),
  removeItem: (key) => SecureStore.deleteItemAsync(key),
};

// entities/session/session-storage.web.ts — браузер
import type { SessionStorage } from "./session-storage.types";

export const sessionStorage: SessionStorage = {
  getItem: async (key) => globalThis.localStorage?.getItem(key) ?? null,
  setItem: async (key, value) => globalThis.localStorage?.setItem(key, value),
  removeItem: async (key) => globalThis.localStorage?.removeItem(key),
};

// любой экран — один импорт на все платформы
import { sessionStorage } from "@/entities/session/session-storage";

Сравните с веткой. Проверок Platform.OS нет ни одной. Веб-сборка не видит expo-secure-store вовсе: его импортирует только файл, который в неё не попадает. Новый метод в интерфейсе заставит дописать оба файла — при условии, что оба объявлены одним типом; к этому вернёмся в последнем разделе. Тем же приёмом пользуются сами пакеты: у expo-secure-store рядом лежат ExpoSecureStore.ts и ExpoSecureStore.web.ts, у expo — registerRootComponent.tsx и registerRootComponent.web.tsx из статьи про свой проект.

Правило выбора живёт в Metro — сборщике, с которым поставляется React Native, — в функции resolveSourceFile пакета metro-resolver:

// metro-resolver 0.84.5 · src/resolve.js — две функции целиком; третья,
// resolveSourceFileForExt, склеивает путь и спрашивает файловую систему
function resolveSourceFile(context, platform) {
  let filePath = resolveSourceFileForAllExts(context, "");
  if (filePath) {
    return filePath;
  }
  const { sourceExts } = context;
  for (let i = 0; i < sourceExts.length; i++) {
    const ext = `.${sourceExts[i]}`;
    filePath = resolveSourceFileForAllExts(context, ext, platform);
    if (filePath != null) {
      return filePath;
    }
  }
  return null;
}

function resolveSourceFileForAllExts(context, sourceExt, platform) {
  if (platform != null) {
    const ext = `.${platform}${sourceExt}`;
    const filePath = resolveSourceFileForExt(context, ext);
    if (filePath) {
      return filePath;
    }
  }
  if (context.preferNativePlatform && sourceExt !== "") {
    const filePath = resolveSourceFileForExt(context, `.native${sourceExt}`);
    if (filePath) {
      return filePath;
    }
  }
  const filePath = resolveSourceFileForExt(context, sourceExt);
  return filePath;
}

Сначала путь пробуется как есть: так находится импорт, записанный с расширением. Затем для каждого расширения по порядку делаются три попытки: .платформа.расширение, потом .native.расширение, если включён preferNativePlatform, и наконец просто .расширение. Остальное настраивает Expo. Порядок расширений собирает @expo/metro-config: getBareExtensions из @expo/config даёт ts, tsx, mjs, js, jsx и json, а в конец дописывается cjs. preferNativePlatform ставит @expo/cli в withMetroMultiPlatform.js одним выражением: platform !== "web". Отсюда таблица:

В таблице спрятана оговорка — в словах «если нет»: сравниваются файлы с одним и тем же расширением, а расширения перебираются снаружи. Во что это выливается, покажет свой резолвер.

В песочнице нет ни диска, ни сборщика, поэтому файлы проекта станут списком имён, а резолвер — функцией от списка, пути импорта и платформы. Правило то же, что в resolveSourceFile: путь как есть, затем расширения в порядке Expo и три попытки внутри каждого. Неудачные попытки копим в tried. Прогноз: какой файл достанется каждой платформе для хранилища, вибрации и нижней панели?

type Target = "ios" | "android" | "web";
// порядок расширений Expo SDK 57: getBareExtensions из @expo/config и cjs в конце
const SOURCE_EXTS = ["ts", "tsx", "mjs", "js", "jsx", "json", "cjs"];

function resolvePlatform(files: string[], request: string, platform: Target): string {
  // путь, записанный с расширением, берётся как есть — без всякой платформы
  if (files.includes(request)) return request;
  const tried: string[] = [];
  const exists = (ext: string) => {
    if (files.includes(request + ext)) return request + ext;
    tried.push(ext);
    return null;
  };
  for (const ext of SOURCE_EXTS) {
    const found =
      exists(`.${platform}.${ext}`) ??
      // .native — «любой телефон»: Expo включает его всем платформам, кроме веба
      (platform !== "web" ? exists(`.native.${ext}`) : null) ??
      exists(`.${ext}`);
    if (found) return found;
  }
  // из тех же попыток Metro собирает своё сообщение, когда файла нет
  throw new Error(`none of these files exist: ${request}(${tried.join("|")})`);
}

const files = [
  "./session-storage.ts", "./session-storage.web.ts", "./session-storage.types.ts",
  "./haptics.ios.ts", "./haptics.android.ts", "./haptics.ts",
  "./tab-bar.native.tsx", "./tab-bar.tsx",
];
for (const request of ["./session-storage", "./haptics", "./tab-bar"]) {
  const picked = (["ios", "android", "web"] as const).map((p) => resolvePlatform(files, request, p));
  console.log(request, "→", picked.join(" | "));
}

Хранилище разошлось, как задумано: телефонам — session-storage.ts, вебу — .web.ts. session-storage.types.ts не выбрался ни разу: types — не платформа, а путь ./session-storage плюс .ts даёт другое имя. У вибрации каждому телефону свой файл, а веб взял общий — своего у него нет, и общий может просто ничего не делать. Панель tab-bar.native.tsx досталась обоим телефонам, а веб её пропустил. Так же в expo-router лежат useBackButton.native.js и useBackButton.js: первый подписывается на системную «назад» Android, он встретится в статье «Собираем стек экранов с историей».

Теперь оговорка из прошлого раздела. Внешний цикл — по расширениям, внутренний — по суффиксам. Значит, суффикс платформы побеждает только среди файлов с одним расширением. С этого места резолвер лежит в подложке рядом с platformFor. Диалог подтверждения: телефонная версия — app-alert.ts без JSX, а веб-версию на Modal написали прямо в app-alert.web.tsx. Рядом — звук конца отдыха, который есть только для iOS и Android. Прогноз: что достанется вебу в обоих случаях?

declare function resolvePlatform(files: string[], request: string, platform: "ios" | "android" | "web"): string;

// диалог: телефонная версия без JSX, веб-версию на Modal написали прямо в .web.tsx;
// звук конца отдыха есть только для iOS и Android
const files = ["./app-alert.ts", "./app-alert.web.tsx", "./rest-sound.ios.ts", "./rest-sound.android.ts"];

for (const request of ["./app-alert", "./rest-sound"]) {
  for (const platform of ["ios", "android", "web"] as const) {
    try {
      console.log(request, platform, "→", resolvePlatform(files, request, platform));
    } catch (e) {
      console.log(request, platform, "→", (e as Error).message);
    }
  }
}

Веб получил телефонный app-alert.ts. Для расширения .ts резолвер попробовал app-alert.web.ts, затем app-alert.ts — и второй файл нашёлся; до .tsx очередь не дошла. Сборка пройдёт без единого предупреждения, а в веб-версии вызов уйдёт в Alert.alert — в react-native-web у Alert единственный статический метод alert с пустым телом, и диалог молча не появится. Лечится одинаковым расширением в паре: .ts с .web.ts или .tsx с .web.tsx. В статье «Modal и свой Alert вместо пустышки» веб-файл так и сделан: app-alert.web.ts только реэкспортирует диалог из соседнего модуля.

Звук отдыха — противоположный случай, громкий. Для веба нет ни своего файла, ни общего, и резолвер перебрал четырнадцать имён. Metro на этом месте останавливает сборку с тем же списком в скобках: «The module could not be resolved because none of these files exist». Файлы только под телефоны — ошибка сборки для веба, и хорошо, что ошибка: её видно сразу, а не у пользователя. Лечится общим файлом-заглушкой rest-sound.ts.

// сверка: настоящий metro-resolver 0.84.5 на выдуманной папке, настройки Expo SDK 57
const { resolve } = require("metro-resolver");
const names = ["app-alert.ts", "app-alert.web.tsx", "rest-sound.ios.ts", "rest-sound.android.ts"];
const files = new Set(names.map((f) => "/app/src/" + f));
const context = {
  sourceExts: ["ts", "tsx", "mjs", "js", "jsx", "json", "cjs"],
  fileSystemLookup: (p) => (files.has(p) ? { exists: true, type: "f", realPath: p } : { exists: false }),
  originModulePath: "/app/src/index.ts",
  // …ещё два десятка полей: пакеты, haste, условия экспорта — выбор файла от них не зависит
};
for (const request of ["./app-alert", "./rest-sound"]) {
  for (const platform of ["ios", "android", "web"]) {
    context.preferNativePlatform = platform !== "web";
    try {
      console.log(request, platform, "→", resolve(context, request, platform).filePath);
    } catch (e) {
      console.log(request, platform, "→", e.message);
    }
  }
}

Резолвер выбирает имя. Дальше сборщик кладёт в сборку код только выбранного файла, а выполняет его один раз — при первом require. В сборке Metro каждый файл — фабрика, зарегистрированная через define(factory, moduleId, dependencyMap), а metroRequire отдаёт уже выполненный модуль, если у него стоит isInitialized; это metro-runtime/src/polyfills/require.js — тот же реестр с кешем, что в своём сборщике. Повторим его поверх резолвера: requireFor(platform, modules) принимает файлы проекта словарём «путь → фабрика» и возвращает свою функцию загрузки. Хранилища в песочнице — память, но печатают, куда пишут. Прогноз для двух сборок?

declare function resolvePlatform(files: string[], request: string, platform: "ios" | "android" | "web"): string;
type Target = "ios" | "android" | "web";

// загрузчик сборки под платформу: как metroRequire, фабрика выполняется
// при первом require, а дальше отдаётся готовый модуль
function requireFor(platform: Target, modules: Record<string, () => unknown>) {
  const done = new Map<string, unknown>();
  return (request: string) => {
    const file = resolvePlatform(Object.keys(modules), request, platform);
    if (!done.has(file)) done.set(file, modules[file]());
    return done.get(file);
  };
}

// session-storage.types.ts — один тип на оба файла
interface SessionStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

// Keychain и localStorage изображены памятью, но печатают, куда пишут
function fakeStore(file: string, place: string): SessionStorage {
  console.log("выполнен", file);
  const data = new Map<string, string>();
  return {
    getItem: async (key) => data.get(key) ?? null,
    setItem: async (key, value) => void (console.log(place, "←", key), data.set(key, value)),
    removeItem: async (key) => void data.delete(key),
  };
}
// файлы проекта: путь → код модуля
const modules = {
  "./session-storage.ts": () => fakeStore("session-storage.ts", "Keychain"),
  "./session-storage.web.ts": () => fakeStore("session-storage.web.ts", "localStorage"),
};

async function build(platform: Target) {
  console.log("сборка", platform);
  const load = requireFor(platform, modules);
  const storage = load("./session-storage") as SessionStorage;
  await storage.setItem("session", "t-42");
  console.log("токен:", await storage.getItem("session"), "| тот же модуль:", load("./session-storage") === storage);
}
build("ios").then(() => build("web"));

Сборка iOS выполнила только session-storage.ts, веб — только .web.ts; чужой файл не выполнился ни разу, а в настоящей сборке его кода нет вовсе. Второй вызов load вернул тот же объект: модуль выполняется один раз, как у metroRequire. requireFor с этого места тоже лежит в подложке — в главе 6 так, сменой файла по расширению, хранилище в памяти подменится настоящей базой в телефоне.

Остался компилятор. В песочнице оба файла живут в одном объекте, и тип можно повесить на весь словарь сразу. В проекте о платформах компилятор не знает. В expo/tsconfig.base.json стоит moduleResolution: "bundler", и путь ./session-storage компилятор разрешает в session-storage.ts — телефонный файл. Веб-файл он проверит лишь на то, что тот объявил о себе сам. Проверено на копии с настройками Expo: tsc 6.0.3 разрешил импорт в телефонный файл и промолчал о веб-файле без removeItem. Поэтому у автора интерфейс вынесен в session-storage.types.ts, а каждый файл объявляет export const sessionStorage: SessionStorage: пропуск в любом из двух назовёт компилятор. У TypeScript есть и опция moduleSuffixes — например [".ios", ".native", ""], — с ней импорт разрешается так, как на iOS; но список в tsconfig один, а платформ три.

У экранов в папке app правило своё: timer.tsx, timer.ios.tsx и timer.web.tsx дают один адрес, и выбирает между ними сам expo-router. Это статья «Собираем маршруты: путь файла — это адрес» в главе 5.