expo-router: те же файлы, но со стеком

В миниатюре экраны лежат в объекте app: ключ — путь файла, значение — компонент. В проекте на Expo этот объект никто не пишет. Ключи — настоящие файлы в папке app, а сам объект при сборке собирает Metro по require.context — это показала статья «Собираем маршруты». Поэтому переезд почти механический: каждый ключ становится файлом, каждое значение — его export default.

Корневая раскладка остаётся раскладкой, только Stack в ней теперь настоящий. expo-router — этаж Expo, в песочницу он не собирается, так что его файлы в этой статье — листинги:

// app/_layout.tsx — корневая раскладка «Подхода»: на месте Slot стоит стек
import { Stack } from "expo-router";

export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="exercise/[id]" options={{ title: "Упражнение" }} />
    </Stack>
  );
}

Имена в Stack.Screen считаются тем же правилом, что во второй задаче статьи «Раскладки и Slot»: относительно папки раскладки. Группа (tabs) со своей раскладкой видна корню одним ребёнком, а карточка — путём exercise/[id]. Сами маршруты перечислять не нужно, их даёт папка; Stack.Screen только настраивает экран. Шапку с кнопкой «назад» нативный стек рисует сам, поэтому «‹ Назад» из карточки миниатюры в настоящий файл не переезжает:

// app/exercise/[id].tsx — карточка упражнения; справочник — модуль проекта, как EXERCISES в подложке
import { router, useLocalSearchParams } from "expo-router";
import { Pressable, Text, View } from "react-native";
import { findExercise, similarTo } from "@/features/catalog";

export default function ExerciseScreen() {
  // параметры не приходят пропом: экран спрашивает их сам, и ответ — про его запись в стеке
  const { id } = useLocalSearchParams<{ id: string }>();
  const ex = findExercise(id);
  const next = similarTo(id);
  return (
    <View style={{ gap: 8 }}>
      <Text style={{ fontSize: 20 }}>{ex.name}</Text>
      <Text>группа: {ex.group}</Text>
      <Pressable onPress={() => router.push(`/exercise/${next.id}`)}>
        <Text>похожее: {next.name}</Text>
      </Pressable>
    </View>
  );
}

Отличий от миниатюры в этом файле два. nav.push стал router.push — объектом переходов, который expo-router экспортирует для вызова откуда угодно, в том числе снаружи React. И экран больше ничего не получает пропсами: у миниатюры в них лежали params и nav, а настоящий экран вызывают без них. В build/useScreens.js обёртка BaseRoute нарочно вынимает из пропсов route и navigation, которые передаёт react-navigation. Комментарий рядом объясняет причину: параметры должны читаться хуками, потому что строка запроса правильная только у них. Каких хуков два и чем они различаются — следующий раздел.

Листинги статьи в песочнице не запустить, зато их проверил tsc 6.0.3 на настоящих типах expo-router 57.0.16 и react-native 0.86 — ни одной ошибки. Чтобы убедиться, что проверка смотрит в эти типы, а не в пустоту, рядом положили пробный файл с тремя заведомыми ошибками: router.push(42), опечатка nme в Stack.Screen и toFixed у строкового id. Нашлись все три.

Вкладки в expo-router 57 берут из expo-router/js-tabs: у Tabs из самого expo-router в типах стоит @deprecated с этой подсказкой. В приложении автора импорт ещё старый — работает, но редактор его зачёркивает.

В части IV параметры приходили странице пропом params, а с Next.js 15 — промисом, который ждали через await или use(); из глубины дерева их доставал useParams(). Вопроса «чьи это параметры» там не возникало: адрес один на всё окно, и страница на экране одна. В expo-router пропа нет, а хуков два. useLocalSearchParams() отвечает параметрами той записи стека, в которой стоит компонент. useGlobalSearchParams() — параметрами экрана, который сейчас в фокусе. Пока экран один, ответы совпадают. Стек из прошлой статьи их разводит: две карточки одного файла exercise/[id].tsx смонтированы одновременно.

