Geruyang/agent-skills-library

Mejores Prácticas de Next.js

Aplica estas reglas al escribir o revisar código Next.js.

Convenciones de Archivos

Consulta file-conventions.md para:

• Estructura del proyecto y archivos especiales
• Segmentos de ruta (dinámicos, catch-all, grupos)
• Rutas paralelas e interceptantes
• Renombramiento de middleware en v16 (middleware → proxy)

Límites de RSC

Detecta patrones inválidos de React Server Components.

Consulta rsc-boundaries.md para:

• Detección de componentes cliente asíncronos (inválido)
• Detección de props no serializables
• Excepciones de Server Actions

Patrones Asíncronos

Cambios en la API asíncrona de Next.js 15+.

Consulta async-patterns.md para:

• params y searchParams asíncronos
• cookies() y headers() asíncronos
• Codemod de migración

Selección de Runtime

Consulta runtime-selection.md para:

• Usar Node.js runtime por defecto
• Cuándo es apropiado Edge runtime

Directivas

Consulta directives.md para:

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

Funciones

Consulta functions.md para:

• Hooks de navegación: useRouter, usePathname, useSearchParams, useParams
• Funciones de servidor: cookies, headers, draftMode, after
• Funciones generadoras: generateStaticParams, generateMetadata

Manejo de Errores

Consulta error-handling.md para:

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized (errores de autenticación)
• unstable_rethrow para bloques catch

Patrones de Datos

Consulta data-patterns.md para:

• Server Components vs Server Actions vs Route Handlers
• Evitar cascadas de datos (Promise.all, Suspense, preload)
• Obtención de datos en componentes cliente

Route Handlers

Consulta route-handlers.md para:

• Conceptos básicos de route.ts
• Conflictos del handler GET con page.tsx
• Comportamiento del entorno (sin React DOM)
• Cuándo usar vs Server Actions

Metadatos e Imágenes OG

Consulta metadata.md para:

• Metadatos estáticos y dinámicos
• Función generateMetadata
• Generación de imágenes OG con next/og
• Convenciones de metadatos basadas en archivos

Optimización de Imágenes

Consulta image.md para:

• Usar siempre next/image en lugar de <img>
• Configuración de imágenes remotas
• Atributo sizes responsive
• Marcadores de posición blur
• Carga prioritaria para LCP

Optimización de Fuentes

Consulta font.md para:

• Configuración de next/font
• Google Fonts, fuentes locales
• Integración con Tailwind CSS
• Precarga de subconjuntos

Empaquetado

Consulta bundling.md para:

• Paquetes incompatibles con servidor
• Importaciones CSS (no etiquetas link)
• Polyfills (ya incluidos)
• Problemas de ESM/CommonJS
• Análisis de bundles

Scripts

Consulta scripts.md para:

• next/script vs etiquetas script nativas
• Scripts en línea requieren id
• Estrategias de carga
• Google Analytics con @next/third-parties

Errores de Hidratación

Consulta hydration-error.md para:

• Causas comunes (APIs del navegador, fechas, HTML inválido)
• Depuración con superposición de errores
• Soluciones para cada causa

Límites de Suspense

Consulta suspense-boundaries.md para:

• Bailout de CSR con useSearchParams y usePathname
• Qué hooks requieren límites de Suspense

Rutas Paralelas e Interceptantes

Consulta parallel-routes.md para:

• Patrones de modales con slots @ e interceptores (.)
• default.tsx para fallbacks
• Cerrar modales correctamente con router.back()

Auto-hosting

Consulta self-hosting.md para:

• output: 'standalone' para Docker
• Manejadores de caché para ISR multi-instancia
• Qué funciona vs qué necesita configuración adicional

Trucos de Depuración

Consulta debug-tricks.md para:

• Endpoint MCP para depuración asistida por IA
• Reconstruir rutas específicas con --debug-build-paths