Файловая маршрутизация в Next.js App Router

Зачем это нужно: проблематика и архитектурный контекст#

Маршрутизация — это архитектурный скелет веб-приложения, определяющий, как URL сопоставляется с кодом, данными и компонентами. В традиционных клиентских клиентских SPA (на базе react-router) навигация строится вокруг централизованного конфигурационного объекта или декларативных деревьев компонентов. При масштабировании проекта такой подход порождает критические системные ограничения:

• Мерж-конфликты централизации: Единый конфигурационный файл маршрутов превращается в точку постоянных конфликтов в распределённых командах.
• Ручной Code Splitting: Разделение кода (Code Splitting) требует постоянной ручной поддержки динамических импортов (React.lazy), что при малейшей ошибке приводит к утечке лишних модулей в начальный бандл.
• Утечка серверной логики: Клиентский роутер вынужден загружать в браузер код, который мог бы выполняться исключительно на сервере (запросы к БД, Markdown-парсеры, секретные токены).
• Сброс состояния при переходах: Сложно гранулярно сохранять состояние родительских оболочек без лишних повторных рендеров всего дерева компонентов.

Next.js App Router кардинально меняет парадигму с помощью файловой маршрутизации (file-based routing). Структура файловой системы внутри директории app напрямую компилируется сборщиком Turbopack в граф маршрутов приложения. Это исключает необходимость в ручных реестрах путей, гарантирует изоляцию страниц, реализует автоматический code splitting по сегментам и обеспечивает нулевой размер клиентского бандла (Zero-Bundle Size) для серверных компонентов по умолчанию.

Ментальная модель: топологический анализ сегментов#

В парадигме App Router базовой структурной единицей является сегмент маршрута (Route Segment). Каждая вложенная папка внутри директории app представляет собой отдельный сегмент URL.

Например, папка app/dashboard/settings точно соответствует URL-пути /dashboard/settings. Однако само по себе создание папок не делает их общедоступными адресами. Сегмент превращается в доступный маршрут только тогда, когда внутри папки появляется специальный файл — page.tsx. Если page.tsx отсутствует, сегмент остаётся служебной веткой дерева и используется исключительно для группировки маршрутов или наследования общих интерфейсных обёрток.

Каждый сегмент изолирован и гарантирует сохранение состояния (Preserved State): родительские макеты не перерисовываются заново при смене дочерних страниц, а дочерние данные передаются в виде дифференциального потока React Server Components.

3. Алгоритм исполнения и жизненный цикл (Runtime Execution)#

Процесс разрешения маршрута от клика пользователя по ссылке до финального обновления DOM-дерева в браузере строго регламентирован конвейером Turbopack и потоковым движком React 19:

4. Спецификация контрактов файловой системы и API#

Next.js наделяет файлы с фиксированными именами специализированными системными ролями. Компилятор Turbopack автоматически преобразует эти файлы в строгую иерархию компонентов React.

Прогрессивное раскрытие файловой системы#

Виток 1: Базовая пара макета и страницы

• page.tsx — единственная точка входа, формирующая публичный URL. Без этого файла директория не генерирует маршрут.
• layout.tsx — структурный каркас сегмента. Обязан принимать проп { children: React.ReactNode }. app/layout.tsx (Root Layout) обязателен для всего проекта и является единственным местом, где объявляются теги <html> и <body>.

Виток 2: Граничные компоненты состояний

• loading.tsx — декларативная граница <Suspense>, мгновенно отдающая скелетон при серверной загрузке.
• error.tsx — изолированный клиентский перехватчик сбоев (<ErrorBoundary>). Обязан содержать директиву 'use client'. При падении дочерней страницы родительский макет и навигация остаются полностью работоспособными.
• not-found.tsx — сегментный интерфейс 404, вызываемый программно функцией notFound().

Виток 3: Организационные соглашения

• (folder) — Route Group (Группа маршрутов): позволяет структурировать проект или изолировать макеты без изменения структуры URL. Например, app/(marketing)/about/page.tsx доступен по чистому адресу /about.
• _folder — Private Folder (Приватная папка): исключается из системы маршрутизации.

