AstroPress: Um Starter WordPress Headless + Astro com 0 KB de JS no Cliente

O AstroPress é um starter open-source que desacopla o WordPress da renderização de páginas: o WordPress permanece como backend editorial puro — Gutenberg, taxonomias, biblioteca de mídia — enquanto o Astro consulta a REST API do WordPress inteiramente em tempo de build e compila HTML/CSS estático para o edge, enviando 0 KB de JavaScript no cliente por padrão nas páginas editoriais. O projeto está no GitHub sob licença MIT.

O problema que ele resolve é específico e comum: o WordPress é genuinamente bom como experiência de edição de conteúdo para autores não técnicos, e genuinamente ruim como runtime de renderização de página quando tráfego ou requisitos de performance ficam sérios. A maioria dos tutoriais de “WordPress headless” para no “chame a REST API a partir do seu frontend”. O AstroPress vai além — é uma stack opinativa e completa, com uma camada real de normalização de conteúdo, um plugin WordPress complementar para preview autenticado de rascunho, orçamentos de performance aplicados em CI e uma ferramenta de diagnóstico que verifica todo o pipeline de ponta a ponta.

Por Que Desacoplar o WordPress da Renderização

Um tema WordPress convencional executa PHP em cada requisição: inicializa o WordPress, roda os hooks de cada plugin ativo, consulta o MySQL pelo post e seus metadados, renderiza um template e só então envia o HTML. Sob carga, ou com uma pilha pesada de plugins, é nesse caminho que nascem a maioria dos problemas de performance do WordPress — não no frontend.

O WordPress headless remove o PHP do caminho de requisição das páginas de conteúdo por completo. O WordPress vira uma fonte de dados consumida em tempo de build (ou via SSR sob demanda para os poucos casos que realmente precisam, como o preview de rascunho); a página que o visitante carrega de fato é HTML estático servido pelo edge, sem ida ao banco de dados por requisição. O trade-off é real: você abre mão da ergonomia “instalou o plugin, ganhou a funcionalidade” de um tema WordPress monolítico, em troca de uma performance de renderização que não degrada sob tráfego.

Arquitetura: Camada de Conteúdo, Não Só uma Chamada de API