В миниатюре оба хука — контексты (как в части IV). Свой Provider стоит вокруг каждой записи стека со значением её параметров, общий — один над всем стеком, со значением верхней записи. Подложка — справочник, экраны, маршрутизатор, стек useStack и подписка useBackButton из прошлых статей. Карточка отмечает в эффекте, для какого id он сработал: в настоящем экране на этом месте загружались бы подходы. Прогноз: человек открывает жим лёжа, оттуда похожее упражнение и жмёт системную «назад». Сколько раз сработает эффект нижней карточки и с какими id?

// подложка: справочник, экраны Workout и Card, маршрутизатор, стек useStack
// и подписка useBackButton из прошлых статей
type Params = Record<string, string>;
type Route = { file: string; parts: string[]; layouts: string[] };
type Found = { file: string; params: Params; layouts: string[] };
type Entry = { key: string; url: string };
interface ListProps {
  open: (id: string) => void;
}
interface CardProps {
  id: string;
  back: () => void;
  open?: (id: string) => void;
}
interface Nav {
  push: (url: string) => void;
  back: () => boolean;
  replace: (url: string) => void;
}
interface ScreenProps {
  params: Params;
  nav: Nav;
}
type Files = Record<string, (props: ScreenProps) => React.ReactNode>;
declare function Workout(props: ListProps): React.ReactElement;
declare function Card(props: CardProps): React.ReactElement;
declare function routesFrom(keys: string[], platform: string): Route[];
declare function match(routes: Route[], url: string): Found | null;
declare function renderRoute(app: Files, found: Found, nav: Nav): React.ReactNode;
declare function useStack(first: string): [Entry[], Nav];
declare function useBackButton(nav: Nav): void;
declare function pressSystemBack(): void;
const { View, Platform } = ReactNative;

// свои параметры — у каждой записи стека, общие — у верхней
const LocalParams = React.createContext<Params>({});
const GlobalParams = React.createContext<Params>({});
const useLocalSearchParams = () => React.useContext(LocalParams);
const useGlobalSearchParams = () => React.useContext(GlobalParams);

function CardScreen({ nav }: ScreenProps) {
  const local = useLocalSearchParams();
  const global = useGlobalSearchParams();
  // на месте строки будет загрузка подходов — эффект видно по тому, для какого id он сработал
  React.useEffect(() => {
    console.log(`карточка ${local.id}: local ${local.id}, global ${global.id}`);
  }, [local.id, global.id]);
  return <Card id={local.id} back={() => nav.back()} open={(id) => nav.push("/exercise/" + id)} />;
}

const app: Files = {
  "./index.tsx": ({ nav }) => <Workout open={(id) => nav.push("/exercise/" + id)} />,
  "./exercise/[id].tsx": CardScreen,
};
const routes = routesFrom(Object.keys(app), Platform.OS);

function Root() {
  const [stack, nav] = useStack("/");
  useBackButton(nav);
  const found = stack.map((e) => match(routes, e.url)!);
  return (
    <GlobalParams.Provider value={found[found.length - 1]!.params}>
      {stack.map((e, i) => (
        <View key={e.key} style={{ display: i === stack.length - 1 ? "flex" : "none" }}>
          <LocalParams.Provider value={found[i]!.params}>{renderRoute(app, found[i]!, nav)}</LocalParams.Provider>
        </View>
      ))}
    </GlobalParams.Provider>
  );
}

mount(<Root />);
setTimeout(() => fireEvent.press("row-bench"), 100);
setTimeout(() => fireEvent.press("similar"), 200);
setTimeout(pressSystemBack, 300);

Нижнюю карточку никто не трогал, а её эффект сработал ещё дважды: сперва для наклонной скамьи, потом снова для жима. Строки «local» в ней не меняются — это её собственный адрес. Строка «global» отвечает на другой вопрос — где человек сейчас. Появилась карточка сверху — и нижняя увидела чужой id. Будь в эффекте загрузка подходов, спрятанная карточка жима загрузила бы в себя историю наклонной скамьи. Верхняя карточка при этом вела бы себя безупречно, так что ошибку искали бы долго.