app/
├── layout.tsx             # Root Layout (<html> и <body>)
├── page.tsx               # Главная страница (/)
├── not-found.tsx          # Глобальный 404
├── global-error.tsx       # Корневой перехват фатальных ошибок
├── (marketing)/           # Route Group (не входит в URL)
│   ├── about/
│   │   └── page.tsx       # Маршрут: /about
│   └── pricing/
│       └── page.tsx       # Маршрут: /pricing
└── dashboard/
    ├── layout.tsx         # Вложенный каркас с сайдбаром (сохраняет состояние)
    ├── loading.tsx        # Suspense fallback для дашборда
    ├── error.tsx          # Client Error Boundary ('use client')
    ├── not-found.tsx      # Сегментная 404
    ├── page.tsx           # Маршрут: /dashboard
    ├── _components/       # Приватная папка (исключена из роутинга)
    │   └── MetricCard.tsx
    └── settings/
        └── page.tsx       # Маршрут: /dashboard/settings

5. Асинхронные параметры и интеграция с React 19#

Начиная с Next.js 15 и стандартов React 19, параметры пути params и поисковые параметры searchParams передаются в серверные компоненты страниц, макетов и функций generateMetadata как асинхронные промисы (Promise).

Почему параметры стали Promise?#

В синхронной модели (Next.js 13–14) сервер был вынужден задерживать генерацию страницы до тех пор, пока HTTP-запрос не будет полностью разобран (включая все входящие заголовки и cookies). Это приводило к искусственной блокировке времени первого байта (TTFB).

Переход к Promise — это инфраструктурная основа для Partial Prerendering (PPR):

1. Статическая оболочка страницы (хедер, навигация, каркас) компилируется в готовый HTML на этапе сборки и отдается из CDN за менее 50 мс.
2. Входящие параметры пути и строки запроса передаются в компонент страницы в виде неразрешенных промисов.
3. Если чтение await params обернуто в границу React <Suspense>, статическая часть страницы вообще не ожидает завершения вычислений. Как только серверный рантайм парсит запрос, промис разрешается, и сервер досылает динамические чанки в открытый потоковый HTTP-канал.

import { Metadata } from 'next';
import { notFound } from 'next/navigation';

interface AnalyticsPageProps {
  params: Promise<{ period: string }>;
  searchParams: Promise<{ metric?: string }>;
}

// 1. Динамическая генерация метаданных
export async function generateMetadata(props: AnalyticsPageProps): Promise<Metadata> {
  const { period } = await props.params;
  return {
    title: `Отчет за период: ${period.toUpperCase()}`,
    description: `Сводная телеметрия за период ${period}`,
  };
}

// 2. Серверная страница с асинхронными параметрами
export default async function AnalyticsPage(props: AnalyticsPageProps) {
  // Асинхронное разрешение параметров Next.js 16
  const params = await props.params;
  const searchParams = await props.searchParams;

  const validPeriods = ['day', 'week', 'month'];
  if (!validPeriods.includes(params.period)) {
    notFound();
  }

  const activeMetric = searchParams.metric ?? 'all';

  return (
    <main className="p-6 space-y-4">
      <h1 className="text-2xl font-bold">Период: {params.period}</h1>
      <p className="text-text-muted">Активный фильтр: {activeMetric}</p>
    </main>
  );
}

Чтение асинхронных параметров в клиентских компонентах через React 19 use()#

Если асинхронный промис параметров передается в клиентский компонент (Client Component), для его разыменования используется нативный примитив React 19 — хук use():

'use client';

import { use } from 'react';

interface ClientSectionViewProps {
  paramsPromise: Promise<{ section: string }>;
}

export function ClientSectionView({ paramsPromise }: ClientSectionViewProps) {
  // Разрешение промиса параметров прямо в теле клиентского компонента
  const { section } = use(paramsPromise);

  return (
    <div className="p-4 rounded-lg bg-bg-surface border border-border">
      <span className="text-xs text-text-muted uppercase">Клиентский сегмент:</span>
      <h3 className="text-lg font-mono font-bold text-accent-cyan">{section}</h3>
    </div>
  );
}

6. Протоколы под капотом: React Flight и Client Router Cache#

При мягкой клиентской навигации (<Link href="...">) браузер не запрашивает новый HTML-документ. Вместо этого клиентский роутер отправляет фоновый асинхронный HTTP-запрос, содержащий системные заголовки:

