Investigación y plantilla de referencia para arquitecturas WordPress Headless + Next.js desplegadas en Vercel. Incluye el starter listo para producción, skill de gestión para Claude Code y documentación completa del enfoque.
WordPress como CMS, Next.js como frontend. El editor usa el panel de siempre; el visitante recibe HTML estático desde un CDN global en milisegundos. La conexión entre ambos mundos: WPGraphQL.
El frontend vive en Vercel (Edge CDN). WordPress puede estar en cualquier hosting — VPS barato, managed WordPress, incluso un sandbox. Lo único que necesita exponer es el endpoint /graphql.
El único requisito en WordPress es tener el plugin WPGraphQL instalado y activo. Nada más cambia para el editor.
Next.js consume la API GraphQL de WordPress, pre-renderiza las páginas y las sirve desde el CDN de Vercel. Sin PHP ejecutándose en cada visita. Sin servidor que escalar.
Títulos, contenido HTML, extractos y fechas se obtienen vía GraphQL con queries precisas — solo los campos necesarios, sin over-fetching.
Cuando el editor publica o edita un post, WordPress llama al endpoint /api/revalidate de Vercel. Next.js purga selectivamente solo las páginas afectadas. El visitante ve el contenido nuevo en la siguiente petición — sin redeploy, sin esperar TTL.
Editor publica → WordPress → webhook POST /api/revalidate
↓
Next.js revalidateTag()
purga solo ese post + home
↓
Siguiente visita regenera
la página al vuelo (gratis)
Resto del tiempo → CDN estático → visitante (~0ms, 0€)
El resultado: con un TTL de 24h y el webhook activo, el 99% del tráfico se sirve desde el CDN sin invocar ninguna función serverless. Coste en Vercel prácticamente cero hasta ~100k visitas/mes.
| Área | Detalle |
|---|---|
| UX del editor | Usa WordPress — sin curva de aprendizaje, sin cambiar flujos |
| Rendimiento | HTML estático desde CDN global, carga en <100ms |
| Seguridad | WordPress nunca expuesto públicamente, wp-admin protegido |
| Coste | Frontend prácticamente gratis en Vercel con ISR + webhook |
| Resiliencia | Fallback estático en /content/*.json — la web aguanta si WP cae |
| Escalabilidad | El CDN aguanta picos de tráfico sin tocar el servidor de WordPress |
| Flexibilidad | Frontend rediseñable sin tocar el CMS |
| Área | Detalle |
|---|---|
| Dos sistemas | WordPress (hosting) + Vercel — dos facturas, dos configuraciones |
| WPGraphQL obligatorio | No compatible con WordPress.com gratuito ni con todas las instalaciones |
| Webhook frágil | Si falla el webhook, el contenido se retrasa hasta que expire el TTL |
| CPTs y ACF | Los custom post types y campos avanzados requieren configuración extra en WPGraphQL |
| Sin tiempo real | No apto para contenido que cambia cada segundo (precios en vivo, scores…) |
| Curva inicial | El primer setup (WPGraphQL + Vercel + variables de entorno) requiere ~30 min |
wordpress-headless/
├── wp-headless-starter-vercel/ # ← Starter listo para usar
│ ├── app/ # Next.js App Router
│ ├── lib/cms/ # Cliente GraphQL + queries
│ ├── scripts/ # Snapshot de contenido
│ └── README.md # Documentación del starter
│
├── skills/
│ └── manager-wp-headless/ # Skill de gestión para Claude Code
│ └── SKILL.md # Menús guiados: posts, deploy, caché, config
│
└── screenshots/ # Capturas del spike
# 1. Entra en el starter
cd wp-headless-starter-vercel
# 2. Instala dependencias
npm install
# 3. Configura tu WordPress
cp .env.example .env.local
# → edita WP_GRAPHQL_URL con tu endpoint GraphQL
# 4. Desarrollo local
npm run dev
# → http://localhost:3000
# 5. Deploy a Vercel
vercel --prod¿No tienes WordPress? Crea uno gratis con WPGraphQL en ~30s en tastewp.com
Ver documentación completa en wp-headless-starter-vercel/README.md.
El directorio skills/manager-wp-headless/ contiene una skill para Claude Code que guía todo el ciclo de vida del proyecto con menús interactivos:
[1] Contenido — Crear, editar y eliminar posts en WordPress
[2] Frontend — Cambiar tema, cabecera, páginas
[3] Deploy — Publicar y actualizar en Vercel
[4] Caché — Revalidar ISR, ajustar TTL, configurar webhook
[5] Config — Setup inicial, cambiar WordPress, variables de entorno
Para usarla: abre Claude Code en este directorio y di "wp headless manager".
- Frontend: Next.js 15 · TypeScript · App Router · ISR
- CMS: WordPress + WPGraphQL
- Deploy: Vercel (Edge CDN)
- Caché: ISR con cache tags + webhook on-demand