Headless Drupal con JSON:API y frameworks JavaScript: cómo desacoplar tu frontend para experiencias web modernas

El modelo headless ha dejado de ser un experimento para convertirse en la arquitectura que muchos equipos eligen cuando rendimiento y flexibilidad están arriba del todo en la lista de prioridades. Según datos de Jamstack Community Survey 2025, el 67% de los desarrolladores frontend trabajan con algún tipo de arquitectura desacoplada, y Drupal se ha ganado un sitio como uno de los CMS backend más robustos para este enfoque.

Drupal incluye JSON:API en su core desde la versión 8.7. Eso significa que cualquier instalación expone automáticamente todos sus contenidos como endpoints REST estandarizados. El contenido se gestiona en Drupal, pero la presentación puede correr en React, Vue, Svelte o cualquier framework que consuma APIs. Es como tener la cocina y el comedor en edificios separados: cada uno se especializa en lo suyo, y la comida llega por un pasaplatos bien diseñado.

Esta guía desglosa la arquitectura headless con Drupal, compara las opciones técnicas (JSON:API vs GraphQL, Next.js vs Nuxt vs Gatsby), aborda los retos reales (SEO, preview, autenticación) y ayuda a decidir cuándo este enfoque aporta valor y cuándo añade complejidad que no necesitas.

Qué significa realmente headless y por qué Drupal encaja en este modelo

En un CMS tradicional, el mismo sistema gestiona el contenido y genera el HTML. Todo en un solo paquete. En un CMS headless, Drupal se ocupa exclusivamente de la gestión de contenidos --creación, edición, permisos, flujos de aprobación, media-- y los expone a través de APIs. El frontend es una aplicación independiente que consume esas APIs y decide cómo presentar la información.

Existe un modelo intermedio, el "progressively decoupled", donde Drupal genera el HTML base pero partes específicas de la interfaz (un buscador interactivo, un configurador de producto) se renderizan con JavaScript que consume la API. Este modelo permite ir desacoplando de forma gradual, probando la receta antes de servir el menú completo.

Por qué Drupal funciona especialmente bien como backend headless:

• JSON:API en el core, sin módulos adicionales. Cualquier tipo de contenido, taxonomía o entidad es accesible via API desde su creación.
• Sistema de permisos granular que se aplica tanto a la interfaz web como a las respuestas de la API.
• Modelado de contenidos flexible con una interfaz administrativa madura para editores.
• Ecosistema de módulos para gestión editorial (workflows, revisiones, media library) que no existe en headless CMS puros como Contentful o Strapi.
• Multiidioma nativo. JSON:API expone cada traducción con el header Accept-Language.

La ventaja frente a headless CMS nativos (Contentful, Sanity, Strapi) es que Drupal ofrece capacidades enterprise --permisos complejos, flujos de aprobación, versionado, multiidioma-- que estos sistemas más jóvenes todavía están construyendo. Contentful, por ejemplo, cobra por usuario editor y por volumen de contenido; Drupal no tiene límites artificiales en ninguno de esos ejes.

JSON:API vs GraphQL en Drupal: cuál elegir y por qué

Drupal ofrece dos mecanismos para exponer contenido como API: JSON:API (en el core) y GraphQL (módulo contribuido). La elección entre uno y otro se parece a decidir entre un menú del día completo y pedir a la carta: ambos te alimentan, pero cada uno encaja mejor en un contexto.

JSON:API sigue la especificación jsonapi.org. Endpoints predecibles por tipo de entidad (/jsonapi/node/article), filtrado potente, inclusión de relaciones en una sola petición con el parámetro include, paginación estandarizada y soporte CRUD completo.

GraphQL permite al cliente definir exactamente qué campos necesita en cada consulta, evitando over-fetching y under-fetching:

query {
  nodeArticles(first: 10, filter: {status: true}) {
    nodes {
      title
      body { processed }
      fieldImage { url, alt }
    }
  }
}

JSON:API es la opción correcta para el 80% de los proyectos. Así de claro. Es parte del core (garantía de mantenimiento), funciona sin configuración adicional, y las librerías del ecosistema (next-drupal) están optimizadas para él. El rendimiento es predecible: cada petición devuelve los datos de forma consistente y el sistema de cache tags de Drupal permite invalidación granular de las respuestas.