• RSC: 1 — указывает серверу, что необходимо вернуть не монолитный HTML, а сериализованный поток графа компонентов.
• Next-Router-State-Tree — передает на сервер закодированный снимок текущего смонтированного дерева сегментов на клиенте. Сервер вычисляет точку наименьшего общего предка (Lowest Common Ancestor, LCA) и исполняет исключительно изменившиеся компоненты.

Эволюция Client Router Cache и конфигурация staleTimes в Next.js 16#

В Next.js 16 политика кэширования клиентского роутера в оперативной памяти браузера (Client Router Cache) оптимизирована для максимальной консистентности данных:

1. Динамические сегменты: Время жизни кэша (staleTime) установлено равным 0 секунд. Каждый переход на динамическую страницу запрашивает свежий Flight Payload с сервера.
2. Статические сегменты и предзагрузка: Для статических маршрутов (SSG) и предварительно загруженных ссылок время актуальности кэша составляет 5 минут (300 секунд).
3. Файлы loading.tsx: Потоковые скелетоны кэшируются на 5 минут, предотвращая мерцание спиннеров при повторных переходах.
4. Общие макеты (Shared Layouts): Никогда не перезапрашиваются с сервера при межлистовой навигации внутри одного родителя.

Тонкая регулировка времени жизни кэша на клиенте настраивается в next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30, // Кэшировать динамические страницы в памяти браузера на 30 секунд
      static: 180,  // Кэшировать статические сегменты на 3 минуты
    },
  },
};

export default nextConfig;

Семантика директивы prefetch в App Router#

• prefetch={null} (по умолчанию): Для статических страниц загружает полный Flight Payload. Для динамических страниц подгружает только скелетон до ближайшего loading.tsx.
• prefetch={true}: Принудительно предзагружает полный Flight Payload всего дерева, включая динамические данные.
• prefetch={false}: Полностью отключает предзагрузку как во вьюпорте, так и при наведении курсора (hover). Для загрузки по hover разработчик вызывает router.prefetch() вручную.

7. Продакшн-паттерны и архитектурная организация#

Паттерн 1: Безопасная коллокация фичи#

Размещение компонентов, экшенов и типов рядом с маршрутом исключает раздувание глобальных папок и защищает приватные файлы от случайного превращения в публичный эндпоинт.

interface Invoice {
  id: string;
  amount: number;
  status: 'paid' | 'pending';
}

interface InvoiceListProps {
  items: Invoice[];
}

export function InvoiceList({ items }: InvoiceListProps) {
  return (
    <ul className="divide-y divide-border border border-border rounded-lg bg-bg-surface">
      {items.map((invoice) => (
        <li key={invoice.id} className="p-3 flex justify-between items-center text-sm">
          <span className="font-mono text-accent-cyan">#{invoice.id}</span>
          <span className="font-semibold">${(invoice.amount / 100).toFixed(2)}</span>
        </li>
      ))}
    </ul>
  );
}

import { InvoiceList } from './_components/InvoiceList';

async function getInvoices() {
  return [
    { id: 'inv-101', amount: 4900, status: 'paid' as const },
    { id: 'inv-102', amount: 12000, status: 'pending' as const },
  ];
}

export default async function BillingPage() {
  const invoices = await getInvoices();

  return (
    <section className="space-y-4">
      <h2 className="text-xl font-bold">Управление счетами</h2>
      <InvoiceList items={invoices} />
    </section>
  );
}

Паттерн 2: Декларативная конфигурация сегмента (Segment Config)#

В файлах page.tsx и layout.tsx можно декларативно задавать стратегию исполнения и кэширования для всего поддерева сегмента:

// Принудительный динамический рендеринг при каждом входящем запросе
export const dynamic = 'force-dynamic';

// Изоляция среды исполнения (Node.js рантайм)
export const runtime = 'nodejs';

// Время жизни кэша сегмента в секундах (Incremental Static Regeneration, ISR)
export const revalidate = 300;

export default async function ReportsPage() {
  return <div className="p-6">Сводные отчеты (обновляются каждые 5 минут)</div>;
}

8. Граничные случаи, системные сбои и безопасность#

9. Инженерные кейсы технических собеседований#