Prioridad: P0 (CRÍTICA)
Directrices de Implementación
Arquitectura de Enrutamiento
- Estructura: Usa el directorio
app/. Define rutas con app/dashboard/layout.tsx retornando {children}; la UI compartida se anida automáticamente dentro de app/layout.tsx. Maneja estados con loading.tsx, error.tsx y not-found.tsx.
- Segmentos: Organiza funcionalidades con Grupos de Rutas (corchetes
(auth)) para que sean excluidos de la URL. Usa Rutas Dinámicas (corchetes [slug]) y define rutas estáticas mediante generateStaticParams.
- Especializados: Usa Rutas Paralelas (
@modal) agregando el slot al layout padre y proporcionando un fallback default.tsx. Usa Rutas Interceptadas ((.)route) para layouts avanzados como paneles de control.
Datos y Funciones
- Next.js 15+ Async: Siempre
await params: Promise, searchParams, cookies() y headers().
- Seguridad: Usa
middleware.ts para autenticación y redirección del lado del edge. Asegura que todos los Route Handlers (route.ts) tengan las verificaciones de autenticación adecuadas.
- RSC: Por defecto, usa React Server Components (RSC). Solo usa
'use client' en nodos hoja para interactividad (hooks/eventos).
- Error Boundaries: Crea
app/dashboard/loading.tsx para envolver automáticamente las rutas en un boundary de Suspense. En error.tsx, usa 'use client' y proporciona una función reset: () => void.
const theme = cookieStore.get('theme');
## Convenciones de Archivos
- **page.tsx**: UI para una ruta.
- **layout.tsx**: UI compartida que envuelve a los hijos. Persiste durante la navegación.
- **loading.tsx**: Boundary de Suspense para estados de carga.
- **error.tsx**: Boundary de error (Debe ser un Componente Cliente).
- **route.ts**: Endpoint de API del lado del servidor.
## Patrones de Estructura
- **Grupos de Rutas**: Usa paréntesis `(auth)` para organizar sin afectar la URL.
- **Carpetas Privadas**: Usa guion bajo `_lib` para excluir del enrutamiento.
- **Rutas Dinámicas**: Usa corchetes `[slug]` o `[...slug]` (comodín).
## Mejores Prácticas
- **Límites de RSC**: Asegúrate de que las props pasadas a los Componentes Cliente sean serializables. Consulta [Límites de RSC y Serialización](../architecture/references/RSC_BOUNDARIES.md).
- **Rutas Paralelas (`@folder`)**: Renderiza múltiples páginas en el mismo layout. Usa `default.tsx` como fallback.
- **Rutas Interceptadas (`(..)folder`)**: Carga rutas dentro del contexto del layout actual.
- **Colocación**: Mantén los archivos de componentes, estilos y pruebas dentro de la carpeta de la ruta.
- **Layouts**: Usa el Layout Raíz (`app/layout.tsx`) para las etiquetas `<html>` y `<body>`.
- [**Estándar de Autohospedaje**](references/SELF_HOSTING.md)
## Anti-Patrones
- **No uses APIs asíncronas sin await**: `params`, `cookies()`, `headers()` son Promesas en Next.js 15+; siempre hazles await.
- **No pongas `'use client'` en la raíz del árbol**: Colócalo en las hojas; mantén layouts y páginas como Server Components.
- **No uses `<html>`/`<body>` en layouts anidados**: Solo `app/layout.tsx` (layout raíz) debe incluirlos.
- **No olvides `error.tsx`**: Cada segmento de ruta necesita un boundary de error de Componente Cliente.