Настоящие хуки устроены так же, как миниатюра. Каждый экран expo-router оборачивает в компонент Route, и тот кладёт в контекст параметры именно этой записи. useLocalSearchParams читает этот контекст. А useGlobalSearchParams идёт в общее хранилище роутера:

// expo-router 57.0.16 · build/Route.js и build/hooks/useGlobalSearchParams.js, фрагменты
function Route({ children, node, params }) {
    return ((0, jsx_runtime_1.jsx)(exports.LocalRouteParamsContext.Provider, { value: params, children: (0, jsx_runtime_1.jsx)(CurrentRouteContext.Provider, { value: node, children: children }) }));
}
function useGlobalSearchParams() {
    return (0, useRouteInfo_1.useRouteInfo)().params;
}

useRouteInfo подписан на хранилище через useSyncExternalStore (как в статье «Свой хук» части IV), поэтому компонент с глобальными параметрами перерисовывается при любом переходе, в фокусе он или нет. А заморозки нижних экранов в expo-router по умолчанию нет — об этом прошлая статья. Так что на телефоне нижняя карточка повела бы себя как в песочнице. Описание хука в его .d.ts говорит то же своими словами: хук обновляется и вне фокуса, годится для аналитики и фоновой работы, а в стеке советует брать локальные параметры. Отсюда правило: экран читает useLocalSearchParams, а useGlobalSearchParams остаётся тому, кто стоит над стеком, — это вторая задача.

Строку запроса миниатюра пока не разбирает вовсе — ?set=3 прилипает к последнему сегменту. Как expo-router смешивает запрос с сегментами пути и кто из них главнее, выясняет первая задача.

В части IV служебные файлы назывались обычными словами — page, layout, loading, error, not-found, route, — и их список приходилось знать наизусть. expo-router помечает их первым символом. Подчёркивание — у раскладки _layout и у системного _sitemap. Плюс — у файлов, которые не становятся обычными экранами. Уже toHref в статье «Собираем маршруты» отвечала null на оба префикса. Теперь разберём, что стоит за плюсом:

Четыре нижних файла экранами не становятся. +html, +api и +middleware отсекает ещё выражение в require.context — то, что статья «Собираем маршруты» показывала для веба; в _ctx.ios.js и _ctx.android.js оно отсекает те же три. +native-intent в бандл телефона попадает — там он и нужен, — но getRoutes держит его в списке исключений вместе с корневым +html. Плюс в начале имени — не пожелание, а правило. Прогон настоящего getRoutes на ключе ./+stats.tsx падает с ошибкой «Invalid route ./+stats.tsx. Route nodes cannot start with the '+' character. "Rename it to stats.tsx"». С той же ошибкой падает и ./exercise/+html.tsx: вне корня +html — просто запрещённое имя. Исключение сделано ровно одно — для +not-found, это прямо написано в комментарии к проверке.

Почему +not-found — экран, а не служебная ветка в подборе? Потому что getRoutes превращает его в обычный динамический сегмент — хвост вида [...rest] из первой задачи статьи «Собираем маршруты». Имя параметра у хвоста — not-found, без плюса. При сортировке маршрутов у него своя ветка в getStateFromPath-forks.js: он проигрывает даже обычному хвосту [...rest], так что достаётся ему только то, что не взял никто. Если своего +not-found в app нет, getRoutes добавляет системный — вместе с системным _sitemap. В миниатюре хвост удобнее вынести в запасную функцию notFound: она вызывается, когда match не нашёл ничего. Прогноз: в корне и в папке exercise лежит по своему +not-found.tsx. Что откроется по каждому из четырёх адресов?

// подложка: маршрутизатор прошлых статей — +not-found адресом у него не становится
type Params = Record<string, string | string[]>;
type Route = { file: string; parts: string[]; layouts: string[] };
type Found = { file: string; params: Params; layouts: string[] };
declare function routesFrom(keys: string[], platform: string): Route[];
declare function match(routes: Route[], url: string): Found | null;
declare function layoutsOf(file: string, keys: string[]): string[];

