Layouts та Templates у Next.js App Router

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

У промислових вебзастосунках сторінки поділяють спільні структурні каркаси: навігаційні панелі, бічні меню (sidebars), віджети профілю, глобальні аудіоплеєри та футери. У традиційних клієнтських клієнтських SPA під час переходу між сторінками розробникам доводилося долати системні складнощі:

• Мерехтіння інтерфейсу та втрата стану: При переході між дочірніми екранами каркас розмонтовувався та монтувався наново, втрачаючи скрол меню, розгорнуті акордеони та значення текстових полів.
• Повторні надлишкові запити до БД: При кожному кліку на посилання навігація знову ініціювала виклики для отримання профілю користувача, структури меню та лічильників сповіщень.
• Складнощі з анімаціями переходів: Спроби анімувати зміну сторінок натикалися на конфлікт між збереженням батьківського макета та необхідністю гарантовано перемонтувати центральну область контенту.

Next.js App Router вирішує ці завдання на фундаментальному рівні через суворий розподіл обов'язків між Layouts (макетами) та Templates (шаблонами).

Ментальна модель: звірка піддерева та персистентність#

В архітектурі React Fiber макет (layout.tsx) є стабільним вузлом віртуального дерева, чий локальний стан, DOM-вузли та фокус введення персистентні. Дочірні маршрути передаються в макет виключно через слот children. Коли змінюється вкладений URL, React виконує звірку піддерева (Subtree Reconciliation): оновлюється лише вміст children, тоді як вузол макета залишається недоторканим.

Ієрархія макетів суворо повторює структуру каталогів:

1. Root Layout (app/layout.tsx) застосовується глобально до всіх маршрутів проєкту.
2. Вкладені макети (Nested Layouts) активуються лише для сторінок усередині своєї директорії та автоматично вкладаються в батьківські макети.
3. Templates (template.tsx) компілюються Next.js як безпосередні дочірні елементи макета відповідного сегмента, але огортаються в динамічний ключ key={currentSegmentId}, викликаючи повне перестворення вузла під час навігації.

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

Процес обробки макетів і шаблонів під час переходу між сторінками регламентований фазами Fiber Reconciliation:

Синтаксис та API: контракти файлової системи#

1. Root Layout (Обов'язковий кореневий каркас)#

Кореневий макет створюється в app/layout.tsx і є обов'язковим для будь-якого застосунку Next.js. Лише він може містити кореневі теги <html> та <body>.

import type { Metadata } from 'next';
import './globals.css';

export const metadata: Metadata = {
  title: {
    template: '%s | Fullstack Agentic Lab',
    default: 'Fullstack Agentic Lab',
  },
  description: 'Інженерна платформа з Fullstack та AI розробки',
};

interface RootLayoutProps {
  children: React.ReactNode;
}

export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="uk" className="dark">
      <body className="min-h-screen bg-bg-base text-text-primary antialiased">
        <header className="border-b border-border p-4">Глобальна навігація</header>
        <main>{children}</main>
      </body>
    </html>
  );
}

2. Асинхронні параметри шляху в макетах (Next.js 15+)#

Починаючи з Next.js 15, якщо макет сегмента розташований усередині динамічного шляху app/[tenant]/layout.tsx, параметр params передається до нього як Promise:

interface TenantLayoutProps {
  children: React.ReactNode;
  params: Promise<{ tenant: string }>;
}

export default async function TenantLayout({ children, params }: TenantLayoutProps) {
  // Асинхронне розв'язання параметрів шляху в макеті
  const { tenant } = await params;

  return (
    <div className="tenant-container flex min-h-screen">
      <aside className="tenant-sidebar w-64 border-r border-border p-4">
        <h2 className="text-lg font-bold">Організація: {tenant}</h2>
      </aside>
      <section className="tenant-content flex-1 p-6">
        {children}
      </section>
    </div>
  );
}

3. Архітектурне обмеження: Чому макети НЕ отримують searchParams#

На відміну від page.tsx, серверні компоненти layout.tsx не отримують проп searchParams.

Це фундаментальне архітектурне рішення для забезпечення ефективності кешування:

• Якби макет залежав від рядка запиту (?page=2&sort=asc), сервер був би змушений перезапитувати та перемальовувати весь батьківський каркас при кожній зміні пагінації чи фільтрів.
• Ізоляція макета від searchParams дозволяє кешувати його в пам'яті браузера (Client Router Cache) на тривалий час у межах поточної сесії.

Якщо вкладеному клієнтському компоненту всередині макета все ж потрібен доступ до рядка запиту, використовуйте клієнтський хук useSearchParams() з next/navigation.

Під капотом: компіляція Templates у динамічний React key#

Next.js компілює файл template.tsx як безпосередню внутрішню огортку сторінки всередині слота children макета:

<Layout>
  {/* Template огортається в динамічний ключ поточного сегмента */}
  <Template key={currentSegmentId}>
    <ErrorBoundary fallback={<Error />}>
      <Suspense fallback={<Loading />}>
        <Page />
      </Suspense>
    </ErrorBoundary>
  </Template>
</Layout>

Коли currentSegmentId змінюється з orders на analytics, зміна атрибута key повідомляє рушію React Fiber: «Знищ старе дерево DOM і змонтуй компонент з нуля».

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

Патерн 1: Template для анімацій переходів сторінок та трекінгу#

'use client';

import { useEffect } from 'react';
import { usePathname } from 'next/navigation';

interface TemplateProps {
  children: React.ReactNode;
}

export default function DashboardTemplate({ children }: TemplateProps) {
  const pathname = usePathname();

  useEffect(() => {
    // Гарантований запуск аналітики при кожному переході
    console.log(`[Telemetry] Page view registered: ${pathname}`);
  }, [pathname]);

  return (
    <div className="animate-in fade-in duration-300">
      {children}
    </div>
  );
}

Патерн 2: Клієнтський провайдер у серверному Layout (Патерн слота)#

Часте завдання — впровадження клієнтського React Context (тема оформлення, локалізація) в кореневий серверний макет без перетворення всього макета на клієнтський компонент:

'use client';

import { createContext, useContext, useState } from 'react';

type Theme = 'dark' | 'light';

const ThemeContext = createContext<{
  theme: Theme;
  toggleTheme: () => void;
}>({
  theme: 'dark',
  toggleTheme: () => {},
});

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('dark');

  const toggleTheme = () => {
    setTheme((prev) => (prev === 'dark' ? 'light' : 'dark'));
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => useContext(ThemeContext);

import { ThemeProvider } from '@/components/providers/ThemeProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="uk">
      <body>
        {/* ThemeProvider є клієнтом, але children передається із сервера у вигляді RSC без втрати продуктивності! */}
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Патерн 3: Серверна перевірка авторизації в Layout з асинхронними cookies()#

import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

interface AdminLayoutProps {
  children: React.ReactNode;
}

export default async function AdminLayout({ children }: AdminLayoutProps) {
  // Асинхронне читання cookies у Next.js 15+
  const cookieStore = await cookies();
  const sessionToken = cookieStore.get('auth_token')?.value;

  if (!sessionToken) {
    redirect('/login?from=/admin');
  }

  return (
    <div className="admin-shell min-h-screen bg-bg-surface">
      <header className="border-b border-border p-4 font-bold">
        Панель адміністратора
      </header>
      <main className="p-6">{children}</main>
    </div>
  );
}

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

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