Layouts y Templates en Next.js App Router

Contexto arquitectónico y motivación#

En aplicaciones web de nivel empresarial, las páginas comparten marcos estructurales comunes: barras de navegación, menús laterales (sidebars), widgets de perfil, reproductores de audio globales y pies de página persistentes. En las SPAs tradicionales de cliente, mantener estas estructuras durante la navegación presentaba graves dificultades:

• Parpadeos visuales y pérdida de estado: Al navegar entre pantallas hermanas, la estructura base se desmontaba y volvía a montar, perdiendo la posición de scroll del menú, acordeones desplegados y valores de formularios.
• Peticiones redundantes a bases de datos: Cada transición desencadenaba nuevamente llamadas para obtener el perfil de usuario, jerarquía de navegación y contadores de notificaciones.
• Complicaciones con animaciones de transición: Intentar animar la entrada de páginas chocaba con la necesidad de preservar el layout padre mientras se remontaba obligatoriamente el contenedor central de contenido.

Next.js App Router soluciona estos problemas a nivel fundamental mediante una clara separación de responsabilidades entre Layouts y Templates.

Modelo mental: reconciliación de subárboles y persistencia#

En la arquitectura de React Fiber, un layout (layout.tsx) es un nodo estable del árbol virtual cuyo estado local, nodos del DOM y foco de entrada son persistentes. Las rutas hijas se entregan al layout exclusivamente mediante la prop children. Cuando cambia la URL anidada, React ejecuta una Reconciliación de Subárbol (Subtree Reconciliation): únicamente se actualiza el contenido de children, manteniendo el nodo del layout intacto.

La jerarquía de layouts reproduce con exactitud la estructura de directorios:

1. El Root Layout (app/layout.tsx) se aplica de forma global a todas las rutas del proyecto.
2. Los Layouts Anidados (Nested Layouts) se activan únicamente para las páginas dentro de su directorio y se anidan automáticamente dentro de los layouts padre.
3. Los Templates (template.tsx) se compilan como hijos directos del layout del segmento correspondiente, pero envueltos con una clave dinámica key={currentSegmentId}, forzando la recreación completa del nodo en cada navegación.

Algoritmo de ejecución y ciclo de vida (Runtime Execution)#

La secuencia de renderizado de layouts y templates durante la navegación está regida por las fases de Fiber Reconciliation:

Sintaxis y API: contratos del sistema de archivos#

1. Root Layout (Marco raíz obligatorio)#

El Root Layout se define en app/layout.tsx y es obligatorio para cualquier aplicación Next.js. Es el único componente autorizado para declarar las etiquetas <html> y <body>.

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

export const metadata: Metadata = {
  title: {
    template: '%s | Fullstack Agentic Lab',
    default: 'Fullstack Agentic Lab',
  },
  description: 'Plataforma de Ingeniería Fullstack y Desarrollo con IA',
};

interface RootLayoutProps {
  children: React.ReactNode;
}

export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="es" className="dark">
      <body className="min-h-screen bg-bg-base text-text-primary antialiased">
        <header className="border-b border-border p-4">Navegación Global</header>
        <main>{children}</main>
      </body>
    </html>
  );
}

2. Parámetros de ruta asíncronos en Layouts (Next.js 15+)#

A partir de Next.js 15, cuando un layout se sitúa dentro de una ruta dinámica como app/[tenant]/layout.tsx, el parámetro params se recibe como una Promise:

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

export default async function TenantLayout({ children, params }: TenantLayoutProps) {
  // Resolución asíncrona de los parámetros de ruta en el layout
  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">Organización: {tenant}</h2>
      </aside>
      <section className="tenant-content flex-1 p-6">
        {children}
      </section>
    </div>
  );
}

3. Restricción arquitectónica: Por qué los Layouts NO reciben searchParams#

A diferencia de page.tsx, los componentes de servidor layout.tsx no reciben la prop searchParams.

Esta decisión es esencial para la eficiencia de la caché:

• Si un layout dependiese de parámetros de búsqueda (?page=2&sort=asc), el servidor tendría que re-renderizar toda la estructura padre en cada cambio de paginación o filtro.
• Aislar el layout de searchParams permite almacenarlo en la memoria del navegador (Client Router Cache) a largo plazo durante la sesión activa.

Si un componente de cliente anidado dentro del layout requiere acceso a los parámetros de búsqueda, utilice el hook de cliente useSearchParams() de next/navigation.

Bajo el capó: compilación de Templates en claves dinámicas de React#

Next.js compila el archivo template.tsx como el envoltorio directo de la página dentro del slot children del layout:

<Layout>
  {/* El Template se envuelve con la clave dinámica del segmento actual */}
  <Template key={currentSegmentId}>
    <ErrorBoundary fallback={<Error />}>
      <Suspense fallback={<Loading />}>
        <Page />
      </Suspense>
    </ErrorBoundary>
  </Template>
</Layout>

Cuando currentSegmentId cambia de orders a analytics, la mutación de la prop key ordena al motor de React Fiber: «Destruye el nodo previo del DOM y monta una instancia completamente nueva desde cero».

Patrones de producción: organización arquitectónica#

Patrón 1: Template para animaciones de entrada y telemetría#

'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(() => {
    // Registro de analítica garantizado en cada cambio de ruta
    console.log(`[Telemetry] Page view registered: ${pathname}`);
  }, [pathname]);

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

Patrón 2: Proveedor de cliente en un Layout de servidor (Patrón Slot)#

Un requerimiento frecuente es integrar un contexto de React de cliente (tema visual, idioma) en el layout raíz sin convertir todo el layout en un Client Component:

'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="es">
      <body>
        {/* ThemeProvider es un límite de cliente, pero {children} se entrega como RSC desde el servidor sin sobrecargar el bundle JS. */}
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Patrón 3: Verificación de autenticación en servidor dentro de Layout con cookies() asíncronas#

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

interface AdminLayoutProps {
  children: React.ReactNode;
}

export default async function AdminLayout({ children }: AdminLayoutProps) {
  // Lectura asíncrona de cookies en 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">
        Panel de Administración
      </header>
      <main className="p-6">{children}</main>
    </div>
  );
}

Errores comunes: fallos del sistema y seguridad#

Preguntas de entrevista para ingenieros Staff / Lead#