WordPress Headless + Next.js: O Guia que Eu Gostaria de Ter Quando Comecei

Por Que Headless WordPress?

O WordPress alimenta mais de 43% da web. Tem um ecossistema maduro, uma interface de edição que qualquer não-técnico consegue usar, e uma comunidade enorme. O problema é que o front-end WordPress clássico (PHP + temas) não combina com a performance e a DX que um desenvolvedor frontend moderno espera.

A solução é usar o WordPress apenas como CMS, um backend para gerenciar conteúdo, e construir o front-end com Next.js. Isso é o que chamamos de headless WordPress.

A Arquitetura

WordPress (Pantheon.io)
  └── WPGraphQL Plugin
        └── GraphQL API endpoint
              │
              └──> Next.js (Vercel)
                    ├── /blog          (ISR - revalida a cada hora)
                    └── /blog/[slug]   (ISR - revalida a cada hora)

Pré-requisitos

• Conta no Pantheon.io (gratuita)
• Projeto Next.js 14+ configurado
• Conhecimento básico de WordPress Admin

1. Criando o Site WordPress no Pantheon

O Pantheon tem um tier gratuito para desenvolvimento. Acesse pantheon.io, crie uma conta, e em "Create New Site" escolha WordPress.

Após o provisionamento (~2 minutos), você terá:

• URL do admin: dev-seu-site.pantheonsite.io/wp-admin
• 3 ambientes: Dev, Test, Live
• Git integrado para deploys

2. Instalando WPGraphQL

No WP Admin → Plugins → Add New, busque por "WPGraphQL" e instale. Após ativar, você verá um item "GraphQL" no menu lateral com um IDE integrado (GraphiQL) para testar queries.

O endpoint da API será: https://seu-site.pantheonsite.io/graphql

3. Instalando ACF + WPGraphQL for ACF

O ACF (Advanced Custom Fields) permite criar campos customizados nos posts, como "tempo de leitura", "destaque", etc. A versão gratuita já é suficiente.

Instale também o "WPGraphQL for ACF" para que esses campos apareçam na API GraphQL.

4. Criando o Field Group no ACF

Em ACF → Field Groups → Add New, crie um grupo chamado "Detalhes do Post" com os campos:

• reading_time (Number): tempo estimado de leitura em minutos
• featured (True/False): se o post deve aparecer em destaque

Em "Location Rules", configure para aparecer quando Post Type = Post. Em "GraphQL", ative "Show in GraphQL" e defina o nome do campo como postDetails.

5. Consultando a API no Next.js

// lib/wordpress.ts
const WP_GRAPHQL_URL = process.env.WP_GRAPHQL_URL;

const GET_POSTS_QUERY = `
  query GetPosts {
    posts(first: 12, where: { status: PUBLISH }) {
      nodes {
        slug
        title
        excerpt
        date
        postDetails {
          readingTime
          featured
        }
        categories {
          nodes { name slug }
        }
      }
    }
  }
`;

export async function getAllPosts() {
  const res = await fetch(WP_GRAPHQL_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: GET_POSTS_QUERY }),
    next: { revalidate: 3600 }, // ISR: revalida a cada hora
  });
  const { data } = await res.json();
  return data.posts.nodes;
}

6. ISR: O Melhor dos Dois Mundos

Com ISR (Incremental Static Regeneration), as páginas do blog são geradas estáticamente (rápidas como CDN), mas podem ser atualizadas sem rebuild completo:

// app/blog/[slug]/page.tsx
export const revalidate = 3600; // revalida a cada 1 hora

// Ou use revalidação on-demand via webhook:
// POST /api/revalidate?secret=xxx&slug=meu-post

Conclusão

A combinação WordPress + WPGraphQL + Next.js é poderosa porque une o melhor de dois mundos: a familiaridade do WordPress para editores de conteúdo, e a performance e DX do Next.js para desenvolvedores. Para projetos onde não-técnicos precisam gerenciar conteúdo, é difícil bater essa stack.