GraphQL se justifica cuando el frontend necesita combinar datos de múltiples tipos de contenido en consultas complejas, el equipo ya domina GraphQL, o se necesita optimizar al máximo el volumen de datos transferidos (aplicaciones móviles con ancho de banda limitado). El módulo GraphQL para Drupal necesita configuración adicional, los esquemas deben definirse explícitamente, y la depuración es menos directa que con JSON:API.

Frameworks frontend: React/Next.js, Vue/Nuxt y Gatsby

Next.js (React). La opción dominante, y con razón. El paquete next-drupal proporciona funciones para consumir JSON:API, gestionar rutas dinámicas y manejar previsualizaciones. Next.js ofrece tres modos de renderizado que puedes combinar según la receta que necesite cada página:

• SSG (Static Site Generation): Páginas generadas en build, servidas como archivos estáticos. Rendimiento máximo, pero contenido estático hasta el siguiente build.
• SSR (Server-Side Rendering): Páginas generadas en cada petición. Contenido siempre actualizado, mayor carga en servidor.
• ISR (Incremental Static Regeneration): Páginas estáticas que se revalidan periódicamente o bajo demanda. El punto intermedio que casi siempre buscas.

La combinación Drupal + Next.js + ISR con revalidación bajo demanda (webhook desde Drupal cuando el contenido cambia) ofrece el mejor equilibrio entre rendimiento y frescura. He montado esta combinación en varios proyectos y cada vez me convence más.

Nuxt (Vue). Capacidades comparables a Next.js para SSR, SSG e ISR. No existe un paquete equivalente a next-drupal con el mismo nivel de integración, pero consumir JSON:API desde Nuxt es directo usando useFetch o librerías como drupal-jsonapi-params para construir las consultas. Si tu equipo tiene experiencia en Vue o el proyecto forma parte de un ecosistema Vue existente, no le des más vueltas. A nivel técnico las diferencias con Next.js son menores; la brecha principal está en el tamaño del ecosistema y la cantidad de ejemplos documentados para la integración con Drupal.

Gatsby. El pionero del Jamstack con plugin oficial para Drupal (gatsby-source-drupal). Pero ha perdido fuelle: ecosistema estancado tras la adquisición por Netlify, tiempos de build que escalan mal en sitios grandes (más de 10.000 páginas), y modelo puramente estático que se queda corto. Para proyectos nuevos en 2026, Next.js es la recomendación por defecto.

Autenticación y autorización en arquitectura headless

En una arquitectura desacoplada, frontend y backend son aplicaciones separadas, posiblemente en dominios distintos. La gestión de sesiones necesita un enfoque específico y algo de cariño en la implementación.

Simple OAuth (OAuth 2.0). La opción recomendada. El usuario introduce credenciales en el frontend, que las envía al endpoint /oauth/token de Drupal. Drupal devuelve un access token (vida corta, 300s por defecto) y un refresh token (vida larga). El frontend incluye el token en el header Authorization: Bearer {token} de cada petición.

JWT (JSON Web Tokens). Para autenticación stateless. Los tokens firmados contienen la información del usuario; el backend no necesita consultar la base de datos para validarlos. Útil cuando hay múltiples microservicios en la mesa.

Cookies de sesión. Si frontend y Drupal están en el mismo dominio, la autenticación por cookie funciona directamente con credentials: 'include'. Más sencillo pero limita las opciones de despliegue.

Un aspecto que muchos equipos descubren demasiado tarde: JSON:API aplica los permisos del usuario autenticado (o del usuario anónimo si no hay autenticación) a cada respuesta. Si un tipo de contenido no es accesible para usuarios anónimos, la API devuelve 403. Si un campo tiene restricciones de acceso, simplemente no aparece en la respuesta. El sistema de permisos de Drupal protege la API de forma nativa, pero el frontend debe manejar correctamente los estados de error y los casos de acceso denegado. Si no, acabas mostrando pantallas en blanco que dejan al usuario preguntándose si algo se ha roto.

Preview editorial y experiencia del editor en headless

El mayor sacrificio del headless es la experiencia editorial. Seamos honestos con esto. En Drupal monolítico, el editor previsualiza exactamente cómo se verá la página. En headless, la previsualización requiere coordinación entre backend y frontend, y esa coordinación no viene gratis.

Next.js Draft Mode. El editor hace clic en "Previsualizar" en Drupal, que redirige al frontend con un token. Next.js activa el draft mode y hace peticiones directas a la API incluyendo contenido no publicado. El paquete next-drupal automatiza gran parte de esta integración, pero la configuración exige atención a los detalles: tokens seguros, CORS correcto, desactivación limpia del draft mode.

