WordPress headless con Next.js: cuándo sí, cuándo no y cómo migrar

Cada pocos meses aparece en la mesa de un CTO la misma propuesta: «vamos a sacar el frontend de WordPress y montarlo en Next.js». A veces la trae el equipo de desarrollo, harto de pelearse con un theme que lleva ocho años acumulando parches. A veces la trae marketing, que ha visto una demo con transiciones instantáneas. Y a veces la trae una consultora con un presupuesto de seis cifras debajo del brazo.

La pregunta correcta no es si WordPress headless «es mejor». Es si el problema que tienes hoy se resuelve desacoplando el frontend, y si tu equipo puede sostener durante tres años la arquitectura que eso implica. Porque headless no es una optimización puntual: es cambiar un sistema donde una persona edita y publica, por otro con dos aplicaciones, un contrato de datos entre ellas, dos pipelines de despliegue y una lista nueva de cosas que se pueden romper un viernes por la tarde.

En esta guía repasamos qué significa exactamente headless en WordPress, los escenarios donde compensa y las señales de que no, una arquitectura de referencia con Next.js y App Router, y —lo más importante y lo que casi nadie cuenta en las demos— el inventario honesto de lo que se rompe al desacoplar: la previsualización, los bloques de Gutenberg, los formularios, el SEO de Yoast, el multidioma y las redirecciones. Cerramos con el coste real de operación, un plan de migración por fases y un checklist de decisión que puedes llevar directamente a un comité.

1. Qué significa «headless» en WordPress (y qué no)

Headless significa que WordPress deja de renderizar HTML para el visitante. Sigue siendo el sitio donde tu equipo escribe, sube imágenes, organiza taxonomías y gestiona usuarios, pero su salida ya no es una página: es JSON. Otra aplicación —en este caso Next.js— consume ese JSON y construye el HTML que ve el usuario.

Lo que no significa: no es «WordPress más rápido». No es una migración de contenido. Y no elimina WordPress de la ecuación, cosa que conviene dejar muy clara en la reunión donde se aprueba el proyecto. Vas a seguir actualizando el core, vas a seguir auditando plugins y vas a seguir teniendo una base de datos MySQL que crece. Lo único que cambia es quién pinta la página.

1.1 Las tres piezas del montaje

Un WordPress headless en producción tiene siempre estas tres piezas, y cada una es un punto de fallo independiente:

• El backend de contenido. WordPress con su editor, sus roles y su media library. Normalmente deja de ser público: se sirve en un subdominio tipo cms.tudominio.com, detrás de autenticación o de un WAF.
• La capa de API. La REST API nativa (/wp-json/wp/v2/) o WPGraphQL. Es el contrato entre los dos mundos, y es donde se concentran la mayoría de los problemas que nadie previó.
• El frontend. La aplicación Next.js que consulta la API, cachea, renderiza y despliega. Tiene su propio repositorio, su propio CI y su propia factura de hosting.

1.2 REST API o WPGraphQL: la primera decisión estructural

La REST API viene de serie, no añade dependencias y está bien documentada. Su problema es el over-fetching y el número de llamadas: para pintar una portada con destacados, categorías, autores y medios necesitas encadenar varias peticiones, y cada campo extra (ACF, taxonomías personalizadas) exige registrar el campo en REST a mano.

WPGraphQL resuelve eso: pides exactamente los campos que necesitas en una sola consulta, tiene extensiones maduras para ACF, Yoast y Polylang/WPML, y encaja mucho mejor con React Server Components. El precio es un plugin crítico más en el camino, una capa de tipos que hay que mantener sincronizada y un vector de ataque adicional si no limitas la profundidad y la complejidad de las consultas.

Nuestra recomendación práctica: si el sitio es esencialmente un blog corporativo con páginas estáticas, la REST API sobra y te ahorras una dependencia. Si tienes campos personalizados en serio, varios tipos de contenido relacionados entre sí o multidioma, WPGraphQL compensa desde el primer sprint. Lo que no funciona es empezar con REST «para ir rápido» y migrar a GraphQL en el mes cuatro: son dos formas distintas de modelar el fetching y se reescribe casi todo.

