Especialista en Next.js 15 + App Router
Referencia completa de Next.js 15 para el desarrollo con Quetrex.
Esta habilidad proporciona una guía exhaustiva sobre todos los patrones del App Router de Next.js 15, garantizando que los agentes implementen Next.js moderno de forma correcta desde el primer intento.
REGLAS CRÍTICAS (NUNCA VIOLAR)
Estas reglas son INNEGOCIABLES. Las violaciónes romperán las compilaciones.
1. Usa SIEMPRE <Image> de next/image - NUNCA uses <img>
// ✅ SIEMPRE HAZ ESTO
import Image from 'next/image'
<Image src="/logo.png" alt="Logo" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />
// ❌ NUNCA HAGAS ESTO - LA COMPILACIÓN FALLARÁ
<img src="/logo.png" alt="Logo" />
<img src={user.avatar} alt={user.name} />
Por qué: El componente Image de Next.js proporciona optimización automática, carga diferida y previene el cambio de diseño. ESLint está configurado para fallar en las compilaciones si se usa <img>.
2. Los Server Components son el VALOR POR DEFECTO - solo añade 'use client' cuando sea necesario
3. Nunca hagas Client Components asíncronos
4. Especifica siempre la estrategia de caché para fetch()
Cuándo Usar Esta Habilidad
Usa esta habilidad cuando trabajes con:
- Creación de nuevas rutas o páginas
- Implementación de obtención de datos (Server Components vs Client Components)
- Decisiones entre Server vs Client Components
- Server Actions y manejo de formularios
- Streaming y Suspense
- Metadatos y SEO
- Manejadores de rutas (API routes)
- Estrategias de caché
- Optimización del rendimiento
Documentación Completa
Esta habilidad incluye guías completas que cubren cada patrón de Next.js 15:
📁 Guía Completa del App Router
Más de 45 ejemplos que cubren:
- Enrutamiento basado en archivos (page.tsx, layout.tsx, route.ts)
- Rutas dinámicas ([id], [...slug], [[...slug]])
- Grupos de rutas ((group))
- Carpetas privadas (_folder)
- Manejadores de rutas (API routes)
- Layouts y plantillas
- UI de carga (loading.tsx)
- Límites de error (error.tsx, global-error.tsx)
- Páginas no encontradas (not-found.tsx)
- Rutas paralelas (@folder)
- Rutas interceptadas ((.)folder)
- Configuración de segmentos de ruta (dynamic, revalidate, runtime)
🔄 Guía Completa de Obtención de Datos
Más de 35 ejemplos que cubren:
- Obtención de datos en Server Components (async/await)
- Obtención de datos en Client Components (useEffect, React Query, SWR)
- Obtención de datos en paralelo (Promise.all)
- Obtención de datos secuencial (prevención de cascadas)
- Transmisión de datos (límites de Suspense)
- Eventos enviados por el servidor (SSE para voz de Quetrex)
- Mutaciones de datos (Server Actions)
- Actualizaciones optimistas (useOptimistic)
- Manejo de formularios (useFormStatus, useActionState)
- Desduplicación de solicitudes
- Precarga de datos
💾 Guía de Estrategias de Caché
Más de 35 ejemplos que cubren:
- Memorización de solicitudes (desduplicación automática)
- Caché de datos (comportamiento de la caché de fetch)
- Caché de ruta completa (estático vs dinámico)
- Caché del enrutador (caché del lado del cliente)
- Configuración de la caché (force-cache, no-store, revalidate)
- Etiquetas de caché (revalidateTag, revalidatePath)
- Revalidación bajo demanda
- Revalidación basada en tiempo (ISR)
- Técnicas de depuración de la caché
- Exclusión de la caché
⚡ Guía Completa de Server Actions
Más de 31 ejemplos que cubren:
- Patrones básicos de Server Actions
- Acciones de formulario (mejora progresiva)
- Acciones de botón (llamadas programáticas)
- Hook useFormStatus (estados de carga)
- Hook useActionState (gestión de estado)
- Hook useOptimistic (UI optimista)
- Manejo de errores en acciones
- Validación con Zod
- Devolución de JSON vs redirección
- Seguridad (autenticación, CSRF)
- Limitación de velocidad
- Transacciones de base de datos
🎯 Guía de la API de Metadatos
Más de 26 ejemplos que cubren:
- Metadatos estáticos (objeto exportado)
- Metadatos dinámicos (generateMetadata)
- Metadatos basados en archivos (icon.png, opengraph-image.png)
- Metadatos de Open Graph
- Twitter Cards
- Datos estructurados JSON-LD
- Configuración de Viewport
- Manifiesto PWA
- Robots.txt
- Generación de Sitemap
✅ Validador de Patrones
Script de Python ejecutable que verifica:
- Los Server Components no usan APIs exclusivas del cliente
- Los Client Components tienen la directiva 'use client'
- La obtención de datos usa la estrategia de caché adecuada
- Las Server Actions están marcadas con 'use server'
- La API de Metadatos se usa correctamente
- Optimización de imágenes ( no )
- Importaciones dinámicas para componentes pesados
Ejecuta con: python validate-patterns.py /ruta/a/src
Referencia Rápida
Árbol de Decisión: Server vs Client Components
¿Necesitas interactividad (onClick, onChange, etc.)?
├─ SÍ → Client Component ('use client')
└─ NO → Server Component (por defecto)
¿Necesitas hooks de React (useState, useEffect)?
├─ SÍ → Client Component
└─ NO → Server Component
¿Necesitas APIs del navegador (window, localStorage)?
├─ SÍ → Client Component
└─ NO → Server Component
¿Necesitas obtener datos?
├─ Usa Server Component (recomendado)
└─ Usa Client Component solo si los datos deben ser del lado del cliente
¿El componente es puramente de presentación?
└─ Server Component (mejor rendimiento)
Patrones Comunes
1. Server Component con obtención de datos
// app/projects/page.tsx
export default async function ProjectsPage() {
const projects = await db.project.findMany()
return <ProjectList projects={projects} />
}
2. Client Component con interactividad
// components/ProjectCard.tsx
'use client'
import { useState } from 'react'
export function ProjectCard({ project }: Props) {
const [loading, setLoading] = useState(false)
const handleDelete = async () => {
setLoading(true)
await deleteProject(project.id)
setLoading(false)
}
return (
<div>
<h2>{project.name}</h2>
<button onClick={handleDelete} disabled={loading}>
Eliminar
</button>
</div>
)
}
3. Server Action con formulario
// app/actions.ts
'use server'
export async function createProject(formData: FormData) {
const name = formData.get('name') as string
const project = await db.project.create({ data: { name } })
revalidatePath('/projects')
return { success: true, project }
}
// app/projects/new/page.tsx
import { createProject } from '@/app/actions'
export default function NewProjectPage() {
return (
<form action={createProject}>
<input name="name" required />
<button type="submit">Crear</button>
</form>
)
}
4. Streaming con Suspense
// app/dashboard/page.tsx
import { Suspense } from 'react'
export default function DashboardPage() {
return (
<div>
<Suspense fallback={<ProjectsSkeleton />}>
<ProjectsAsync />
</Suspense>
<Suspense fallback={<UsersSkeleton />}>
<UsersAsync />
</Suspense>
</div>
)
}
async function ProjectsAsync() {
const projects = await fetchProjects() // Consulta lenta
return <ProjectList projects={projects} />
}
5. Metadatos dinámicos
// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'
export async function generateMetadata({
params,
}: {
params: Promise<{ slug: string }>
}): Promise<Metadata> {
const { slug } = await params
const post = await fetchPost(slug)
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [post.coverImage],
},
}
}
Mejores Prácticas para Quetrex
1. Usa Server Components por defecto
// ✅ CORRECTO: Server Component (por defecto)
export default async function ProjectsPage() {
const projects = await fetchProjects()
return <ProjectList projects={projects} />
}
// ❌ INCORRECTO: Client Component cuando no es necesario
'use client'
export default function ProjectsPage() {
const [projects, setProjects] = useState([])
useEffect(() => {
fetchProjects().then(setProjects)
}, [])
return <ProjectList projects={projects} />
}
2. Usa la estrategia de caché adecuada
// Contenido estático (almacenado en caché para siempre)
const categories = await fetch('https://api.example.com/categories', {
cache: 'force-cache',
}).then(r => r.json())
// Contenido dinámico (sin caché)
const user = await fetch('https://api.example.com/me', {
cache: 'no-store',
}).then(r => r.json())
// ISR (revalidar cada hora)
const products = await fetch('https://api.example.com/products', {
next: { revalidate: 3600 },
}).then(r => r.json())
3. Implementa límites de error adecuados
// app/dashboard/error.tsx
'use client'
export default function DashboardError({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>¡Algo salió mal!</h2>
<button onClick={reset}>Intentar de nuevo</button>
</div>
)
}
4. Usa estados de carga
// app/dashboard/loading.tsx
export default function DashboardLoading() {
return <DashboardSkeleton />
}
5. Optimiza las imágenes
// ✅ CORRECTO: Usa next/image
import Image from 'next/image'
export function ProjectCard({ project }) {
return (
<Image
src={project.image}
alt={project.name}
width={400}
height={300}
/>
)
}
// ❌ INCORRECTO: Usa la etiqueta <img>
export function ProjectCard({ project }) {
return <img src={project.image} alt={project.name} />
}
Errores Comunes a Evitar
❌ Error 1: Client Component asíncrono
// ❌ INCORRECTO: Esto es un error de sintaxis
'use client'
export default async function BadComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
// ✅ CORRECTO: Usa Server Component o useEffect
export default async function GoodComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
❌ Error 2: APIs del cliente en Server Component
// ❌ INCORRECTO: Los Server Components no pueden usar APIs del navegador
export default function BadComponent() {
const [state, setState] = useState(false) // ¡Error!
return <div>{state}</div>
}
// ✅ CORRECTO: Añade la directiva 'use client'
'use client'
export default function GoodComponent() {
const [state, setState] = useState(false)
return <div>{state}</div>
}
❌ Error 3: Falta de estrategia de caché
// ❌ INCORRECTO: Comportamiento de caché poco claro
const data = await fetch('/api/data')
// ✅ CORRECTO: Estrategia de caché explícita
const data = await fetch('/api/data', {
cache: 'no-store', // o 'force-cache', o { next: { revalidate: 60 } }
})
❌ Error 4: No usar
// ❌ INCORRECTO: Imágenes no optimizadas
<img src="/logo.png" alt="Logo" />
// ✅ CORRECTO: Usa la optimización de imágenes de Next.js
<Image src="/logo.png" alt="Logo" width={200} height={100} />
Solución de Problemas
Error: "Estás importando un componente que necesita useState..."
Solución: Añade 'use client' al archivo del componente.
Error: "async/await no es válido en Client Components"
Solución: Elimina 'use client' o usa useEffect en lugar de un componente asíncrono.
Error: "process no está definido"
Solución: Las variables de entorno en Client Components necesitan el prefijo NEXT_PUBLIC_.
Error: "Headers ya enviados"
Solución: No uses headers() o cookies() después de enviar la respuesta. Llámalos antes de cualquier transmisión.
Documentación Oficial
- Documentos de Next.js 15.5: https://nextjs.org/docs
- App Router: https://nextjs.org/docs/app
- Obtención de datos: https://nextjs.org/docs/app/building-your-application/data-fetching
- Server Actions: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
- Caché: https://nextjs.org/docs/app/building-your-application/caching
- Metadatos: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
- Ejemplos: https://github.com/vercel/next.js/tree/canary/examples
Validación
Ejecuta el validador de patrones para revisar tu código:
python .claude/skills/nextjs-15-specialist/validate-patterns.py src/
El validador verifica:
- ✅ Client Components asíncronos (prohibido)
- ✅ APIs del cliente en Server Components
- ✅ Ubicación de la directiva 'use client'
- ✅ Funciones asíncronas de Server Actions
- ✅ Optimización de imágenes
- ✅ Metadatos en rutas dinámicas
- ✅ Importaciones dinámicas para componentes pesados
- ✅ Estrategias de caché de fetch
- ✅ Configuración de segmentos de ruta
Resumen
Esta habilidad garantiza que:
- Elijas el tipo de componente correcto (Server vs Client)
- Implementes patrones adecuados de obtención de datos
- Uses las estrategias de caché apropiadas
- Manejes correctamente las Server Actions
- Optimices metadatos y SEO
- Evites errores comunes de Next.js
- Sigas las pautas de arquitectura de Quetrex
En caso de duda:
- Lee la guía específica (enlaces arriba)
- Ejecuta el validador
- Consulta los documentos oficiales de Next.js 15
- Usa Server Components por defecto
Última actualización: 2025-11-23 Versión de Next.js: 15.5 Ejemplos totales: 150+ Líneas totales: 4,000+
