BIGboss248/nextjs-wordpress

Desarrollo de Páginas y Rutas en Next.js (nextjs-page-dev)

Flujo de trabajo especializado para crear páginas Next.js App Router listas para producción, con parámetros de ruta asíncronos, diccionarios de traducción localizados, metadatos dinámicos, datos estructurados JSON-LD con seguridad de tipos (schema-dts) y renderizado previo estático.

[!TIP] Activos Modulares y Guías Detalladas:

• Streaming y Límites de UI: references/streaming-and-boundaries.md
• Convenciones y Ciclo de Vida de Páginas: references/page-conventions-and-lifecycle.md
• Guía de SEO y Datos Estructurados: references/seo-structured-data-guide.md
• Plantillas Reutilizables: resources/templates/
• Script de Verificación: scripts/verify-page.ps1 (Windows) / scripts/verify-page.sh (Linux)

---

Reglas y Estándares Arquitectónicos

1. Contexto de Planificación y Registro de Rutas

• Lee docs/project.json para resolver supported_languages, dictionaries_dir (predeterminado: "messages") y new_component_dir.
• Todas las URL de navegación DEBEN hacer referencia a ROUTES desde @/lib/routes o @/i18n/navigation.
• Jerarquía de ruta objetivo: app/[locale]/<route-path>/page.tsx (o app/<route-path>/page.tsx si no está localizada).

2. Cero Hardcodeo y Población de Diccionarios

• Sin Texto Hardcodeado: Los encabezados, títulos, descripciones y etiquetas estáticas de la página deben agregarse a messages/[locale].json en todos los supported_languages antes de escribir JSX.
• Traducciones RSC: Lee las traducciones en los Componentes del Servidor usando await getTranslations('<namespace>').

3. SEO, Metadatos y JSON-LD

• Metadatos Dinámicos: Exporta generateMetadata({ params, searchParams }: Props) proporcionando title, description y URL canónica dinámicos (alternates: { canonical: ... }).
• Datos Estructurados: Inyecta JSON-LD tipado usando schema-dts (WithContext<T>) envuelto en <script type="application/ld+json"> con los caracteres < escapados como \u003c.
• Consulta references/seo-structured-data-guide.md para esquemas.

4. Renderizado Previo Estático (generateStaticParams)

• Si la página está anidada bajo un segmento dinámico [locale] (o cualquier segmento dinámico) y supported_languages contiene más de 1 locale, exporta generateStaticParams() retornando { locale } para todos los locales soportados.

5. Navegación Instantánea y Empuje Granular de Suspense

• Estados de Carga Granulares: Empuja <Suspense> hacia abajo a sub-componentes dinámicos específicos para que las secciones estáticas/en caché (encabezado, héroe, información de producto en caché) se eleven inmediatamente al Static Shell y App Shell.
• Exclusión: Si un segmento es inherentemente dinámico y no se desea retroalimentación instantánea, configura export const instant = false.
• Consulta references/streaming-and-boundaries.md para patrones de streaming.

---

Pasos del Flujo de Trabajo

• Paso 0: Generación del Plan de Implementación y Puerta de Aprobación

  • Lee docs/project.json y la definición de la ruta objetivo en lib/routes.ts.
  • Formula los metadatos de la página, el tipo de esquema JSON-LD, los espacios de nombres de traducción y el diseño de componentes.
  • Presenta un plan de implementación conciso al usuario si se están creando páginas nuevas importantes.

• Paso 1: Poblar los Diccionarios de Traducción

  • Agrega el título de la página, la meta descripción y el texto del cuerpo de la página en todos los archivos de locale (messages/en.json, messages/fa.json, etc.) bajo un espacio de nombres de página dedicado.

• Paso 2: Crear Esqueletos Compañeros (loading.tsx)

  • Si la página transmite contenido o obtiene datos, despliega loading.tsx desde loading.tsx.template.

• Paso 3: Implementar el Componente de Página (page.tsx)

  • Despliega y personaliza page.tsx.template:
    1. Define la interfaz de props async (params: Promise<{ locale: string, ... }>, searchParams).
    2. Exporta generateMetadata() resolviendo títulos dinámicos y alternativas canónicas.
    3. Exporta generateStaticParams() para rutas localizadas/dinámicas.
    4. Implementa la página RSC componiendo componentes de sección desde <new_component_dir>/<page-name>/.
    5. Renderiza el componente de datos estructurados <JsonLd>.

• Paso 4: Verificación y Comprobación de Cordura

  • Ejecuta el script de verificación de la página:
    • Windows (PowerShell):

      pwsh .agents/skills/nextjs-page-dev/scripts/verify-page.ps1 -RoutePath <route_dir>
      

    • Linux / macOS (Bash):

      bash .agents/skills/nextjs-page-dev/scripts/verify-page.sh <route_dir>
      

  • Asegúrate de que no haya errores de TypeScript ni de diccionarios faltantes.

• Paso 5: Sincronización de la Lista de Verificación del Plan de Implementación

  • Marca como completados los elementos de infraestructura de página (page.tsx, loading.tsx, error.tsx, generateMetadata, JSON-LD Schema, generateStaticParams()) en docs/plan/05-pages-and-components.md.
  • Si todas las sublistas de verificación de componentes y las tareas de infraestructura de página para esta página están completadas, marca el elemento de página principal (- [x]).