2. Cuándo tiene sentido y cuándo es sobreingeniería

Ésta es la sección que justifica o mata el proyecto. Nuestra experiencia auditando plataformas ajenas dice que la proporción está muy desequilibrada: de cada diez propuestas de headless que llegan a nuestra mesa, dos tienen una razón técnica sólida y ocho son un intento de resolver con arquitectura un problema de mantenimiento, de rendimiento mal diagnosticado o de aburrimiento del equipo.

2.1 Los cuatro casos donde sí compensa

Uno: el contenido alimenta varios destinos. Web pública, app móvil, pantallas en tienda, un portal de partners, una intranet. En el momento en que el mismo artículo tiene que salir por tres sitios distintos, WordPress como fuente de datos y clientes independientes es sencillamente la arquitectura correcta.

Dos: el frontend es una aplicación, no un sitio. Configuradores de producto, simuladores, buscadores con faceting complejo, áreas privadas con mucho estado en cliente. Si el 70% del trabajo del frontend es lógica de interfaz y no maquetar contenido, pelearse con PHP y un theme es trabajar contra la herramienta.

Tres: hay varios equipos con ciclos distintos. Un equipo de contenido que publica veinte veces al día y un equipo de producto que despliega dos veces por semana. Separar los repositorios y los despliegues elimina una fuente real de bloqueos organizativos.

Cuatro: necesitas integrar fuentes externas en el render. Cuando la página combina WordPress con un PIM, un ERP o un motor de búsqueda, componer eso en el servidor de Next.js es más limpio que meterlo en un theme a base de wp_remote_get() y transients. Si estás en ese punto, te interesa cómo abordamos las integraciones por API entre ecommerce, ERP y logística.

2.2 Las cinco señales de que no

1. «Es que la web va lenta». En el 90% de los casos que auditamos, la lentitud viene de imágenes sin optimizar, de un hosting compartido, de 43 plugins activos o de un page builder que carga 900 KB de CSS. Eso se arregla en dos semanas sin tocar la arquitectura. Antes de plantear headless, mide: si no sabes cuál es tu INP y el resto de Core Web Vitals, no tienes un diagnóstico, tienes una sensación.
2. Nadie en plantilla sabe React en producción. No «ha hecho un curso»: ha mantenido una app React con SSR durante un año. Si la respuesta es no, estás comprando una dependencia externa permanente.
3. El sitio depende de plugins que pintan front. Formularios, sliders, popups, pasarelas, reservas, membresías. Cada uno de ellos deja de funcionar el día que apagas el theme, y reimplementarlos cuesta más que todo el frontend junto.
4. Marketing edita con un page builder. Si tu equipo monta landings arrastrando bloques en Elementor o Divi, headless les quita esa capacidad de golpe. Es una decisión de negocio, no técnica, y hay que tomarla explícitamente.
5. El presupuesto cubre el proyecto pero no los tres años siguientes. Un headless sin partida de mantenimiento se convierte en dos sistemas desactualizados en lugar de uno.

El paralelismo con otros CMS es útil aquí: las mismas preguntas se aplican casi literalmente a cuándo desacoplar el frontend en Drupal, y los criterios de decisión se parecen más de lo que la guerra de CMS sugiere.

3. Arquitectura de referencia con Next.js

Damos por supuesto App Router y React Server Components, que es lo que tiene sentido montar hoy en un proyecto nuevo. Si vienes de Pages Router, el modelo mental cambia bastante y conviene saberlo antes de presupuestar.

3.1 Fetching en servidor y el contrato de datos

Con App Router, las consultas a WordPress ocurren en el servidor: el navegador nunca ve la URL del CMS ni tokens. Eso resuelve de un plumazo dos problemas clásicos del headless de hace unos años —CORS y exposición del backend— pero introduce uno nuevo: cada render en servidor es una petición a WordPress, así que necesitas caché desde el día uno, no cuando llegue el tráfico.

