bigboss248/nextjs-wordpress

Integração Next.js WooCommerce (nextjs-woocommerce)

Guia operacional e checklist para arquitetar, consultar e integrar aplicações Next.js App Router com um backend WooCommerce headless via WPGraphQL, WooGraphQL e Autenticação JWT.

---

Pré-requisitos e Referências da Documentação

• Projeto Next.js 14+ inicializado com App Router e TypeScript.
• Backend WooCommerce ativo com WPGraphQL, WooGraphQL e wp-graphql-jwt-authentication.
• Para esquemas API completos e padrões de código Next.js, consulte nextjs-woocommerce-reference.md.
• Para implementação reutilizável de cliente de busca de dados, veja woocommerce-fetcher.ts.

---

Checklist de Implementação Passo a Passo

flowchart TD
    S1["1. Configuração de Ambiente e Cliente"] --> S2["2. Catálogo Público de Produtos (ISR/SSG)"]
    S2 --> S3["3. Autenticação de Usuário (JWT + Cookies)"]
    S3 --> S4["4. Perfil Protegido e Histórico de Pedidos"]
    S4 --> S5["5. Sessão de Carrinho e Ponte de Checkout Nativo"]

Fase 1: Configuração de Ambiente e Cliente

• Configurar Variáveis de Ambiente:
  • Adicione NEXT_PUBLIC_WORDPRESS_API_URL=https://sua-loja.com/graphql ao .env.example e .env.development.
  • Adicione NEXT_PUBLIC_WORDPRESS_URL=https://sua-loja.com para redirecionamentos de checkout.
• Configurar Buscador Universal:
  • Implemente woocommerce-fetcher.ts com suporte a cache ISR e cabeçalhos de autenticação.

Fase 2: Catálogo Público de Produtos e Taxonomias

• Navegação por Categoria: Consulte productCategories com hideEmpty: true para cabeçalhos e menus de categoria.
• Arquivo de Grade de Produtos: Consulte products usando fragmentos de união (... on SimpleProduct, ... on VariableProduct). Configure next: { revalidate: 300, tags: ['products'] }.
• Página de Detalhe do Produto: Pré-renderize rotas dinâmicas (app/products/[slug]/page.tsx) com generateStaticParams() consultando todos os slugs de produtos.

Fase 3: Pipeline de Autenticação JWT

• Mutation de Login: Implemente Server Action executando login(input: { username, password }).
• Armazenamento de Cookie: Armazene o authToken retornado em um cookie seguro HttpOnly (auth_token).
• Ligação de Sessão: Se o cliente retornar sessionToken, armazene no cookie wc_session.
• Logout: Limpe os cookies de autenticação no logout do usuário.

Fase 4: Dados Protegidos do Usuário e Pedidos

• Perfil do Cliente: Consulte viewer { id name email } passando Authorization: Bearer <authToken>.
• Histórico de Pedidos: Consulte customer { orders { nodes { id orderNumber total status } } } com cache: 'no-store'.

Fase 5: Gerenciamento de Carrinho e Estratégia de Checkout

• Estado do Carrinho: Capture e persista o cabeçalho woocommerce-session retornado nas mutations addToCart.
• Ponte de Checkout Nativo:
  • Redirecione usuários para https://sua-loja.com/checkout para aproveitar os gateways de pagamento nativos do WooCommerce (ZarinPal, Mellat, Stripe), logística regional e selos de conformidade sem reescrever gateways personalizados.

---

Casos de Borda e Armadilhas Conhecidas

1. Desotimização Estática vs. Dinâmica: Ler cookies no layout raiz ou páginas de produto muda o Next.js para modo dinâmico SSR completo. Leia cookies de autenticação apenas dentro de Server Actions, Route Handlers ou subárvores isoladas do painel de conta (app/account/...).
2. Fragmentos Polimórficos: Consultas diretas como products { nodes { price } } falharão na validação no WooGraphQL. Sempre envolva preços e variações em ... on SimpleProduct e ... on VariableProduct.
3. Perda de Sessão: Ao adicionar itens ao carrinho, não reenviar o cabeçalho woocommerce-session cria um novo carrinho vazio a cada mutation.
4. CORS no Endpoint GraphQL: Certifique-se de que o WordPress envie os cabeçalhos Access-Control-Allow-Origin e Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session para o domínio do seu Next.js.

---

Verificação e Testes de Pré-voo

• pnpm build é bem-sucedido com a geração estática das páginas de produto.
• Teste se o formulário de login emite auth_token e redireciona para o painel.
• A página de conta renderiza os detalhes do cliente e a lista de pedidos com token válido.
• Adicionar ao carrinho atualiza a contagem de itens do carrinho em várias requisições do cliente.