const keys = [
  "./_layout.tsx",
  "./(tabs)/_layout.tsx",
  "./(tabs)/index.tsx",
  "./(tabs)/catalog.tsx",
  "./exercise/[id].tsx",
  "./exercise/+not-found.tsx",
  "./+not-found.tsx",
];
const routes = routesFrom(keys, "ios");

// +not-found — хвост своей папки, как [...rest]: ловит то, что под ней не нашлось
function notFound(keys: string[], url: string): Found | null {
  const segments = url.split("/").filter(Boolean);
  let best: { file: string; depth: number } | null = null;
  for (const file of keys) {
    const path = /^\.\/(.*)\+not-found\.[jt]sx?$/.exec(file)?.[1];
    if (path === undefined) continue;
    // группы в адрес не входят и здесь
    const dir = path.split("/").filter((part) => part !== "" && !/^\(.+\)$/.test(part));
    const fits = segments.length > dir.length && dir.every((part, i) => part === segments[i]);
    // из подходящих берётся самая глубокая папка
    if (fits && (best === null || dir.length > best.depth)) best = { file, depth: dir.length };
  }
  if (best === null) return null;
  return { file: best.file, params: { "not-found": segments.slice(best.depth) }, layouts: layoutsOf(best.file, keys) };
}

for (const url of ["/exercise/bench", "/exercise/bench/history", "/exercise", "/workout/7"]) {
  const found = match(routes, url) ?? notFound(keys, url);
  console.log(url, "→", found?.file, found?.params);
}

Экрана истории подходов ещё нет, и /exercise/bench/history достался ближайшему +not-found — тому, что в папке exercise, с хвостом ["bench", "history"]. А /exercise ушёл в корень, хотя папка та же: хвосту нужен хотя бы один сегмент после своей папки, как и [...rest]. Настоящие getRoutes и getStateFromPath из expo-router 57.0.16 на тех же ключах ответили точно так же, вплоть до массивов в параметре not-found. В самом файле хвост читают тем же хуком, что и id:

// app/+not-found.tsx — экран для адреса, которого нет
import { Link, Stack, useLocalSearchParams } from "expo-router";
import { Text, View } from "react-native";

export default function NotFoundScreen() {
  // хвост адреса приходит массивом, и имя параметра — без плюса
  const params = useLocalSearchParams<{ "not-found": string[] }>();
  return (
    <View>
      <Stack.Screen options={{ title: "Не найдено" }} />
      <Text>Экрана /{params["not-found"]?.join("/")} нет</Text>
      <Link href="/">К тренировке</Link>
    </View>
  );
}

Stack.Screen внутри экрана задаёт ему заголовок в шапке стека, а Link — переход по адресу. Файлов error.tsx и loading.tsx в expo-router нет, их роли достались экспортам из файла маршрута. Если файл экспортирует функцию ErrorBoundary, useScreens.js оборачивает экран границей ошибок с ней в роли запасной разметки; пропсы у неё — error и retry. Раскладка может экспортировать SuspenseFallback: в синхронном режиме импорта, который включён по умолчанию, это запасная разметка для Suspense, которым useScreens.js оборачивает саму раскладку и, через контекст, её дочерние экраны. Граница ошибок и Suspense те же, что в части IV, изменилось только место, где их объявляют.

Страница в app Next.js по умолчанию была серверным компонентом: асинхронная функция, await params, запрос в базу прямо в теле, а 'use client' отмечал границу. У expo-router этой границы нет. На телефоне нет сервера, который отрисовал бы экран заранее: весь бандл уже на устройстве, и каждый файл в app — обычный клиентский компонент, как все примеры части. 'use client' писать не нужно, асинхронным экран быть не может. Опаснее всего привычка из части IV — страница, которая ждёт данные сама. Прогноз: что будет, если смонтировать такой экран? Появится название упражнения, ошибка или что-то третье? И сколько раз React вызовет функцию — один, два или много?

const { Text } = ReactNative;

let calls = 0;
// привычка из части IV: страница — асинхронная функция, данные ждут прямо в ней
async function ExerciseScreen() {
  calls += 1;
  const ex = await Promise.resolve({ name: "Жим штанги лёжа" });
  return <Text>{ex.name}</Text>;
}

