Файлова маршрутизація в 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 15+
  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 15+#

У Next.js 15 політику клієнтського кешування в оперативній пам'яті браузера (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). Для завантаження за подією розробник викликає 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. Інженерні кейси технічних співбесід#