Iframe preview. Drupal muestra un iframe que carga la URL del frontend con un parámetro de previsualización. Menos elegante pero funciona con cualquier framework. A veces la solución menos bonita es la que mejor se adapta.

Storybook. Complementa la experiencia editorial mostrando cómo se renderizan los componentes con datos de ejemplo, aunque no reemplaza la previsualización de contenido real.

SEO en arquitectura headless: SSR, SSG y los matices que importan

Si el frontend es una SPA que renderiza todo en el navegador, los bots de búsqueda reciben una página vacía con un <div id="root"></div>. Googlebot ejecuta JavaScript con retrasos; otros motores y redes sociales no lo ejecutan en absoluto. Receta segura para el desastre SEO.

SSR genera el HTML completo en el servidor. Los bots reciben contenido indexable con meta tags correctas. SSG produce archivos HTML estáticos servidos desde CDN con tiempos de carga inferiores a 100ms. ISR combina ambos: páginas estáticas que se revalidan bajo demanda.

Drupal puede disparar la revalidación de Next.js mediante un webhook cuando el contenido cambia:

// pages/api/revalidate.js
export default async function handler(req, res) {
  const path = req.body?.path;
  if (path) {
    await res.revalidate(path);
    return res.json({ revalidated: true });
  }
}

Para meta tags y datos estructurados, Drupal sigue siendo la fuente de datos (título SEO, meta descripción, imagen OG), pero el frontend debe leerlos de la API y renderizarlos en el <head>. Para el sitemap, el módulo Simple Sitemap de Drupal genera el XML configurado con el dominio del frontend como base URL.

Rendimiento, cache y CDN en arquitectura desacoplada

Una arquitectura headless mal configurada puede ser más lenta que un Drupal monolítico con Varnish. Suena contradictorio, pero pasa. La cache opera en tres niveles y hay que cuidar cada uno:

1. Backend (Drupal). Internal Page Cache y Dynamic Page Cache para respuestas de la API. JSON:API soporta cache tags para invalidación granular.
2. Frontend. En Next.js con ISR, las páginas se almacenan y sirven sin recalcularlas. La revalidación bajo demanda permite invalidar páginas específicas cuando el contenido cambia.
3. CDN. Cloudflare, Fastly o CloudFront sirven páginas desde edge locations con headers Cache-Control apropiados.

Para optimizar peticiones a la API:

• Usa el parámetro include de JSON:API para obtener entidades relacionadas (imagen, autor, categoría) en una sola llamada en lugar de hacer peticiones separadas. Cada petición HTTP tiene un coste; reduce el número de viajes.
• Implementa un patrón BFF (Backend for Frontend) con funciones serverless que agregan múltiples llamadas a la API en una sola respuesta optimizada para la vista que el frontend necesita renderizar.
• Cachea respuestas en el frontend con SWR o React Query, que proporcionan stale-while-revalidate: muestran datos de cache inmediatamente y actualizan en segundo plano.

Hosting y despliegue: Vercel, Netlify y opciones self-hosted

La arquitectura headless requiere alojar dos sistemas independientes. Dos cocinas separadas, cada una con sus propias necesidades de infraestructura.

Backend Drupal: Plataformas especializadas (Pantheon, Platform.sh, Acquia) ofrecen hosting optimizado con staging y despliegue automatizado, desde 50-100 EUR/mes. Un VPS en AWS, DigitalOcean o Hetzner con Nginx, PHP-FPM y MariaDB ofrece control total a menor coste. Docker Compose para desarrollo, Kubernetes si la organización ya tiene infraestructura de contenedores.

Frontend: Vercel ofrece la mejor integración con Next.js: despliegue automático desde Git, preview deployments, edge functions. Netlify es comparable con excelente soporte para Nuxt. Self-hosted con Node.js + PM2 + Nginx para control total, perdiendo la conveniencia de los deploys automáticos.

Para la mayoría de proyectos, Platform.sh para Drupal + Vercel para Next.js ofrece el menor esfuerzo operacional con rendimiento de producción. Esa es la combinación con la que arranco por defecto y luego ajusto según las necesidades concretas.

Cuando NO ir headless: las limitaciones reales del desacoplamiento

Sitios con edición intensiva en página. Si los editores necesitan construir páginas arrastrando componentes y previsualizando en tiempo real, Layout Builder de Drupal ofrece una experiencia que es muy difícil de replicar en headless. Y "muy difícil" aquí significa "caro y lento de implementar".