mount(<ExerciseScreen />);
setTimeout(() => console.log("экран вызван раз:", calls), 1000);

Компилятор промолчал: типы React 19 разрешают асинхронный компонент, ведь где он выполнится, им неизвестно. Возражает рантайм. Первая строка — предупреждение React: асинхронными пока бывают только серверные компоненты. Дальше React обошёлся с возвращённым промисом как с неготовым значением в use(): приостановил отрисовку, дождался и вызвал функцию снова. Но каждый вызов создаёт новый промис, и круг не замыкается. Считает React не вызовы, а приостановки корня, и когда их становится больше ста — в его коде стоит проверка 100 < shellSuspendCounter, — сдаётся и бросает ошибку. Браузер прячет её текст, песочница говорит об этом строкой «Uncaught». Тот же пример в кадре без изоляции показал текст целиком: «An unknown Component is an async Client Component…» — первое предупреждение, только уже ошибкой и без имени компонента. Последней React добавляет свою строку «An error occurred in the <ExerciseScreen> component». Вместо Promise.resolve мог стоять запрос в сеть — 104 запроса за одно открытие экрана.

На телефоне будет то же самое: это проверка React, а не браузера. В рендерере React Native 0.86, ReactFabric-dev.js, есть и предупреждение про «async Client Component», и тот же предел в сотню приостановок корня. Данные экрану нужно не ждать в теле функции, а получать хуком — через use() с Suspense или эффектом, как в части IV. У «Подхода» есть путь проще: его данные живут на самом телефоне, и хранилище, которое читается за один такт, соберёт следующая глава.

Сервер у Expo всё же бывает — для веба. Файлы +api.ts — это код для сервера, как route.ts, только к экранам он отношения не имеет. А серверные компоненты в Expo — эксперимент: в app.json есть флаги experiments.reactServerComponentRoutes и experiments.reactServerFunctions, и описание обоих в типах конфига Expo 57 начинается со слова «Experimentally». «Подход» их не включает.

Сверим миниатюру с настоящим маршрутизатором по частям. Каждую строку этой таблицы глава собрала руками, и каждую проверила прогоном настоящего кода expo-router 57.0.16:

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

// подложка: справочник, экраны, вкладки TabBar, маршрутизатор прошлых статей,
// стек useStack с подпиской useBackButton и модель backHandler
type Params = Record<string, string | string[]>;
type Route = { file: string; parts: string[]; layouts: string[] };
type Found = { file: string; params: Params; layouts: string[] };
type Entry = { key: string; url: string };
interface ListProps {
  open: (id: string) => void;
}
interface CardProps {
  id: string;
  back: () => void;
}
interface Nav {
  push: (url: string) => void;
  back: () => boolean;
  replace: (url: string) => void;
}
interface ScreenProps {
  params: Params;
  nav: Nav;
}
type Files = Record<string, (props: ScreenProps) => React.ReactNode>;
interface NavigatorProps {
  app: Files;
  first: string;
}
declare function Workout(props: ListProps): React.ReactElement;
declare function Card(props: CardProps): React.ReactElement;
declare function TabBar(props: { nav: Nav }): React.ReactElement;
declare function Slot(): React.ReactNode;
declare function routesFrom(keys: string[], platform: string): Route[];
declare function match(routes: Route[], url: string): Found | null;
declare function layoutsOf(file: string, keys: string[]): string[];
declare function renderRoute(app: Files, found: Found, nav: Nav): React.ReactNode;
declare function useStack(first: string): [Entry[], Nav];
declare function useBackButton(nav: Nav): void;
declare function pressSystemBack(): void;
const { View, Text, Pressable, Platform } = ReactNative;

// Stack рисует корневая раскладка — на его место встают все записи истории
const StackContext = React.createContext<React.ReactNode>(null);
function Stack() {
  return React.useContext(StackContext);
}

