WordPress headless com Next.js: um blog completo

Eu uso a combinação Next.js + WordPress desde bem antes da IA existir. O motivo foi bem prático: um cliente com área de membros em WordPress, que ficou pesada e lenta, tanto no front-end quanto no back-end. Em vez de migrar todos os usuários, todas as vídeo-aulas e todo o material do curso para uma aplicação nova, eu mantive o WordPress como back-end e coloquei um front-end em Next.js na frente. Funcionou muito bem.

Neste post eu mostro esse mesmo caminho na prática: pegar uma instalação WordPress, tirar dela a responsabilidade de exibir o site e usar apenas o painel administrativo, com todo o front-end em Next.js, construído com a ajuda do Claude Code.

O que significa WordPress headless?

Headless quer dizer usar o WordPress apenas como API. Você tira dele toda a responsabilidade de mostrar o site e ele passa a ser só o back-end da aplicação.

Na prática, existem dois endereços diferentes:

Endereço	Papel
dev.seusite.com (WordPress)	Back-end e painel. Quem acessa é só quem alimenta o conteúdo.
seusite.com (Next.js)	Front-end. É o que o visitante enxerga.

O visitante não deve acessar o WordPress diretamente. Ele acessa o Next.js, que por sua vez busca o conteúdo via REST API. O front-end nunca fala com o banco de dados do WordPress. Ele fala com o serviço REST que o WordPress já expõe nativamente.

O tema do WordPress deixa de existir para o público. Toda a camada visual passa a ser sua, no Next.js.

Quando vale a pena usar WordPress headless?

Depende do projeto. Vale muito a pena quando:

• O cliente já está preso ao WordPress e tem todo o histórico de posts lá dentro.
• Você quer performance de front-end moderno sem migrar conteúdo nenhum.
• A equipe do cliente já sabe usar o painel do WordPress, então não há retrabalho de treinamento.
• Existe um gargalo de performance no tema atual que você não consegue resolver.

Não vale a pena quando o site é novo. Se você vai criar tudo do zero, provavelmente é mais simples iniciar direto em Next.js com outro CMS, ou simplesmente usar WordPress tradicional mesmo. A análise é sua, caso a caso.

A vantagem de manter o WordPress é ter um CMS consolidado, conhecido pelo cliente e com todos os dados já cadastrados.

Como acessar os posts pela REST API nativa do WordPress?

Isso já vem ligado em qualquer instalação WordPress. Não precisa de plugin nenhum. Basta acrescentar o caminho da API depois da URL do site:

https://seusite.com/wp-json/wp/v2/posts

O retorno é um JSON com todos os artigos. É esse endpoint que a aplicação Next.js vai consumir.

Quantos posts por página?

/wp-json/wp/v2/posts?per_page=6
/wp-json/wp/v2/posts?per_page=20&page=2

O per_page aceita de 1 a 100 (o padrão é 10). Para paginar, combine com page.

Como buscar por um termo?

/wp-json/wp/v2/posts?search=vero

Como retornar só os campos que interessam?

Por padrão a API devolve todos os campos, e o JSON fica gigante. Use _fields para enxugar:

/wp-json/wp/v2/posts?_fields=id,title,slug

Isso reduz drasticamente o tamanho da resposta e é uma das otimizações mais importantes numa aplicação headless.

Como trazer a imagem destacada?

A imagem destacada não vem embutida por padrão, só o ID dela. Para trazer o objeto completo, use _embed:

/wp-json/wp/v2/posts?_embed

O resultado aparece dentro de _embedded['wp:featuredmedia'], com todos os tamanhos gerados pelo WordPress.

Outros parâmetros úteis

Estes não apareceram no vídeo, mas são os que eu mais uso no dia a dia:

Parâmetro	Para que serve
orderby	Ordena por date, title, slug, modified, id ou relevance
order	asc ou desc
categories	Filtra por ID de categoria (?categories=5)
categories_exclude	Exclui categorias do resultado
tags	Filtra por ID de tag
author	Filtra por ID do autor
slug	Busca um post específico pelo slug (?slug=meu-post)
offset	Pula N resultados
after / before	Filtra por data em ISO 8601 (?after=2025-01-01T00:00:00)
sticky	true traz só os posts fixados

Combinando tudo:

/wp-json/wp/v2/posts?_embed&_fields=id,title,slug,excerpt&per_page=9&orderby=date&order=desc

Como saber o total de páginas?

A contagem não vem no corpo do JSON. Vem nos cabeçalhos da resposta:

curl -I "https://seusite.com/wp-json/wp/v2/posts?per_page=10"

X-WP-Total: 137
X-WP-TotalPages: 14

É com esses dois cabeçalhos que você monta a paginação do blog no Next.js.

Os outros endpoints do namespace wp/v2

/wp-json/wp/v2/posts       posts
/wp-json/wp/v2/pages       páginas
/wp-json/wp/v2/categories  categorias
/wp-json/wp/v2/tags        tags
/wp-json/wp/v2/users       autores
/wp-json/wp/v2/media       biblioteca de mídia
/wp-json/wp/v2/search      busca genérica em todos os tipos

E se o site estiver com permalinks simples, a API responde também nesta forma alternativa:

/?rest_route=/wp/v2/posts

Existe ainda o plugin WPGraphQL, que organiza bem essas consultas e evita over-fetching. Mas aqui a proposta é usar só o que já é nativo, sem plugin de ponte.

O que instalar antes de começar?

Só o Node. O Next.js roda em cima dele.

node -v

Se aparecer a versão, está tudo certo. Se não aparecer, baixe o Node no site oficial, instale (no Windows é bem tranquilo), reinicie o terminal e rode o comando de novo.

Depois é só criar a pasta do projeto e abrir o Claude Code dentro dela:

mkdir blogwp
cd blogwp
claude

Por que instalar o Context7 antes de pedir o código?

Porque sem ele o Claude vai escrever a integração de memória, e a memória dele pode estar desatualizada em relação à documentação da REST API do WordPress e do Next.js.

O Context7 é um MCP que consulta a documentação atualizada na hora. Ele busca como cada recurso está escrito na documentação oficial e liga uma coisa na outra sozinho.

Dentro do Claude Code, instale pelo menu de plugins:

/plugin

Procure por context7 na lista e instale. Essa etapa é o que faz a diferença entre um código que funciona e um código que inventa parâmetro que não existe.

Qual prompt usar para o Claude criar o blog?

Este foi o prompt completo. Não precisou de mais nada:

Preciso de um blog feito em Next.js. Crie esse blog usando as boas práticas
do framework Next.js. Esse blog vai puxar os posts de uma API nativa do
WordPress. Essa API fica num WordPress headless no endereço
https://dev.seusite.com/tp/

Use o Context7 para consultar a documentação do WordPress e fazer o uso
correto da API nativa.

Duas dicas sobre como rodar esse prompt:

1. Use o modo plano. Deixe o Claude planejar antes de escrever qualquer arquivo.
2. Planeje com o Fable 5 e execute com o Opus. Eu gosto de planejar com o Fable 5 e depois trocar de modelo para a execução. Se você não tiver o Fable 5 disponível no seu plano, tudo bem, dá para chegar no mesmo resultado sem ele.

Para conferir e trocar o modelo antes de executar:

/model

Quais decisões o Claude pede antes de gerar o plano?

Ele faz algumas perguntas de escopo. As que importam:

Qual o escopo do blog? Eu pedi completo: home, post individual, arquivo, categoria. Tudo isso a API nativa wp/v2 já expõe.

Qual o visual? As opções eram Tailwind CSS v4 com design próprio, minimalista em CSS puro, ou componentes prontos. Escolhi Tailwind v4 com design próprio.

Como tratar o cache do conteúdo vindo do WordPress? Essa é a decisão mais importante do projeto:

Estratégia	Como funciona	Trade-off
ISR	Páginas estáticas regeneradas a cada N segundos	Simples e rápido, sem configurar nada no WordPress. Conteúdo demora até N segundos para atualizar.
ISR + webhook on-demand	O WordPress avisa o Next.js quando algo muda	Atualização instantânea, mas exige configuração do lado do WordPress.
SSR	Toda requisição bate na API do WordPress	Conteúdo sempre fresco, porém lento e dependente da disponibilidade do WordPress.

Escolhi ISR. É o melhor custo-benefício: o Next.js gera as páginas estáticas, guarda essa versão e revalida de tempos em tempos para ver se o conteúdo mudou lá no WordPress.

