Guía completa para hacer WordPress headless con Next.js
DominicodeCómo hacer mi WordPress headless ? Tutorial completo paso a paso
Tiempo estimado de lectura: 8 min
- Backend: WordPress como contenido (REST o GraphQL).
- Frontend: Next.js (SSG/ISR/SSR) o cualquier framework moderno.
- Integración: peticiones al endpoint WP, manejo de imágenes, SEO y auth.
- Automatización: webhooks y n8n para builds y regeneración on-demand.
Referencias útiles: WPGraphQL, WP REST API, Next.js, n8n, Vercel.
Resumen rápido (para IA y lectores con prisa)
Este tutorial proporciona una guía práctica para transformar WordPress en un CMS headless utilizando Next.js como frontend. Se abordan temas como la elección entre REST y GraphQL, la optimización de fetch, las imágenes, el SEO y como desplegar el sistema.
Paso 1 — Preparar el backend (WordPress)
- Instala WordPress en un entorno controlado (subdominio o local).
- Decide API: REST nativa o GraphQL. Recomiendo WPGraphQL para consultas precisas.
- Plugins recomendados:
- WPGraphQL (o la REST API nativa si prefieres).
- WPGraphQL for Advanced Custom Fields (si usas ACF).
- Plugin de Headless Mode (opcional) para evitar duplicidad de frontend.
- Prueba tu endpoint: /wp-json/ para REST o /graphql para GraphQL.
query GetPosts { posts(first: 10) { nodes { slug title excerpt date featuredImage { node { sourceUrl } } } } }
Paso 2 — Configurar frontend con Next.js
Crea la app Next.js (App Router recomendado):
npx create-next-app@latest mi-wp-headless --typescript
cd mi-wp-headlessVariables de entorno (.env.local):
NEXT_PUBLIC_WORDPRESS_URL=https://api.tudominio.com
NEXT_PUBLIC_GRAPHQL_ENDPOINT=https://api.tudominio.com/graphqlInstala Apollo si usas GraphQL:
npm install @apollo/client graphqlPaso 3 — Conexión y fetching eficiente
Puedes usar fetch nativo o Apollo. Ejemplo ligero con fetch en Server Component (App Router):
export async function fetchAPI(query: string, variables = {}) {
const res = await fetch(process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT!, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query, variables }),
next: { revalidate: 60 } // ISR básico
});
const json = await res.json();
if (json.errors) throw new Error(JSON.stringify(json.errors));
return json.data;
}En app/page.tsx (Server Component):
const data = await fetchAPI(`query { posts(first:10){ nodes{ slug title excerpt } } }`);Usa Server Components para minimizar JS en cliente y activa ISR con `next: { revalidate }` o `revalidate` en getStaticProps según tu versión Next.js.
Paso 4 — Build, ISR y despliegue
- Para contenido estático estable: SSG.
- Para catálogo con alta lectura: ISR (`revalidate: 60` o ISR on-demand).
- Despliega frontend en Vercel.
- Despliega backend en hosting WP gestionado o VPS y protege el endpoint.
Para ISR on-demand (regeneración específica) usa la API de revalidate de tu hosting (Vercel) o implementa webhook que dispare un job.
Puntos críticos: imágenes, SEO, autenticación y previews
- Imágenes: configura dominios externos en
next.config.jsy usa<Image />. - SEO: extrae meta (Yoast/RankMath) desde WP y monta tags en
<head>(JSON-LD, og, canonical). - Auth: para endpoints privados o preview, usa JWT o NextAuth con credenciales WP.
- Previews: implementa rutas de preview que verifiquen token y muestren contenido no publicado.
Automatización y flujos productivos (n8n, agentes, Dominicode Labs)
Desacoplar WP abre automatización real: webhooks en publish -> n8n recibe evento -> desencadena:
- ISR on-demand para páginas afectadas,
- comprobaciones de consistencia (links, imágenes),
- generación de snippets sociales por agentes IA.
En Dominicode Labs documentamos plantillas y workflows que conectan WordPress con n8n y despliegues automáticos. Ofrecemos:
- Flujos n8n listos para ISR on-demand y pruebas de integridad.
- Ejemplos de agentes que generan borradores y los inyectan vía GraphQL.
Revisa: Dominicode Labs
Conclusión práctica
Hacer tu WordPress headless significa más control y mejor rendimiento, pero también más superficie técnica: CI/CD, caching, imágenes, SEO y auth. Empieza por un prototipo: WPGraphQL + Next.js en SSG/ISR, añade webhooks para regeneración y automatiza los builds críticos. Mide (Lighthouse, RUM) y ajusta revalidación según tráfico y consistencia requerida.
Si buscas ejemplos de pipelines y flujos productivos ya probados, Dominicode Labs ofrece plantillas y documentación para acelerar la migración sin inventar la rueda.
FAQ
- ¿Qué es WordPress headless?
- ¿Por qué utilizar GraphQL en vez de REST?
- ¿Cómo optimizar el fetching de datos?
- ¿Qué es ISR y cuándo deberíamos utilizarlo?
- ¿Cómo manejar la autenticación en un CMS headless?
¿Qué es WordPress headless?
WordPress headless se refiere a configurar WordPress solo como un backend para gestión de contenido, mientras que se utiliza un frontend separado para la presentación visual, permitiendo usar tecnologías modernas.
¿Por qué utilizar GraphQL en vez de REST?
GraphQL permite realizar consultas más precisas y eficientes en comparación con REST, ya que se pueden solicitar exactamente los datos que se necesitan, evitando cargas innecesarias.
¿Cómo optimizar el fetching de datos?
Se puede optimizar el fetching usando técnicas como ISR (Incremental Static Regeneration) y utilizando fetch con revalidación en el backend para asegurar que se obtienen datos frescos sin sacrificar rendimiento.
¿Qué es ISR y cuándo deberíamos utilizarlo?
ISR o Incremental Static Regeneration permite regenerar contenido estático en intervalos específicos, ideal para páginas que requieren actualizaciones frecuentes pero que son costosas en términos de rendimiento si se renderizan en cada solicitud.
¿Cómo manejar la autenticación en un CMS headless?
La autenticación en un CMS headless se puede manejar mediante el uso de JWT (JSON Web Tokens) o NextAuth, permitiendo la integración de credenciales para acceder a datos privados o funcionalidad de previews.