// свои параметры — у каждой записи стека, общие — у верхней
const LocalParams = React.createContext<Params>({});
const GlobalParams = React.createContext<Params>({});
function useLocalSearchParams<T extends Params = Params>() {
  return React.useContext(LocalParams) as T;
}
function useGlobalSearchParams<T extends Params = Params>() {
  return React.useContext(GlobalParams) as T;
}

// +not-found — хвост своей папки: ловит всё, что под ней не нашлось, но хотя бы один сегмент
function notFound(keys: string[], url: string): Found | null {
  const segments = url.split("/").filter(Boolean);
  let best: { file: string; depth: number } | null = null;
  for (const file of keys) {
    const path = /^\.\/(.*)\+not-found\.[jt]sx?$/.exec(file)?.[1];
    if (path === undefined) continue;
    const dir = path.split("/").filter((part) => part !== "" && !/^\(.+\)$/.test(part));
    const fits = segments.length > dir.length && dir.every((part, i) => part === segments[i]);
    if (fits && (best === null || dir.length > best.depth)) best = { file, depth: dir.length };
  }
  if (best === null) return null;
  return { file: best.file, params: { "not-found": segments.slice(best.depth) }, layouts: layoutsOf(best.file, keys) };
}

function Navigator({ app, first }: NavigatorProps) {
  const keys = Object.keys(app);
  const routes = React.useMemo(() => routesFrom(keys, Platform.OS), [app]);
  const [stack, nav] = useStack(first);
  useBackButton(nav);
  // адрес, которому не нашлось даже +not-found, получает системный экран, как в expo-router
  const found = stack.map((e) => match(routes, e.url) ?? notFound(keys, e.url));
  const screens = stack.map((e, i) => {
    const f = found[i];
    // корневая раскладка рисуется одна, над стеком; в запись идёт цепочка ниже неё
    const layouts = f?.layouts[0] === "./_layout.tsx" ? f.layouts.slice(1) : (f?.layouts ?? []);
    return (
      <View key={e.key} style={{ display: i === stack.length - 1 ? "flex" : "none" }}>
        <LocalParams.Provider value={f?.params ?? {}}>
          {f ? renderRoute(app, { ...f, layouts }, nav) : <Text>Экран не найден</Text>}
        </LocalParams.Provider>
      </View>
    );
  });
  const RootLayout = app["./_layout.tsx"] ?? Stack;
  return (
    <GlobalParams.Provider value={found[found.length - 1]?.params ?? {}}>
      <StackContext.Provider value={screens}><RootLayout params={{}} nav={nav} /></StackContext.Provider>
    </GlobalParams.Provider>
  );
}

function CardScreen({ nav }: ScreenProps) {
  const { id } = useLocalSearchParams<{ id: string }>();
  React.useEffect(() => console.log("карточка:", id), [id]);
  return (
    <View>
      <Card id={id} back={() => nav.back()} />
      <Pressable testID="history" onPress={() => nav.push("/exercise/" + id + "/history")}>
        <Text>история подходов</Text>
      </Pressable>
    </View>
  );
}

function NotFoundScreen() {
  const tail = useLocalSearchParams<{ "not-found": string[] }>()["not-found"].join("/");
  React.useEffect(() => console.log("не найдено:", tail), [tail]);
  return <Text>Такого экрана пока нет</Text>;
}

const app: Files = {
  "./_layout.tsx": () => <View style={{ gap: 8 }}><Text style={{ fontSize: 18 }}>Подход</Text><Stack /></View>,
  "./(tabs)/_layout.tsx": ({ nav }) => <View><TabBar nav={nav} /><Slot /></View>,
  "./(tabs)/index.tsx": ({ nav }) => <Workout open={(id) => nav.push("/exercise/" + id)} />,
  "./exercise/[id].tsx": CardScreen,
  "./exercise/+not-found.tsx": NotFoundScreen,
};

mount(<Navigator app={app} first="/" />);
setTimeout(() => fireEvent.press("row-bench"), 100);
setTimeout(() => fireEvent.press("history"), 200);
setTimeout(pressSystemBack, 300);
setTimeout(pressSystemBack, 400);
setTimeout(pressSystemBack, 500);