Паралельні та перехоплюючі маршрути в Next.js App Router

Навіщо це потрібно: проблематика та архітектурний контекст#

Сучасні високонавантажені вебдодатки вимагають складних і динамічних сценаріїв відображення інтерфейсу:

1. Багатопанельні інтерфейси (Dashboards & Split-views): Необхідність одночасно виводити на одному екрані кілька незалежних аналітичних панелей, графіків або стрічок активності. Кожна з них повинна асинхронно стрімити дані, мати власний індикатор завантаження (loading.tsx) та ізольовано обробляти збої (error.tsx), не порушуючи роботу сусідніх панелей.
2. URL-Driven Modals (модальні вікна, прив'язані до URL): Відкриття детального перегляду картки товару або фотографії в модальному вікні поверх поточного списку зі збереженням контексту фонової сторінки та оновленням URL (наприклад, перехід на /photo/123). При цьому прямий захід за цим же посиланням або оновлення сторінки через F5 повинні відкривати повноцінну окрему сторінку, а не модалку.

Next.js App Router вирішує ці завдання на рівні ядра за допомогою паралельних маршрутів (Parallel Routes) та перехоплюючих маршрутів (Intercepting Routes).

Ментальна модель: слоти @slot та рівні перехоплення#

1. Паралельні маршрути (@slot)#

Паралельні маршрути створюються з використанням папок із префіксом @ (слотів). Імена слотів не потрапляють у публічний URL (app/dashboard/@analytics компілюється в URL /dashboard), а передаються як іменовані React-пропси в компонент layout.tsx відповідного рівня.

Основний файл page.tsx неявно є слотом за замовчуванням children (еквівалентний @children). Кожен паралельний слот є незалежною гілкою React-дерева зі своїм життєвим циклом, межею Suspense та кешем.

2. Перехоплюючі маршрути ((.), (..))#

Перехоплюючі маршрути дозволяють замапити клієнтський перехід за посиланням на альтернативний компонент, зберігаючи контекст поточного екрана:

• (.) — перехоплення маршруту на тому ж рівні сегмента.
• (..) — перехоплення маршруту на один сегмент вище.
• (..)(..) — перехоплення на два сегменти вище.
• (...) — перехоплення від самого кореня директорії app.

Важливо: Папки паралельних слотів (@slot) і групи маршрутів ((group)) не є сегментами URL і повністю ігноруються при підрахунку рівнів для (..).

Алгоритм виконання та життєвий цикл (Runtime Execution)#

Синтаксис та API: контракти слотів і типізація Layout#

1. Підключення паралельних слотів у Layout#

Паралельні слоти передаються в layout.tsx як іменовані React-пропси:

interface DashboardLayoutProps {
  children: React.ReactNode;
  analytics: React.ReactNode; // Слот app/dashboard/@analytics
  notifications: React.ReactNode; // Слот app/dashboard/@notifications
}

export default function DashboardLayout({
  children,
  analytics,
  notifications,
}: DashboardLayoutProps) {
  return (
    <div className="p-6 space-y-6">
      <main>{children}</main>
      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
        <section className="border border-border p-4 rounded-lg">
          {analytics}
        </section>
        <section className="border border-border p-4 rounded-lg">
          {notifications}
        </section>
      </div>
    </div>
  );
}

2. Системний контракт файлу default.tsx#

Файл default.tsx визначає, що відображати в паралельному слоті, коли поточний URL не збігається з жодним маршрутом усередині цього слота:

// Якщо модальне вікно не активне, повертаємо null для приховування слота
export default function DefaultModalSlot() {
  return null;
}

Практичні патерни: архітектурна організація#

Патерн: URL-Driven модальне вікно з кнопкою закриття через router.back()#

'use client';

import { useRouter } from 'next/navigation';
import { use } from 'react';

interface PhotoModalProps {
  params: Promise<{ id: string }>;
}

export default function PhotoModal({ params }: PhotoModalProps) {
  const router = useRouter();
  const { id } = use(params);

  return (
    <div className="fixed inset-0 z-50 bg-black/80 flex items-center justify-center p-4">
      <div className="bg-bg-surface border border-border rounded-xl max-w-lg w-full p-6 space-y-4">
        <div className="flex justify-between items-center">
          <h3 className="text-lg font-bold">Фото #{id}</h3>
          {/* router.back() відновлює попередній URL без модалки */}
          <button
            onClick={() => router.back()}
            className="text-text-muted hover:text-text-primary text-sm px-2 py-1 rounded bg-bg-elevated"
          >
            Закрити ✕
          </button>
        </div>
        <div className="aspect-video bg-black/40 rounded-lg flex items-center justify-center font-mono text-xs text-text-muted">
          [Перегляд фотографії {id}]
        </div>
      </div>
    </div>
  );
}

Поширені помилки: граничні збої та безпека#

Питання на співбесіді: Staff / Lead рівень#