A diferença de performance é grande. No WordPress tradicional, cada visita bate no banco de dados. Com ISR, o Next.js já tem a versão pronta do post e serve direto, sem várias requisições ao banco a cada acesso.

O que o projeto gerado tem dentro?

O resultado é um blog em Next.js 16 com App Router, React 19 e Turbopack, Tailwind CSS v4 usando tokens próprios em @theme (sem tailwind.config), e ISR revalidando a cada 5 minutos. A única dependência além do framework é o html-react-parser.

As rotas ficaram assim:

Rota	Renderização
/	Estática + ISR
/page/[page]	ISR, pré-gerada a partir do total de páginas
/[slug]	ISR, pré-gerada com generateStaticParams
/categoria/[slug] (+ /page/N)	ISR (página 1 pré-gerada)
/tag/[slug] (+ /page/N)	ISR sob demanda
/autor/[slug] (+ /page/N)	ISR (página 1 pré-gerada)
/busca?q=	Dinâmica, noindex

Repare no padrão dos colchetes: toda pasta entre colchetes é uma rota dinâmica. O [slug] de /[slug]/page.tsx é o que chega como parâmetro para buscar aquele post específico na API.

A página 1 de qualquer arquivo mora na raiz dele, e /page/1 redireciona com 307, para o mesmo conteúdo não existir em dois endereços diferentes.

Cuidado com os slugs reservados

Como o post individual é servido em /[slug], na raiz, as rotas literais têm precedência. Então não crie posts no WordPress com os slugs page, categoria, tag, autor ou busca. Eles ficariam inacessíveis. A lista fica em RESERVED_SLUGS, no arquivo src/lib/wordpress/config.ts.

Como rodar o projeto na sua máquina?

cp .env.example .env.local
npm install
npm run dev

Depois é só acessar http://localhost:3000.

Duas coisas que não sobem para o Git, e o Claude já deixou as duas no .gitignore:

node_modules/
.next/

Por isso, ao subir o projeto para outro lugar, o npm install é obrigatório: é ele que recria a pasta node_modules.

As variáveis de ambiente

Variável	Para que serve
WORDPRESS_API_URL	Base da REST API (.../wp-json/wp/v2). Server-only, sem NEXT_PUBLIC_.
NEXT_PUBLIC_SITE_URL	Origem pública do site. Alimenta metadataBase, canonical, sitemap e robots.

Atenção a uma pegadinha: o NEXT_PUBLIC_SITE_URL entra no bundle no momento do build. Ao publicar, defina o domínio real antes de rodar npm run build, senão o sitemap e as tags Open Graph vão sair apontando para localhost.

Por que as imagens do WordPress não aparecem no Next.js?

Esse é o problema mais comum de quem monta um headless pela primeira vez.

O componente de imagem do Next.js precisa saber quais domínios externos estão autorizados a fornecer imagens. Se o domínio não estiver na lista, a imagem simplesmente não carrega. A configuração fica em next.config.ts:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "dev.seusite.com",
        pathname: "/tp/wp-content/uploads/**",
      },
    ],
  },
};

export default nextConfig;

O Claude já cria esse bloco apontando para a pasta wp-content/uploads do WordPress que você informou. Mas se um dia você mudar o domínio do WordPress, precisa mudar aqui também, senão as imagens param de aparecer.

Como colocar essa aplicação no ar?

Você tem três caminhos:

Hostinger. Dá para subir uma aplicação Next com poucos cliques no painel.

VPS na mão. Suba os arquivos (menos o node_modules) e rode, já no servidor:

npm install
npm run build
npm run start

O build precisa acontecer no servidor, depois de definir as variáveis de ambiente. Vale pedir ajuda ao Claude nessa etapa. Eu tenho skills próprias que sobem a aplicação direto no meu VPS.

Vercel. É quem criou o Next.js e tem uma camada gratuita para projetos pequenos. Fique de olho nos termos de uso e nos limites do plano.

O código-fonte do projeto

O projeto completo está disponível para você usar como base, modificar e criar o seu próprio blog:

https://github.com/tpwebmaster/blogwp

Foi tudo planejado com o Fable 5 e executado com o Opus, consultando a documentação pelo Context7, e o resultado é um blog completo consumindo os posts de uma instalação WordPress real.