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="ru" 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 16)#

В Next.js 16, если макет сегмента расположен внутри динамического пути 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="ru">
      <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 16
  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 уровень#