Headless WordPress + Next.js: a battle plan for 2026

O que significa headless

Em uma configuração headless, o WordPress continua sendo o lugar onde os editores escrevem e gerenciam o conteúdo, mas deixa de renderizar o site público. Um front-end separado — aqui, o Next.js — busca o conteúdo pela REST API do WordPress ou pelo WPGraphQL e monta as páginas.

Os benefícios são velocidade, segurança (o painel do WordPress pode ficar em um endereço privado), liberdade de design e a possibilidade de enviar o mesmo conteúdo para um site, apps e outros canais. Os custos são dois sistemas para hospedar e manter, e recursos que os temas e plugins do WordPress normalmente oferecem precisam ser reconstruídos no front-end.

Quando vale a pena

• Grandes sites de conteúdo e publishers, em que velocidade e escala importam.
• Marcas que precisam de um front-end altamente personalizado, com cara de app.
• Conteúdo compartilhado entre um site, apps mobile e outros canais.
• Equipes que já têm desenvolvedores React ou Next.js.

Para um site institucional ou uma pequena empresa com poucas páginas, um tema WordPress tradicional bem feito costuma ser mais barato e igualmente rápido.

Renderização: páginas estáticas que continuam atualizadas

Gere as páginas de forma estática e sirva-as a partir de uma CDN, para que os visitantes recebam o HTML instantaneamente. Em vez de reconstruir o site inteiro, use a revalidação sob demanda: quando um editor publica ou atualiza um post, um pequeno hook do WordPress chama um endpoint secreto no Next.js, que revalida apenas as páginas ou tags afetadas. O conteúdo vai ao ar em segundos, e as páginas continuam rápidas.

// app/api/revalidate/route.js — called by WordPress on publish
import { revalidateTag } from 'next/cache';

export async function POST(request) {
  const { secret, tag } = await request.json();
  if (secret !== process.env.REVALIDATE_SECRET) {
    return Response.json({ ok: false }, { status: 401 });
  }
  revalidateTag(tag);
  return Response.json({ ok: true });
}

Pré-visualizações para editores

Os editores esperam que o botão Visualizar funcione. Use o draft mode do Next.js: o WordPress aponta para uma rota de pré-visualização com um segredo e o ID do post, a rota ativa o draft mode e a página busca a revisão mais recente com uma requisição autenticada (por exemplo, com uma senha de aplicativo ou um token). Teste as pré-visualizações de posts não publicados, posts agendados e páginas com campos personalizados.

SEO em um projeto headless

• Exponha os campos do plugin de SEO (título, descrição, canonical, imagem social, schema) pela API e renderize-os nos metadados do Next.js.
• Gere o sitemap e o robots.txt a partir do front-end, usando o conteúdo do WordPress.
• Gerencie os redirecionamentos no WordPress e sincronize-os com o front-end, para que os editores mantenham o controle.
• Mantenha as URLs idênticas durante uma migração ou redirecione todas as URLs antigas.

Imagens, formulários e busca

Sirva as mídias do WordPress pela otimização de imagens do Next.js ou por uma CDN de imagens, com o domínio de mídia do WordPress liberado na configuração. Os formulários precisam de um destino: envie-os para uma rota do Next.js que valide e encaminhe para o seu CRM ou e-mail, ou use a API de um plugin de formulários. A busca do site normalmente passa para um serviço dedicado ou um endpoint de API simples, porque a página de busca do tema deixa de existir.

Armadilhas que planejamos

• Page builders armazenam o layout como shortcodes ou marcação proprietária, difícil de renderizar em outro lugar; prefira blocos do Gutenberg ou campos personalizados.
• Menus, widgets e recursos de plugins que dependem de um tema precisam de equivalentes na API.
• Proteja o painel do WordPress e desative o tema público para evitar conteúdo duplicado.
• Conteúdo multilíngue precisa de um plugin com suporte à API e de uma estratégia clara de URLs no Next.js.

Um checklist antes de começar

Definam o modelo de conteúdo (tipos de post, campos, blocos), como funcionam as pré-visualizações e a publicação, onde ficam os redirecionamentos e os campos de SEO, como serão tratados os formulários e a busca, e quem hospeda e monitora cada uma das partes. Com essas decisões tomadas desde o início, o WordPress headless dá aos editores a ferramenta que eles já conhecem e aos visitantes um site rápido em qualquer lugar.