Tópico 12 — Headless WordPress e Next.js | Guia Técnico WordPress, Banco de Dados e Next.js

1. Conceito de Headless

O termo “Headless” significa desacoplar o WordPress da camada de exibição. Nesse modelo, o WordPress atua apenas como backend e gerenciador de conteúdo, enquanto o front-end é renderizado por frameworks modernos como Next.js, React ou Nuxt.

Objetivo compreender a comunicação entre WordPress e Next.js via API, estruturando um fluxo de dados seguro e performático.

2. Arquitetura e Fluxo de Comunicação

No modelo Headless, o fluxo de dados segue este caminho:

Fluxo

WordPress (Painel e REST API)
│
├── Endpoint público (https://site.com/wp-json/)
│
└── Next.js (Frontend)
    ├── getStaticProps() → consulta inicial
    ├── getServerSideProps() → atualização em tempo real
    └── API Routes → autenticação, formulários, integrações

Importante O WordPress continua sendo a origem dos dados, enquanto o Next.js cuida da interface e da renderização.

3. REST API e Endpoints

O WordPress oferece endpoints JSON nativos através da REST API, acessíveis em /wp-json/wp/v2/.

Exemplo — retorno de posts

GET https://seudominio.com/wp-json/wp/v2/posts

Os endpoints também permitem filtros e parâmetros, como ?per_page=5 ou ?categories=12.

4. Integração com Next.js

O Next.js consome a REST API do WordPress através de requisições no lado do servidor, garantindo SEO e desempenho.

Exemplo — getStaticProps em Next.js

export async function getStaticProps() {
  const res = await fetch('https://seudominio.com/wp-json/wp/v2/posts?_embed');
  const posts = await res.json();

  return {
    props: { posts },
    revalidate: 60 // atualiza a cada 60 segundos
  }
}

Dica use o parâmetro _embed para carregar imagens destacadas e metadados relacionados em uma única chamada.

5. Autenticação e Segurança

Para criar conteúdo, editar ou acessar dados restritos, use autenticação com tokens JWT (JSON Web Token).

Exemplo — obtenção de token JWT

POST https://seudominio.com/wp-json/jwt-auth/v1/token
{
  "username": "admin",
  "password": "senha_forte"
}

Segurança nunca exponha credenciais no front-end. Use variáveis de ambiente (.env.local) no projeto Next.js.

6. Alternativa: WPGraphQL

Além da REST API, é possível usar o plugin WPGraphQL para consultas otimizadas e mais flexíveis.

Exemplo de query GraphQL

{
  posts(first: 5) {
    nodes {
      title
      slug
      date
      featuredImage {
        node {
          sourceUrl
        }
      }
    }
  }
}

7. Estrutura de Pastas no Projeto Headless

Exemplo de organização de pastas

/
├── pages/
│   ├── index.js
│   ├── posts/[slug].js
│   └── api/
│       └── contato.js
├── components/
│   ├── Header.js
│   ├── Footer.js
│   └── CardPost.js
├── lib/
│   ├── api.js
│   └── config.js
├── public/
│   └── imagens/
└── styles/
    └── globals.css

Boas práticas mantenha lógica de fetch em arquivos separados em lib/api.js para facilitar manutenção e reutilização.

8. Revalidação Incremental

O Next.js permite regenerar páginas estáticas automaticamente quando há atualização de conteúdo no WordPress, sem precisar reimplantar o site.

Exemplo de revalidação via API

export default async function handler(req, res) {
  try {
    await res.revalidate('/');
    return res.json({ revalidated: true });
  } catch (err) {
    return res.status(500).send('Erro ao revalidar');
  }
}

9. Benefícios do Headless

Melhor desempenho e controle total sobre o front-end.
Segurança aprimorada (sem dependência do tema).
Escalabilidade: um backend pode alimentar múltiplas aplicações (web, mobile, PWA).
SEO otimizado via renderização estática do Next.js.

10. Boas Práticas e Considerações

Use cache em endpoints de API para evitar sobrecarga.
Controle versões das APIs e documente endpoints personalizados.
Utilize HTTPS e restrinja métodos HTTP quando possível.
Combine logs do servidor (Nginx/Apache) com monitoramento do Next.js para diagnóstico.

Resultado Uma arquitetura moderna, desacoplada e escalável, integrando o poder do WordPress como CMS com a eficiência do Next.js no front-end.