O docs/architecture.md do AstroPress documenta o fluxo de dados assim: WordPress → REST API (/wp-json/wp/v2/*) → um cliente WordPress (client.ts) → JSON bruto → uma camada de conteúdo (src/lib/wordpress/) que normaliza o payload → dados tipados e normalizados consumidos por rotas e componentes do Astro → HTML estático (ou a rota de preview sob demanda).

A camada de conteúdo é a parte que importa arquiteturalmente. Em vez de deixar o formato da resposta REST do WordPress vazar para cada componente de página — nomes de campo, objetos de taxonomia aninhados, peculiaridades específicas do WordPress —, a camada de normalização isola isso completamente. Os componentes consomem um formato tipado e definido pelo próprio projeto; se a resposta da API do WordPress mudar, ou você trocar um plugin que altera o payload, o ajuste é feito num único lugar, em vez de caçar cada template que tocava post.acf.algum_campo diretamente.

O projeto também documenta limites explícitos de JavaScript: fetches ou hidratação no lado do cliente são proibidos para conteúdo já conhecido em tempo de build — é exatamente para isso que existem a camada de conteúdo e a geração estática. Ilhas do Astro só são permitidas para interatividade de escopo estreito que genuinamente não pode ser estática, como uma caixa de busca no cliente. É a mesma disciplina que impede uma arquitetura “static-first” de regredir silenciosamente para uma aplicação renderizada no cliente, um client:load conveniente de cada vez.

A Cascata de SEO em 4 Níveis

Sites WordPress reais acumulam metadados de SEO vindos de múltiplas fontes, muitas vezes conflitantes: um plugin de SEO dedicado, campos nativos do WordPress e padrões do site, nem sempre sincronizados entre si. O README do AstroPress descreve uma “cascata inteligente de metadados” que resolve isso de forma determinística: Yoast SEO → Rank Math → campos nativos do WP → padrões do site, avançando para a próxima fonte apenas quando a atual não tem nada definido, e alimentando o resultado em grafos JSON-LD de Schema.org (BlogPosting, BreadcrumbList, WebSite).

O benefício prático é que migrar entre plugins de SEO, ou rodar um site que começou com campos nativos do WP e depois adicionou o Yoast, não produz metadados silenciosamente ausentes — a cascata sempre resolve para algo, numa ordem de prioridade previsível, em vez de exigir que cada template trate manualmente qual plugin está ativo no momento.

Pipeline de Imagens e Preview de Rascunho

Mídia remota vinda do WordPress é compilada através do pipeline astro:assets do Astro em WebP/AVIF responsivos em tempo de build, com atributos explícitos de largura e altura definidos para que o navegador reserve o espaço de layout antes da imagem carregar — o mecanismo direto para manter o Cumulative Layout Shift em zero, em vez de depender só de lazy-loading para mascarar o problema.

A geração estática tem uma lacuna estrutural: editores não conseguem ver rascunhos não publicados num site que só compila a partir de conteúdo publicado. A resposta do AstroPress é um plugin WordPress complementar, o astropress-connector, que realiza um handshake tokenizado com uma rota de SSR sob demanda no Astro — uma exceção estreita e propositalmente delimitada à regra de estático por padrão, escopada especificamente para preview, em vez de deixada aberta como uma saída genérica para SSR. O editor ganha preview em tempo real de conteúdo não publicado sem que o projeto abra mão do padrão de entregar HTML estático de tempo de publicação para tudo o mais.

Headless Doctor: Diagnosticando o Pipeline Completo

Configurações headless falham de formas difíceis de localizar — é o WordPress, o conector REST, os permalinks, o plugin de preview, ou o build do Astro? O AstroPress vem com uma ferramenta de diagnóstico, executada via npm run doctor (CLI) ou pelo dashboard /doctor (web), que verifica sete categorias de ponta a ponta: configuração de ambiente, conectividade com o WordPress, disponibilidade dos endpoints REST, estrutura de permalinks, estado de instalação do plugin conector, detecção do plugin de SEO e o handshake de preview de rascunho.

É o tipo de ferramenta fácil de pular num tutorial mínimo de WordPress headless e cara de não ter quando algo quebra numa implantação real — um diagnóstico que aponta qual das sete peças falhou evita ter que checar cada uma manualmente sob pressão de tempo.

Orçamentos de Performance Aplicados em CI, Não Só Documentados

O AstroPress declara orçamentos de performance num arquivo budget.json e os aplica via npm run audit:perf no CI — segundo o README, bloqueando inchaço de CSS acima de aproximadamente 25 KB e qualquer JavaScript de cliente acidental em páginas editoriais. A distinção que importa aqui: um orçamento de performance que existe só como afirmação num README não é um orçamento de performance, é uma esperança. Aplicá-lo como um gate de CI significa que um pull request que regride o payload de CSS ou hidrata acidentalmente um componente que deveria ser estático de fato falha o build, em vez de ser publicado e só ser pego (ou não) depois, por quem eventualmente rodar o Lighthouse manualmente.

A suíte de testes do projeto reforça isso com mais de 130 testes via Vitest, segundo a tabela de referência de CLI do README, cobrindo a lógica de normalização de conteúdo e da cascata de SEO, que de outra forma seriam o ponto mais provável de regressões silenciosas.

Como Começar

O quickstart documentado:

git clone https://github.com/hd-rx8/AstroPress-Headless-Starter.git
cd AstroPress-Headless-Starter
npm install
docker compose up -d   # WordPress 6 + MySQL 8.4, com conteúdo de demonstração pré-carregado
npm run doctor         # verifica o pipeline completo antes de iniciar o dev
npm run dev            # http://localhost:4321

O admin do WordPress fica acessível em http://localhost:8080/wp-admin, e o dashboard de diagnóstico em /doctor. A configuração vive no .env, exigindo WORDPRESS_URL, SITE_URL e ASTROPRESS_PREVIEW_SECRET (o segredo compartilhado usado pelo handshake de token do preview de rascunho). A stack é construída sobre o Astro — atualmente Astro 7, conforme o package.json do projeto —, exigindo Node 22.12 ou superior.

Quando o AstroPress Se Encaixa, e Quando Não

Se encaixa bem:

Sites com muito conteúdo (blogs, sites institucionais, documentação) onde editores não técnicos precisam da experiência de edição do Gutenberg, mas o frontend precisa ser rápido e barato de hospedar.
Times migrando um site WordPress existente para um frontend estático sem abandonar o CMS que os editores já conhecem.
Projetos onde orçamentos de performance aplicados em CI são um requisito real, não um “seria bom ter” — a ferramenta existe especificamente para tornar regressões visíveis antes do merge.

Não se encaixa bem:

Conteúdo altamente dinâmico e por usuário (um dashboard logado, dados em tempo real) — é um modelo de renderização diferente do que a geração estática, com conteúdo conhecido em tempo de build, foi projetada para atender.
Times que não querem operar dois sistemas (WordPress mais um pipeline separado de build/deploy para o frontend Astro) em vez de uma única instalação WordPress monolítica — o desacoplamento que compra a performance também adiciona uma peça operacional a mais.
Sites que precisam de atualização de conteúdo instantânea e sem cache a cada publicação, mais rápida do que um ciclo de rebuild permite, sem também configurar regeneração incremental ou sob demanda.

Perguntas Frequentes

O AstroPress exige rodar WordPress e Astro como duas implantações separadas?

Sim — o WordPress funciona puramente como backend editorial e API de conteúdo, enquanto o Astro é o alvo de build/deploy que produz o site estático. O setup com Docker Compose roda os dois localmente para desenvolvimento, mas uma implantação de produção normalmente mantém o WordPress em seu próprio host (ou um provedor de WordPress gerenciado) e implanta o build do Astro separadamente num host estático/edge.

Como o AstroPress lida com conflitos entre os plugins Yoast e Rank Math?

Através da cascata de metadados em 4 níveis: o Yoast SEO é checado primeiro, depois o Rank Math, depois os campos nativos do WordPress, depois os padrões do site, vencendo o primeiro nível que tiver dado definido. Isso evita o erro comum de um template fixar qual plugin ler e perder metadados silenciosamente se o site trocar de plugin de SEO depois.

Editores conseguem fazer preview de rascunhos não publicados num site gerado estaticamente?

Sim, através do plugin WordPress astropress-connector, que realiza um handshake tokenizado com uma rota de SSR sob demanda dedicada no Astro. É a única exceção deliberada ao modelo de renderização estático por padrão do projeto, escopada especificamente para preview de rascunho, não para renderização dinâmica em geral.

O que a afirmação de “0 KB de JavaScript no cliente” realmente significa?

Refere-se especificamente às páginas editoriais — conteúdo renderizado a partir de dados do WordPress é entregue como HTML/CSS estático, sem bundle de JavaScript no cliente para esse conteúdo. Os limites de JavaScript documentados pelo projeto ainda permitem ilhas do Astro de escopo estreito (como uma caixa de busca no cliente) para interatividade genuína; a restrição é que conteúdo conhecido em tempo de build nunca recebe hidratação que não precisa.

Qual a diferença entre isso e simplesmente chamar a REST API do WordPress manualmente a partir de um app Next.js ou Astro?

A diferença é o sistema ao redor: uma camada dedicada de normalização de conteúdo que isola o formato do payload REST do WordPress do resto do código, uma cascata de SEO em 4 níveis em vez de tratamento ad hoc de metadados, um mecanismo de preview de rascunho propositalmente construído, orçamentos de performance aplicados em CI e uma ferramenta de diagnóstico cobrindo o pipeline completo. Um fetch() feito à mão para /wp-json/wp/v2/posts te dá os dados; não te dá, por padrão, nada dessa infraestrutura ao redor.

Eu uso a mesma abordagem static-first, com orçamentos de performance aplicados, neste site — veja Agent-Ready Portfolios (em inglês) para a arquitetura em duas camadas, humana e de agente, e o guia de TTFB no WooCommerce se o site que você está desacoplando do WordPress também roda WooCommerce. O repositório do AstroPress tem o código-fonte completo; se você está avaliando para uma migração real, entre em contato.