Equipos sin experiencia frontend especializada. Un proyecto headless requiere dominar Drupal y el framework frontend. La curva de aprendizaje puede alargar el proyecto un 40-60%. No subestimes esto.

Presupuestos ajustados para sitios informativos. Un sitio corporativo estándar se implementa en Drupal monolítico en 4-6 semanas. En headless requiere 8-12 semanas por la duplicación de esfuerzo y la complejidad de integración. Si el presupuesto no da para eso, mejor un monolítico bien hecho.

Funcionalidades que dependen del servidor. Webform, Drupal Commerce, personalización basada en perfil: tienen implementaciones maduras en Drupal monolítico que requieren desarrollo adicional significativo en headless.

La pregunta correcta no es "headless o monolítico" sino "qué partes de mi proyecto se benefician del desacoplamiento". El modelo progresivamente desacoplado --donde Drupal genera la estructura base y JavaScript enriquece secciones específicas-- ofrece un camino intermedio que reduce el riesgo. Permite adoptar headless de forma incremental, sin la apuesta de todo o nada que implica un desacoplamiento completo desde el primer día.

Arquitectura de referencia para un proyecto Drupal headless en producción

Esta es la arquitectura que utilizamos en proyectos de tamaño medio (50-200 páginas, 5-10 tipos de contenido, 50.000-500.000 visitas mensuales). Es la receta base que luego condimentamos según el proyecto:

Backend: Drupal 10/11 con JSON:API + Simple OAuth + Metatag + Pathauto + Simple Sitemap + Content Moderation. Nginx + PHP 8.3 + MariaDB 10.11 + Redis.

Frontend: Next.js 14+ con App Router + next-drupal + Tailwind CSS en Vercel con ISR y revalidación bajo demanda.

Integración: Webhook de Drupal a la API de revalidación de Next.js con el path de la página afectada. Draft mode para previsualización de borradores desde Drupal.

CDN: Cloudflare con cache de página completa y bypass para draft mode y rutas autenticadas.

CI/CD: GitHub Actions para despliegue automático. Tests e2e con Cypress para validar que el frontend renderiza correctamente los contenidos de la API.

Si estás evaluando la arquitectura headless para un proyecto con Drupal y necesitas orientación sobre qué enfoque se adapta mejor a tus requisitos, nuestro equipo técnico puede ayudarte a tomar esa decisión con criterio; contacta con nosotros en Tangram Consulting para una consulta inicial.

Elegir arquitectura con los pies en el suelo

La adopción de headless Drupal debe responder a necesidades concretas, no a lo que esté de moda en conferencias.

Rendimiento medible. Si el sitio tiene un TTFB superior a 800ms y un LCP por encima de 2,5 segundos, headless con SSG/ISR puede mejorar estos valores drásticamente. Si el rendimiento ya es aceptable con Drupal + Varnish, la ganancia marginal puede no justificar la inversión. Mide primero, decide después.

Complejidad del frontend. Si la interfaz requiere interacciones ricas (filtros dinámicos, visualizaciones de datos, animaciones complejas), un framework JavaScript es la herramienta correcta y headless es el camino natural. Si las páginas son mayoritariamente estáticas, Drupal con Twig es más eficiente. No montes una cocina industrial para hacer tostadas.

Multicanalidad. Si el mismo contenido se consume desde web, app móvil, kiosco y asistente de voz, la API evita duplicar la gestión de contenidos.

Capacidad del equipo. Un equipo con experiencia sólida en Drupal pero sin conocimientos de React va a pasar un mal rato con headless. Invierte en formación o complementa el equipo antes de comprometerte con la arquitectura.

JSON:API proporciona una base robusta y estandarizada para exponer contenidos, y frameworks como Next.js ofrecen herramientas maduras para consumirlos con rendimiento de primer nivel. Pero cada capa de abstracción añade complejidad operacional --dos repositorios, dos pipelines de despliegue, dos stacks tecnológicos que mantener-- y la arquitectura correcta es la que resuelve los problemas reales del proyecto con la menor complejidad posible. Un Drupal monolítico bien optimizado sigue siendo una solución excelente para muchos casos de uso. Headless brilla cuando los requisitos de rendimiento, multicanalidad o experiencia de usuario lo exigen de forma objetiva. El truco está en saber cuándo cada ingrediente aporta al plato y cuándo solo lo complica.