Prácticas recomendadas de Next.js
Regla de lectura selectiva
Comienza con:
references/senior-master-standard.md
references/usage-routing.md
references/quality-checklist.md
Luego carga solo los documentos, scripts, activos o ejemplos heredados que coincidan con la tarea real del usuario.
Principios para el desarrollo con App Router de Next.js.
1. Componentes de servidor vs cliente
Árbol de decisión
¿Necesita...?
│
├── useState, useEffect, controladores de eventos
│ └── Componente Cliente ('use client')
│
├── Obtención directa de datos, sin interactividad
│ └── Componente Servidor (por defecto)
│
└── ¿Ambos?
└── Divide: Servidor padre + Cliente hijo
Por defecto
| Tipo | Uso |
|---|
| Servidor | Obtención de datos, diseño, contenido estático |
| Cliente | Formularios, botones, UI interactiva |
2. Patrones de obtención de datos
Estrategia de obtención
| Patrón | Uso |
|---|
| Por defecto | Estático (almacenado en caché en compilación) |
| Revalidar | ISR (actualización basada en tiempo) |
| Sin almacenamiento | Dinámico (cada solicitud) |
Flujo de datos
| Origen | Patrón |
|---|
| Base de datos | Obtención en componente servidor |
| API | fetch con almacenamiento en caché |
| Entrada del usuario | Estado del cliente + acción del servidor |
3. Principios de enrutamiento
Convenciones de archivos
| Archivo | Propósito |
|---|
page.tsx | UI de la ruta |
layout.tsx | Diseño compartido |
loading.tsx | Estado de carga |
error.tsx | Límite de error |
not-found.tsx | Página 404 |
Organización de rutas
| Patrón | Uso |
|---|
Grupos de rutas (nombre) | Organizar sin URL |
Rutas paralelas @slot | Múltiples páginas al mismo nivel |
Interceptación (.) | Superposiciones modales |
4. Rutas API
Manejadores de ruta
| Método | Uso |
|---|
| GET | Leer datos |
| POST | Crear datos |
| PUT/PATCH | Actualizar datos |
| DELETE | Eliminar datos |
Prácticas recomendadas
- Validar entrada con Zod
- Devolver códigos de estado apropiados
- Manejar errores correctamente
- Usar Edge runtime cuando sea posible
5. Principios de rendimiento
Optimización de imágenes
- Usar el componente next/image
- Establecer prioridad para contenido visible
- Proporcionar marcador de posición borroso
- Usar tamaños responsivos
Optimización del paquete
- Importaciones dinámicas para componentes pesados
- División de código basada en rutas (automática)
- Analizar con bundle analyzer
6. Metadatos
Estáticos vs dinámicos
| Tipo | Uso |
|---|
| Exportación estática | Metadatos fijos |
| generateMetadata | Dinámico por ruta |
Etiquetas esenciales
- title (50-60 caracteres)
- description (150-160 caracteres)
- Imágenes de Open Graph
- URL canónica
7. Estrategia de almacenamiento en caché
Capas de caché
| Capa | Control |
|---|
| Solicitud | opciones de fetch |
| Datos | revalidate/tags |
| Ruta completa | configuración de ruta |
Revalidación
| Método | Uso |
|---|
| Basada en tiempo | revalidate: 60 |
| Bajo demanda | revalidatePath/Tag |
| Sin caché | no-store |
8. Acciones del servidor
Casos de uso
- Envíos de formularios
- Mutaciones de datos
- Disparadores de revalidación
Prácticas recomendadas
- Marcar con 'use server'
- Validar todas las entradas
- Devolver respuestas tipadas
- Manejar errores
9. Antipatrones
| ❌ No hacer | ✅ Hacer |
|---|
| 'use client' en todas partes | Servidor por defecto |
| Obtener datos en componentes cliente | Obtener datos en servidor |
| Saltar estados de carga | Usar loading.tsx |
| Ignorar límites de error | Usar error.tsx |
| Paquetes cliente grandes | Importaciones dinámicas |
10. Estructura del proyecto
app/
├── (marketing)/ # Grupo de rutas
│ └── page.tsx
├── (dashboard)/
│ ├── layout.tsx # Diseño del panel
│ └── page.tsx
├── api/
│ └── [resource]/
│ └── route.ts
└── components/
└── ui/
Recuerda: Los Componentes Servidor son la opción predeterminada por una razón. Empieza allí, agrega cliente solo cuando sea necesario.
Cuándo usar
Este skill es aplicable para ejecutar el flujo de trabajo o las acciones descritas en la descripción general.
Limitaciones
- Usa este skill solo cuando la tarea coincida claramente con el alcance descrito anteriormente.
- No trates la salida como un sustituto de la validación, pruebas o revisión experta específica del entorno.
- Detente y solicita aclaraciones si faltan entradas, permisos, límites de seguridad o criterios de éxito requeridos.