Собираем маршруты: путь файла — это адрес

Свой файловый маршрутизатор из части IV ходил по дереву папок: папка — узел, особые файлы — поля узла. Next.js это может себе позволить: дерево читается при сборке на машине разработчика и на сервере. На телефон же уезжает бандл JavaScript, и никакой папки app там нет — спросить у файловой системы, какие экраны существуют, некому.

Поэтому expo-router спрашивает не файловую систему, а сборщик. Точка входа expo-router/entry через entry-classic.js доходит до build/qualified-entry.js, и там корневой компонент ExpoRoot получает пропом context объект ctx из модуля expo-router/_ctx. В самом модуле одна инструкция — вызов require.context. Это не функция рантайма, а указание Metro: при сборке обойти папку, положить в бандл подходящие файлы и оставить на месте вызова функцию с методом keys(). Вот модуль целиком, вариант для веба:

// expo-router 57.0.16 · _ctx.web.js, целиком
export const ctx = require.context(
  process.env.EXPO_ROUTER_APP_ROOT,
  true,
  /^(?:\.\/)(?!(?:(?:(?:.*\+api)|(?:\+middleware)|(?:\+(html|native-intent))))\.[tj]sx?$).*(?:\.android|\.ios|\.native)?\.[tj]sx?$/,
  process.env.EXPO_ROUTER_IMPORT_MODE
);

Первый аргумент — папка app, второй — «с подпапками», третий — фильтр путей: файлы API и корневые служебные файлы — +html, +middleware, в веб-варианте ещё +native-intent — в список не попадают. Всё остальное с расширением .js, .jsx, .ts или .tsx становится ключом — путём от папки app, с ./ в начале и расширением в конце. Заметьте имя файла: _ctx.web.js. Рядом лежат _ctx.ios.js и _ctx.android.js, и Metro, собирая бандл под платформу, берёт файл с её суффиксом — к этому приёму мы вернёмся в следующем разделе.

Так выглядит папка app настоящего приложения автора — не «Подхода», а рабочего проекта на Expo SDK 57:

$ find app -type f | sort

Здесь уже видно, чем expo-router отличается от App Router из части IV: экран — это сам файл, notes/[id].tsx, а не notes/[id]/page.tsx, и адрес папки даёт index.tsx, а не page.tsx. Адресом становится не каждый файл: _layout.tsx — обёртка, +html.tsx — служебный файл веб-сборки, а папки в скобках — группы, о них следующая статья. Остальные расхождения с частью IV — хуки параметров, служебные имена с плюсом — соберёт статья «expo-router: те же файлы, но со стеком».

В песочнице нет ни Metro, ни самого expo-router: это этаж Expo, и его пакеты сюда не собираются — об этом говорила прошлая статья. Так что require.context здесь не выполнится. Но после сборки на входе маршрутизатора всё равно лежит просто массив строк — его и возьмём. Первое правило превращает ключ в адрес: срезать ./ и расширение, служебные файлы пропустить, а index заменить адресом папки. Прогноз: что напечатает каждая из шести строк?

// ключи — как их отдаёт ctx.keys(): путь от папки app, с «./» и расширением
const keys = [
  "./index.tsx",
  "./catalog.tsx",
  "./workout/index.tsx",
  "./exercise/[id].tsx",
  "./_layout.tsx",
  "./+not-found.tsx",
];