El patrón que usamos: una capa fina de acceso a datos (lib/wp.ts) con funciones tipadas por tipo de contenido, nunca fetch suelto en los componentes. Todas las respuestas pasan por un normalizador que convierte la forma de WordPress en el modelo del frontend. Parece burocracia hasta el día en que alguien renombra un campo ACF y tienes un único sitio que tocar en lugar de treinta.

3.2 ISR y revalidación bajo demanda: el corazón del montaje

Aquí es donde un headless bien hecho gana de verdad. La estrategia correcta no es generar todo el sitio en cada build —con 4.000 entradas eso son builds de veinte minutos— sino generar bajo demanda y cachear:

• Las rutas se renderizan la primera vez que alguien las pide y se guardan en caché.
• Cada respuesta se etiqueta por tipo y por ID (post-1234, categoria-seguridad).
• Un hook en WordPress (save_post, transition_post_status) llama a un webhook firmado del frontend.
• Ese endpoint invalida solo las etiquetas afectadas: la entrada, su categoría, la portada y el feed.

Resultado: el editor pulsa «Actualizar» y el cambio está online en segundos, sin rebuild completo y sin que un pico de tráfico se traduzca en un pico de carga en el CMS. Si el webhook falla, un TTL de seguridad (una hora, por ejemplo) garantiza que el contenido se refresca igualmente. Ese fallback no es opcional: los webhooks se pierden.

3.3 Imágenes y medios

WordPress genera sus propios tamaños al subir; Next.js tiene su optimizador. Tenerlos compitiendo es el error más habitual y se traduce en doble almacenamiento, doble coste de transformación y un LCP peor que el del theme original.

Elige uno. Si el volumen es alto, lo más limpio es servir los originales desde WordPress —o mejor, desde un bucket S3 con CDN delante— y dejar que el optimizador de Next haga el trabajo de formatos y tamaños. Añade los dominios a la configuración de imágenes, define sizes correctamente y no uses priority en más de un elemento por vista.

4. Lo que se rompe al desacoplar (y cómo se arregla)

Esta es la lista que convierte un proyecto de ocho semanas en uno de dieciséis. No es exhaustiva, pero cubre lo que nos hemos encontrado en todas las migraciones reales.

4.1 La previsualización

El botón «Vista previa» apunta al theme, que ya no existe. Hay que reimplementarlo: filtrar preview_post_link para que apunte a una ruta del frontend, activar el modo borrador de Next.js con un token firmado, y consultar la revisión en lugar del contenido publicado. Son unas horas de trabajo, pero si se deja para el final tienes a todo el equipo editorial publicando a ciegas durante semanas. Impleméntalo en el primer sprint.

4.2 Bloques de Gutenberg y estilos del editor

La API devuelve HTML de bloques con clases (wp-block-*) cuyo CSS vivía en el theme. Tienes tres opciones: importar las hojas de estilo del core de WordPress (rápido, pero arrastras CSS que no usas), parsear los bloques y mapearlos a componentes React (limpio y lo que recomendamos para bloques clave: imagen, galería, cita, tabla, embed) o restringir el editor a un conjunto cerrado de bloques permitidos. La tercera es la que mejor funciona a largo plazo, y conviene negociarla con el equipo de contenido antes de escribir una línea.

4.3 Formularios, comentarios y todo lo que envía datos

Contact Form 7, WPForms y similares dependen de su JavaScript y sus endpoints. En headless hay que reimplementar el formulario en React y postear contra un endpoint —el del plugin si expone REST, o una Route Handler propia— gestionando validación, honeypot, reCAPTCHA y rate limiting por tu cuenta. Esa última parte importa: al exponer un endpoint de envío sin la protección que el plugin traía de serie, te conviertes en destino de spam automatizado en cuestión de días.

4.4 SEO: Yoast, sitemaps y redirecciones

El punto donde más proyectos se pegan un tiro en el pie, porque el daño no se ve hasta tres semanas después de salir a producción.

