BIGboss248/nextjs-wordpress

Desenvolvimento de Páginas e Rotas Next.js (nextjs-page-dev)

Fluxo de trabalho especializado para criar páginas prontas para produção no Next.js App Router com parâmetros de rota assíncronos, dicionários de tradução localizados, metadados dinâmicos, dados estruturados JSON-LD com segurança de tipos (schema-dts) e pré-renderização estática.

[!TIP] Ativos Modulares e Guias Detalhados:

• Streaming e Limites de UI: references/streaming-and-boundaries.md
• Convenções e Ciclo de Vida de Páginas: references/page-conventions-and-lifecycle.md
• Guia de SEO e Dados Estruturados: references/seo-structured-data-guide.md
• Modelos Reutilizáveis: resources/templates/
• Script de Verificação: scripts/verify-page.ps1 (Windows) / scripts/verify-page.sh (Linux)

---

Regras e Padrões Arquiteturais

1. Contexto de Planejamento e Registro de Rotas

• Leia docs/project.json para resolver supported_languages, dictionaries_dir (padrão: "messages") e new_component_dir.
• Todas as URLs de navegação DEVEM referenciar ROUTES de @/lib/routes ou @/i18n/navigation.
• Hierarquia do caminho da página alvo: app/[locale]/<route-path>/page.tsx (ou app/<route-path>/page.tsx se não for localizada).

2. Zero Hardcoding e População de Dicionários

• Sem Código Fixo: Títulos de página, cabeçalhos, descrições e rótulos estáticos devem ser adicionados a messages/[locale].json em todos os supported_languages antes de escrever JSX.
• Traduções RSC: Leia traduções em Componentes Servidor usando await getTranslations('<namespace>').

3. SEO, Metadados e JSON-LD

• Metadados Dinâmicos: Exporte generateMetadata({ params, searchParams }: Props) fornecendo title, description e URL canônica (alternates: { canonical: ... }) dinâmicos.
• Dados Estruturados: Injete JSON-LD tipado usando schema-dts (WithContext<T>) envolto em <script type="application/ld+json"> com caracteres < escapados como \u003c.
• Consulte references/seo-structured-data-guide.md para esquemas.

4. Pré-renderização Estática (generateStaticParams)

• Se a página estiver aninhada sob um segmento dinâmico [locale] (ou qualquer segmento dinâmico) e supported_languages contiver mais de 1 localidade, exporte generateStaticParams() retornando { locale } para todas as localidades suportadas.

5. Navegação Instantânea e Suspense Granular Push-Down

• Estados de Carregamento Granulares: Empurre <Suspense> para componentes dinâmicos específicos para que seções estáticas/em cache (cabeçalho, hero, informações de produto em cache) sejam elevadas para o Static Shell e App Shell imediatamente.
• Optando por não usar: Se um segmento é inerentemente dinâmico e o feedback instantâneo não é desejado, configure export const instant = false.
• Consulte references/streaming-and-boundaries.md para padrões de streaming.

---

Etapas do Fluxo de Trabalho

• Etapa 0: Geração do Plano de Implementação e Gate de Aprovação

  • Leia docs/project.json e a definição da rota alvo em lib/routes.ts.
  • Formule metadados da página, tipo de esquema JSON-LD, namespaces de tradução e layout de componentes.
  • Apresente um plano de implementação conciso ao usuário se estiver criando páginas novas importantes.

• Etapa 1: Popular Dicionários de Tradução

  • Adicione título da página, meta descrição e texto do corpo da página em todos os arquivos de localidade (messages/en.json, messages/fa.json, etc.) sob um namespace de página dedicado.

• Etapa 2: Criar Esqueletos de Companhia (loading.tsx)

  • Se a página transmitir conteúdo ou buscar dados, implante loading.tsx a partir de loading.tsx.template.

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

  • Implante e personalize page.tsx.template:
    1. Defina a interface de props assíncrona (params: Promise<{ locale: string, ... }>, searchParams).
    2. Exporte generateMetadata() resolvendo títulos dinâmicos e alternativas canônicas.
    3. Exporte generateStaticParams() para rotas localizadas/dinâmicas.
    4. Implemente a página RSC compondo componentes de seção a partir de <new_component_dir>/<page-name>/.
    5. Renderize o componente de dados estruturados <JsonLd>.

• Etapa 4: Verificação e Sanity Check

  • Execute o script de verificação da 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>
      

  • Garanta zero erros de TypeScript ou dicionários ausentes.

• Etapa 5: Sincronização da Lista de Verificação do Plano de Implementação

  • Marque os itens de infraestrutura de página concluídos (page.tsx, loading.tsx, error.tsx, generateMetadata, JSON-LD Schema, generateStaticParams()) em docs/plan/05-pages-and-components.md.
  • Se todas as sublistas de verificação de componentes e tarefas de infraestrutura de página para esta página estiverem concluídas, marque o item da página pai (- [x]).