// null — файл в папке есть, но экрана по адресу у него нет
function toHref(key: string): string | null {
  const path = key.replace(/^\.\//, "").replace(/\.[jt]sx?$/, "");
  const name = path.split("/").pop()!;
  // _layout — обёртка, а не экран (о ней следующая статья); с плюсом — служебные файлы
  if (name.startsWith("_") || name.startsWith("+")) return null;
  // index — это сама папка, как page.tsx в App Router
  return "/" + path.replace(/(^|\/)index$/, "");
}

for (const key of keys) {
  console.log(key, "→", toHref(key));
}

Корневой index.tsx дал /, а не пустую строку: выражение съело index целиком, и остался только приставленный спереди слеш. workout/index.tsx стал адресом своей папки. [id] остался в адресе как есть: это не значение, а место под значение, подставлять его будет подбор. А _layout и +not-found ответили null: файлы есть, но экранов по адресу у них нет.

Шаблон (^|\/)index$ — не перестраховка. С простым index$ файл reindex.tsx превратился бы в /re: выражение не знает, где кончается имя.

Статья «Одно приложение, три платформы» разводила код файлами .ios, .android и .web: сборщик сам брал файл своей платформы. В папке app тот же приём работает для целых экранов. timer.tsx, timer.ios.tsx и timer.web.tsx — это один адрес /timer, и каждая платформа выбирает себе файл. Правила записаны в функции getFileMeta из expo-router/build/getRoutesCore.js: файл чужой платформы пропускается целиком, файл своей точнее файла без суффикса.

Прогноз: какой файл таймера достанется iOS, Android и песочнице?

const { Platform } = ReactNative;
const EXT = /\.[jt]sx?$/;
const PLATFORM = /\.(ios|android|web)$/;

// по одному файлу на адрес — так решает getFileMeta в expo-router
function pick(keys: string[], platform: string): string[] {
  const best = new Map<string, string>();
  for (const file of keys) {
    const path = file.replace(EXT, "");
    const suffix = PLATFORM.exec(path)?.[1];
    // файл чужой платформы для этой сборки всё равно что не существует
    if (suffix !== undefined && suffix !== platform) continue;
    const name = path.replace(PLATFORM, "");
    // файл своей платформы точнее общего и вытесняет его
    if (!best.has(name) || suffix !== undefined) best.set(name, file);
  }
  return [...best.values()];
}

const files = ["./index.tsx", "./timer.tsx", "./timer.ios.tsx", "./timer.web.tsx"];
for (const platform of ["ios", "android", Platform.OS]) {
  console.log(platform, "→", pick(files, platform).join(" "));
}

Android взял общий файл: своего у него нет, а .ios и .web для него чужие. Третья строка — честный ответ песочницы: Platform.OS здесь "web", и экраном таймера в предпросмотре стал бы timer.web.tsx. Код, написанный в timer.ios.tsx, песочница не увидит никогда — так же, как Android.

Настоящий expo-router считает то же самое баллами точности: 2 — своя платформа, 0 — файл без суффикса, −1 — чужая, такой файл выбрасывается. Есть и промежуточный балл 1 для .native — его добавит третья задача. Прогон настоящего getRoutes из expo-router 57.0.16 на тех же четырёх ключах даёт то же самое: iOS получает ./timer.ios.tsx, Android — ./timer.tsx, веб — ./timer.web.tsx.

А если общего файла нет? Экран статистики сделали только для iOS — stats.ios.tsx, без пары. Функция pick из прошлого примера лежит в подложке, а сверху — проверка из getMostSpecific того же модуля expo-router, с тем же текстом ошибки. Прогноз: что будет на iOS и что на Android?

// подложка: pick из прошлого примера
declare function pick(keys: string[], platform: string): string[];
const EXT = /\.[jt]sx?$/;
const PLATFORM = /\.(ios|android|web)$/;

// проверка из getMostSpecific в expo-router: у платформенного файла обязан быть общий
function checked(keys: string[], platform: string): string[] {
  const chosen = pick(keys, platform);
  const plain = new Set(keys.map((key) => key.replace(EXT, "")));
  for (const file of chosen) {
    const name = file.replace(EXT, "").replace(PLATFORM, "");
    if (!plain.has(name)) {
      throw new Error("The file " + file + " does not have a fallback sibling file without a platform extension.");
    }
  }
  return chosen;
}

const files = ["./index.tsx", "./stats.ios.tsx"];
for (const platform of ["ios", "android"]) {
  try {
    console.log(platform, "→", checked(files, platform).join(" "));
  } catch (e) {
    console.log(platform, "→", (e as Error).message);
  }
}

Одна и та же папка, два разных исхода. На iOS сборка маршрутов падает с ошибкой, а на Android проходит молча, только экрана статистики в ней нет: stats.ios.tsx для Android чужой, выброшен ещё до проверки, и ссылка на /stats приведёт на экран «не найдено». Настоящий expo-router ведёт себя так же — прогон getRoutes дал ту же ошибку для iOS и тихую сборку без /stats для Android и веба. Разработчик с айфоном увидит ошибку и добавит общий файл, разработчик с Android не увидит ничего. Отсюда правило: у платформенного экрана всегда есть общий брат, хотя бы заглушка.

Сравните с резолвером из статьи «Одно приложение, три платформы». Там на вход приходил запрос — ./rest-sound, — и resolvePlatform искал под него один файл: звук, сделанный только в .ios и .android, на обоих телефонах находился, а останавливалась сборка веба, где подходящего файла нет. У маршрутизатора запроса нет. Ему отдают весь список, и он сам решает, какие адреса существуют, поэтому правило перевёрнуто: ошибку получает платформа, у которой файл есть, а та, у которой его нет, об экране просто не узнаёт. По той же причине resolvePlatform не поехал в подложку этой статьи — он отвечает на другой вопрос.

Два общих файла на один адрес — timer.tsx и timer.jsx — expo-router в разработке тоже не прощает: ошибка «The route files … conflict on the route "/timer"». В продакшн-сборке проверка выключена, и молча берётся первый найденный.

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

Прогноз: что найдётся по каждому из пяти адресов?

// подложка: toHref из первого примера
type Params = Record<string, string>;
type Route = { file: string; parts: string[] };
type Found = { file: string; params: Params };
declare function toHref(key: string): string | null;

const keys = ["./index.tsx", "./catalog.tsx", "./workout/index.tsx", "./exercise/[id].tsx", "./_layout.tsx"];
// плоская таблица: файл и его адрес, разрезанный на сегменты
const routes: Route[] = keys.flatMap((file) => {
  const href = toHref(file);
  return href === null ? [] : [{ file, parts: href.split("/").filter(Boolean) }];
});

function match(routes: Route[], url: string): Found | null {
  const segments = url.split("/").filter(Boolean);
  for (const route of routes) {
    if (route.parts.length !== segments.length) continue;
    const params: Params = {};
    const fits = route.parts.every((part, i) => {
      const name = /^\[(.+)\]$/.exec(part)?.[1];
      if (name === undefined) return part === segments[i];
      // адрес мог прийти ссылкой снаружи — с %D0%B6 вместо «ж»
      params[name] = decodeURIComponent(segments[i]!);
      return true;
    });
    if (fits) return { file: route.file, params };
  }
  return null;
}

for (const url of ["/", "/exercise/squat", "/workout/", "/exercise", "/exercise/squat/history"]) {
  const found = match(routes, url);
  if (found === null) console.log(url, "→ не найден");
  else console.log(url, "→", found.file, found.params);
}

/workout/ нашёлся: пустые куски после разрезания отброшены, и хвостовой слеш ничего не меняет. /exercise и /exercise/squat/history — нет: сегмент в скобках принимает что угодно, но ровно один кусок, и число сегментов обязано совпасть. Для «всего остального хвоста» есть отдельный вид скобок, [...rest], — это первая задача.

И обратите внимание на тип: params.id — строка, даже если в адресе было число. Разбирать и проверять значение — дело экрана, а не маршрутизатора; так было и в части IV. Одно отличие от Next.js всё же есть: там params приходил промисом, а expo-router отдаёт параметры экрану сразу, хуком. Каким именно из двух — разберёт статья «expo-router: те же файлы, но со стеком».

Добавим в «Подход» экран нового упражнения — exercise/new.tsx рядом с exercise/[id].tsx. Адрес /exercise/new подходит под оба файла: под первый буквально, под второй с id, равным "new". В части IV этот спор решал порядок двух проверок при спуске по дереву: сначала буквальная папка, потом переменная. Здесь дерева нет, а match берёт первое совпадение в таблице. Значит, всё решает порядок строк — а он пока такой, в каком пришли ключи.

Прогноз: ключи отсортированы по алфавиту. Что найдёт match по /exercise/new в неотсортированной таблице и в отсортированной?

// подложка: toHref из первого примера и match из прошлого
type Params = Record<string, string>;
type Route = { file: string; parts: string[] };
type Found = { file: string; params: Params };
declare function toHref(key: string): string | null;
declare function match(routes: Route[], url: string): Found | null;

const keys = ["./index.tsx", "./exercise/new.tsx", "./exercise/[id].tsx"].sort();
const table: Route[] = keys.flatMap((file) => {
  const href = toHref(file);
  return href === null ? [] : [{ file, parts: href.split("/").filter(Boolean) }];
});

const dynamic = (route: Route) => route.parts.filter((part) => part.startsWith("[")).length;
// меньше скобок — выше; sort устойчив, равные остаются в прежнем порядке
const sorted = [...table].sort((a, b) => dynamic(a) - dynamic(b));

console.log(keys);
console.log(match(table, "/exercise/new"));
console.log(match(sorted, "/exercise/new"));
console.log(match(sorted, "/exercise/squat"));

В неотсортированной таблице /exercise/new открыл карточку упражнения с id, равным "new": ни ошибки, ни предупреждения, просто не тот экран. Виноват алфавит: [ в таблице символов стоит раньше строчных букв, и [id] оказался в списке первым. После сортировки буквальный маршрут встал выше, а /exercise/squat по-прежнему достался карточке — new.tsx на него не подходит.

Миниатюра сортирует таблицу один раз, когда её собирает: порядок у неё зависит только от файлов. Правило у expo-router то же. Его функция сравнения лежит в build/fork/getStateFromPath-forks.js, и одно из первых её правил записано прямо комментарием — статичные маршруты всегда выше динамических. Дальше идут уточнения: у кого больше статичных сегментов, тот выше, а хвост [...rest] — в самом конце. А вот момент сортировки другой. Среди уточнений есть «при равенстве выше маршрут из той группы, где человек сейчас», поэтому порядок зависит ещё и от текущего экрана. Кеш в build/fork/getStateFromPath.js потому закомментирован — с пометкой, что конфиги меняются вместе с состоянием, — и таблица пересортировывается при каждом разборе адреса. Наше «меньше скобок — выше» — упрощение того же правила: буквальный маршрут оно ставит выше динамического, а маршруты с равным числом скобок оставляет в том порядке, в каком пришли ключи. expo-router сравнивает и их — сегмент за сегментом, слева направо: из a/[b] и [a]/b адрес /a/b у него всегда достаётся первому, а в миниатюре — тому, что раньше в списке ключей. Для «Подхода» этого хватает: таких пар в нём нет.

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

Осталось поставить таблицу на место if из прошлой статьи. Миниатюра этой статьи — выбор файла платформы, адреса, отсортированная таблица и подбор — уехала в подложку двумя функциями: routesFrom(keys, platform) и match(routes, url); целиком она в свёртке ниже. Экраны Catalog, Workout и Card — те же, что в прошлой статье. А модель require.context — обычный объект: путь файла → компонент, который файл экспортирует по умолчанию.

В состоянии корня теперь лежит не имя экрана, а адрес — строка (сама ячейка состояния — как в части IV). Экран получает params и функцию go, а объект router позволяет перейти по адресу снаружи React — так это сделает обработчик нажатия на уведомление. Прогноз: какие пять строк напечатает корень?

// подложка: справочник и экраны Catalog, Workout, Card из прошлой статьи,
// а также миниатюра этой статьи — routesFrom и match (целиком она в свёртке ниже)
type Params = Record<string, string>;
type Route = { file: string; parts: string[] };
type Found = { file: string; params: Params };
interface ListProps {
  open: (id: string) => void;
}
interface CardProps {
  id: string;
  back: () => void;
}
declare function Catalog(props: ListProps): React.ReactElement;
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;
const { Text, Platform } = ReactNative;

interface ScreenProps {
  params: Params;
  go: (url: string) => void;
}

// модель require.context: путь файла → то, что файл экспортирует по умолчанию
const app: Record<string, (props: ScreenProps) => React.ReactElement> = {
  "./index.tsx": ({ go }) => <Workout open={(id) => go("/exercise/" + id)} />,
  "./catalog.tsx": ({ go }) => <Catalog open={(id) => go("/exercise/" + id)} />,
  "./exercise/[id].tsx": ({ params, go }) => <Card id={params.id} back={() => go("/")} />,
};
const routes = routesFrom(Object.keys(app), Platform.OS);

// переход снаружи React — так его сделает обработчик нажатия на уведомление
const router = { push: (_url: string) => {} };

function Root() {
  const [url, setUrl] = React.useState("/");
  React.useEffect(() => {
    router.push = setUrl;
  }, []);
  const found = match(routes, url);
  console.log(url, "→", found === null ? "не найден" : found.file);
  if (found === null) return <Text>Экран не найден</Text>;
  const Screen = app[found.file];
  return <Screen params={found.params} go={setUrl} />;
}

mount(<Root />);
setTimeout(() => fireEvent.press("row-bench"), 100);
setTimeout(() => fireEvent.press("back"), 200);
setTimeout(() => router.push("/exercise/deadlift"), 300);
setTimeout(() => router.push("/exercise/deadlift/history"), 400);

Все пять переходов — одна и та же операция: адрес → match → файл → компонент. Строке тренировки и уведомлению не нужно знать, как устроено приложение, — только адрес. Закрылась последняя строка таблицы требований из прошлой статьи: у каждого экрана есть имя, и по имени на него можно попасть снаружи. Незнакомый адрес не роняет приложение, а даёт экран «не найдено» — в expo-router это файл +not-found.tsx, а если его нет, системный экран.

Остальные строки той таблицы на месте. «‹ Назад» в карточке зашита на go("/") и снова не знает, откуда пришли; справочник по-прежнему размонтируется при уходе — в состоянии лежит один адрес, а не список. А ещё у каждого экрана своя шапка там, где нужна общая: вкладки «Тренировка» и «Справочник» пришлось бы рисовать в каждом файле. Этим займутся следующие две статьи — сначала раскладки _layout, потом стек с историей.

type Params = Record<string, string>;
type Route = { file: string; parts: string[] };
type Found = { file: string; params: Params };
const { Platform } = ReactNative;

const EXT = /\.[jt]sx?$/;
const PLATFORM = /\.(ios|android|web)$/;

// путь файла → адрес; null — файл есть, а экрана по адресу у него нет
function toHref(key: string): string | null {
  const path = key.replace(/^\.\//, "").replace(EXT, "").replace(PLATFORM, "");
  const name = path.split("/").pop()!;
  if (name.startsWith("_") || name.startsWith("+")) return null;
  return "/" + path.replace(/(^|\/)index$/, "");
}

// по одному файлу на адрес: своя платформа точнее общего, чужой файл не существует,
// а платформенный файл без общего — ошибка, как в expo-router
function pick(keys: string[], platform: string): string[] {
  const best = new Map<string, string>();
  const plain = new Set<string>();
  for (const file of keys) {
    const path = file.replace(EXT, "");
    const suffix = PLATFORM.exec(path)?.[1];
    if (suffix !== undefined && suffix !== platform) continue;
    const name = path.replace(PLATFORM, "");
    if (suffix === undefined) plain.add(name);
    if (!best.has(name) || suffix !== undefined) best.set(name, file);
  }
  for (const [name, file] of best) {
    if (!plain.has(name)) {
      throw new Error("The file " + file + " does not have a fallback sibling file without a platform extension.");
    }
  }
  return [...best.values()];
}

// таблица собирается и сортируется один раз: меньше скобок — выше
function routesFrom(keys: string[], platform: string): Route[] {
  const dynamic = (route: Route) => route.parts.filter((part) => part.startsWith("[")).length;
  return pick(keys, platform)
    .flatMap((file) => {
      const href = toHref(file);
      return href === null ? [] : [{ file, parts: href.split("/").filter(Boolean) }];
    })
    .sort((a, b) => dynamic(a) - dynamic(b));
}

function match(routes: Route[], url: string): Found | null {
  const segments = url.split("/").filter(Boolean);
  for (const route of routes) {
    if (route.parts.length !== segments.length) continue;
    const params: Params = {};
    const fits = route.parts.every((part, i) => {
      const name = /^\[(.+)\]$/.exec(part)?.[1];
      if (name === undefined) return part === segments[i];
      params[name] = decodeURIComponent(segments[i]!);
      return true;
    });
    if (fits) return { file: route.file, params };
  }
  return null;
}

const keys = ["./_layout.tsx", "./index.tsx", "./exercise/[id].tsx", "./exercise/new.tsx", "./timer.tsx", "./timer.ios.tsx", "./timer.web.tsx", "./+not-found.tsx"];
const routes = routesFrom(keys, Platform.OS);
console.log(routes.map((route) => route.file));
console.log(match(routes, "/exercise/new"));
console.log(match(routes, "/timer"));