• Metadatos. Yoast calcula title, description, canonical, Open Graph y JSON-LD en el render de PHP. En headless hay que exponerlos por API (el campo yoast_head_json o la extensión de WPGraphQL) y mapearlos a la Metadata API de Next. Si no lo haces, publicas un sitio entero sin canonical ni datos estructurados.
• Sitemaps. El sitemap de Yoast apunta a URLs del backend. Hay que generarlo en el frontend a partir de la API, o reescribirlo.
• Redirecciones. El plugin Redirection actúa en PHP y deja de ejecutarse. Todas las reglas hay que exportarlas y reimplementarlas en el middleware de Next o en la capa de CDN. Un inventario incompleto aquí es tráfico orgánico perdido, y recuperarlo cuesta meses.
• Indexación del backend. Si cms.tudominio.com queda accesible y sin noindex, acabarás con el sitio duplicado en Google compitiendo contra sí mismo.

4.5 Multidioma

WPML y Polylang resuelven el enrutado por idioma en PHP. En headless tienes que replicar esa lógica en el routing de Next (segmentos [locale]), construir los hreflang a mano y decidir qué pasa con las traducciones parciales. Si tu sitio es multiidioma, suma entre el 30% y el 40% al presupuesto del frontend. Es la partida que más se subestima.

5. Rendimiento: qué ganas de verdad

La expectativa habitual es «vamos a pasar de 45 a 95 en PageSpeed». La realidad es más matizada y conviene ponerla por escrito antes de firmar.

Lo que mejora de forma fiable: el TTFB, porque sirves HTML cacheado desde el edge en lugar de ejecutar PHP y consultar MySQL. Y el peso de la página, porque eliminas de golpe el CSS y el JS que inyectaban los plugins: en sitios con page builder hemos visto caer el peso inicial a menos de la mitad.

Lo que puede empeorar: el INP y el TBT. Next.js hidrata React en el cliente, y un frontend mal construido —con todo marcado como componente de cliente, providers globales y librerías pesadas— entrega un JavaScript mayor que el del theme que sustituiste. Ganar en LCP y perder en INP es un resultado perfectamente posible, y bastante frecuente.

Lo que no cambia: las imágenes mal dimensionadas siguen mal dimensionadas, y los scripts de terceros —tag manager, chat, píxeles, A/B testing— siguen pesando exactamente lo mismo. En muchos sitios reales, esos terceros son la mitad del problema, y headless no los toca.

Dicho de otro modo: headless te da un suelo de rendimiento mucho mejor, pero no te protege de construir mal encima. Antes de asumir que la arquitectura es el cuello de botella, merece la pena una auditoría de código con datos objetivos que te diga dónde se va realmente el tiempo.

6. Seguridad: superficie distinta, no necesariamente menor

El argumento clásico es que headless reduce el riesgo porque el CMS deja de ser público. Es cierto a medias y conviene entender la otra mitad.

Lo que efectivamente mejora: el login de WordPress deja de estar expuesto al mundo, los ataques de fuerza bruta contra wp-login.php dejan de importar y una vulnerabilidad en un plugin de frontend ya no afecta al visitante, porque ese código nunca se ejecuta para él.

Lo que empeora o aparece nuevo: la API REST o GraphQL sí es pública, y con ella una superficie perfectamente explotable si no la acotas. Enumeración de usuarios por /wp-json/wp/v2/users, consultas GraphQL anidadas que tumban el servidor, endpoints de formularios sin rate limiting, tokens de preview con demasiado alcance, variables de entorno filtradas en el bundle del cliente. Y, sobre todo, un segundo sistema que actualizar: ahora tienes que estar al día de WordPress y del ecosistema npm del frontend, con su rotación de dependencias.

Las medidas mínimas: deshabilitar el endpoint de usuarios, aplicar límites de profundidad y complejidad en GraphQL, exigir cabecera de aplicación o IP allowlist entre el frontend y el CMS, firmar los webhooks de revalidación y auditar dependencias en cada despliegue. Los fundamentos de siempre siguen aplicando: merece la pena repasar la guía de seguridad de WordPress para empresas, porque el backend sigue siendo WordPress con todo lo que eso implica.

7. Hosting, despliegue y coste real de operación

La conversación de presupuesto se queda casi siempre en el desarrollo inicial y se olvida de lo que viene después. Estos son los conceptos que hay que poner en la hoja de cálculo:

• Hosting del CMS. No desaparece. Sigue habiendo PHP, MySQL, backups y actualizaciones, aunque con mucho menos tráfico.
• Hosting del frontend. Vercel, Netlify, Cloudflare o un contenedor propio. El plan gratuito cubre el desarrollo; producción con tráfico real, funciones en el edge y ancho de banda es una factura mensual nueva y variable.
• CDN y optimización de imágenes. Si el volumen es alto, factura aparte.
• Dos pipelines de CI/CD y dos entornos de staging que mantener sincronizados.
• Observabilidad. Con dos sistemas, «la web va lenta» requiere trazas para saber si el problema está en la API, en el render o en la caché. Sin esto, cada incidencia es una investigación a ciegas.
• Actualizaciones de framework. Next.js publica versiones mayores con frecuencia y las migraciones no siempre son triviales. Presupuesta una cada año.

Como regla orientativa de lo que vemos en proyectos reales: el coste de mantenimiento anual de un headless bien montado está entre 1,5 y 2 veces el del mismo sitio monolítico. No es prohibitivo, pero tiene que estar en el plan desde el principio, no aparecer en el mes siete. Si no vas a dedicar ese presupuesto, la decisión honesta es quedarse en monolito y hacerlo bien: un WordPress moderno y bien mantenido —y más con los cambios de arquitectura que trae la actualización a WordPress 7— rinde perfectamente para la mayoría de sitios corporativos.

8. Migración por fases: un plan de 90 días

Migrar de golpe es la vía rápida para pasar un trimestre apagando fuegos. El enfoque que funciona es incremental, con el sitio antiguo sirviendo tráfico hasta el último día.

Días 1-15: inventario y decisión

Listado completo de plugins y de qué hace cada uno en el front. Inventario de tipos de contenido y campos personalizados. Exportación de todas las reglas de redirección. Medición de referencia de Core Web Vitals y de tráfico orgánico por plantilla. Decisión REST o GraphQL. Si al terminar esta fase el inventario revela seis plugins críticos de frontend, ya tienes la respuesta y te has ahorrado el proyecto entero.

Días 16-40: cimientos

Proyecto Next.js con App Router, capa de datos tipada, plantillas de entrada y página, previsualización funcionando, revalidación por webhook firmado y metadatos de Yoast mapeados. Al final de esta fase, el equipo editorial tiene que poder escribir un borrador y verlo. Sin eso, no se avanza.

Días 41-65: contenido y paridad

Archivos, taxonomías, buscador, paginación, bloques mapeados a componentes, formularios reimplementados con protección antispam, sitemap y robots.txt. Aquí es donde aparece el 80% de los casos límite que nadie había listado.

Días 66-80: rutas en paralelo

Un proxy inverso enruta por patrón: /blog/* al frontend nuevo, el resto al theme antiguo. Se valida con tráfico real y se revierte en segundos si algo falla. Esta fase es la que convierte un lanzamiento arriesgado en uno aburrido, que es exactamente lo que quieres.

Días 81-90: corte y vigilancia

Traslado del resto de rutas, noindex y bloqueo del backend, redirecciones activas en el middleware. Después: dos semanas mirando Search Console a diario —cobertura, errores 404, páginas excluidas— y comparando contra la medición de referencia. Los problemas de SEO en una migración no aparecen el día uno; aparecen entre el día diez y el treinta.

9. Alternativas que deberías descartar antes

Antes de aprobar un headless, hay cuatro caminos más baratos que resuelven la mayoría de los síntomas que llevan a plantearlo:

1. Limpiar y optimizar el monolito. Auditar plugins, eliminar los que no aportan, caché de página en servidor, CDN, imágenes en AVIF/WebP, critical CSS. Dos o tres semanas, coste bajo, y suele cerrar la conversación sobre rendimiento.
2. Theme a medida en lugar de page builder. Buena parte de la lentitud que se atribuye a WordPress es del builder, no de WordPress. Un theme propio bien construido rinde a la altura de casi cualquier frontend moderno.
3. Headless parcial. Dejar el sitio como está y desacoplar solo la pieza que lo necesita: el configurador, el buscador, el área de cliente. Te llevas la ventaja donde importa sin duplicar el sistema entero.
4. Otro CMS. Si vas a reescribir el frontend de todas formas, plantéate si WordPress sigue siendo el backend adecuado o si un CMS headless nativo encaja mejor. La comparativa de Next.js, Nuxt y Astro es un buen punto de partida, porque la elección de framework condiciona mucho el resto.

10. Checklist de decisión

Para llevar a comité. Si respondes «no» a cualquiera de las cinco primeras, no es el momento:

1. ¿Hay al menos dos consumidores reales del contenido, o el frontend es una aplicación de verdad?
2. ¿Tenemos en plantilla quien mantenga una app React con SSR durante tres años?
3. ¿El inventario de plugins de frontend es corto y reimplementable?
4. ¿Marketing acepta perder el page builder y trabajar con bloques acotados?
5. ¿Está presupuestado el mantenimiento anual, no solo el proyecto?
6. ¿Tenemos medición de referencia de rendimiento y tráfico orgánico para comparar después?
7. ¿Está inventariado y exportado el 100% de las redirecciones?
8. ¿Hay un plan de convivencia y un camino de vuelta si el corte sale mal?

Conclusión

WordPress headless con Next.js es una arquitectura sólida y madura cuando responde a un problema real: contenido que alimenta varios destinos, un frontend que es genuinamente una aplicación, equipos con ciclos distintos o integraciones que no caben en un theme. En esos casos, el resultado es un sitio más rápido, más seguro de cara al público y mucho más agradable de evolucionar.

Cuando se adopta para resolver lentitud mal diagnosticada, deuda técnica acumulada o simple fatiga con el stack actual, el resultado es predecible: dos sistemas en lugar de uno, el doble de superficie de mantenimiento y los mismos problemas de fondo, ahora repartidos entre dos repositorios. La diferencia entre un caso y otro casi nunca está en la tecnología: está en haber hecho el inventario antes de decidir.

Nuestra recomendación práctica: mide primero, inventaría después y decide al final. Y si decides que sí, migra por fases con el sitio antiguo sirviendo tráfico hasta el último día. Un lanzamiento aburrido es el objetivo, no una señal de falta de ambición.

Preguntas frecuentes

¿WordPress headless mejora el SEO?

No por sí mismo. Mejora el TTFB y el peso de la página, que son factores de experiencia, pero el SEO técnico hay que reconstruirlo entero: metadatos de Yoast, canonical, datos estructurados, sitemap y redirecciones. Una migración headless mal ejecutada es una de las formas más rápidas de perder tráfico orgánico.

¿Puedo seguir usando Elementor o Divi?

No de forma práctica. Ambos generan HTML y CSS propios en el render de PHP. Existen soluciones parciales que exportan ese HTML, pero arrastras el CSS del builder y pierdes casi toda la ventaja. Si el equipo depende del builder, headless no es tu camino.

¿Cuánto cuesta un proyecto headless?

Depende del inventario, pero como orden de magnitud: un blog corporativo sencillo ronda las 8-10 semanas de desarrollo; un sitio con campos personalizados, multidioma y formularios complejos se va a 16-20. El multidioma es la partida que más se subestima, y el mantenimiento anual posterior está entre 1,5 y 2 veces el del mismo sitio monolítico.

¿Y WooCommerce? ¿Puedo hacer headless mi tienda?

Se puede, pero el listón sube mucho: carrito, checkout, pasarelas, impuestos, envíos y cuentas de cliente hay que reconstruirlos o consumirlos por Store API, y cualquier error ahí es dinero. Antes de plantearlo, conviene revisar si WooCommerce sigue siendo la opción adecuada para tu caso, y tratar el proyecto como un desarrollo de ecommerce completo, no como un cambio de frontend.

¿Qué pasa con las actualizaciones de WordPress?

Siguen siendo tu responsabilidad. El core, los plugins que queden y PHP hay que mantenerlos al día igual que antes. Headless no reduce el mantenimiento del backend: le suma el del frontend.