Headless Drupal con API decoupled: cómo construir un frontend moderno con React o Vue

Llevo años pisando plantas y persiguiendo trazas, lotes y no conformidades. Miro una arquitectura web igual que una línea de envasado: dónde está el cuello de botella y quién se come el marrón cuando el cliente reclama. Drupal funciona como CMS robusto. Lo que ha cambiado es la fábrica de alrededor: el contenido viaja a la app del operario, al panel del cliente, al portal de calidad y al ERP. Servirlo desde un monolito es como pretender que una sola máquina haga inyección, mecanizado y embalaje. Ahí aparece headless Drupal con API decoupled y frontend en React o Vue.

Qué significa exactamente "headless Drupal" y por qué importa

En una instalación tradicional, Drupal hace de máquina única: almacena, aplica lógica y renderiza con Twig. En modo headless conserva las dos primeras responsabilidades y manda la presentación a un frontend que consume datos por API (REST o JSON:API). Visto desde planta, Drupal queda como ERP de contenido y el frontend hace de SCADA.

"Decoupled" se usa como sinónimo, con matiz: fully decoupled elimina del todo la capa de presentación de Drupal; progressively decoupled deja Drupal renderizando y le pega componentes de React o Vue solo donde lo pide la página. Como meter un MES encima de un ERP viejo: no rehaces la planta, refuerzas los puntos críticos.

Según la encuesta State of Drupal 2024 publicada por Drupal Association, el 47 % de los sitios nuevos construidos con Drupal 10 ya utilizan algún grado de arquitectura decoupled, frente al 31 % registrado en 2022. El ecosistema se mueve hacia capas separadas, como llevamos años haciendo en automoción al separar control de proceso y supervisión.

Cuándo adoptar esta arquitectura (y cuándo no)

No todo proyecto pide headless. Un sitio corporativo con quince páginas estáticas, un blog y un formulario funciona con Drupal tradicional. Meterle un frontend desacoplado es como instalar un MES para tres referencias.

Headless Drupal con API decoupled y frontend en React o Vue tiene sentido cuando se cumple al menos una condición:

• Multicanalidad real: el mismo contenido se publica en web pública, app del comercial, kiosco de fábrica y dispositivo IoT. Una fuente, varias salidas, como un maestro de materiales que alimenta producción, calidad y compras.
• Interactividad exigente: dashboards de OEE, configuradores de producto, filtros dinámicos sobre catálogos de miles de SKUs en tiempo real.
• Equipos separados: backend en PHP/Drupal y frontend en JavaScript trabajando en paralelo, como mantenimiento y producción en parada programada.
• Rendimiento crítico: tráfico alto donde un frontend con renderizado estático (SSG) o server-side rendering (SSR) mediante Next.js o Nuxt.js baja el Time to First Byte de forma seria.

Si no entras en ninguno, no desacoples. Pagas complejidad sin recoger nada.

La API de Drupal: JSON:API frente a REST y GraphQL

Drupal 10 trae JSON:API en el core. No instalas nada, expones contenido como endpoints RESTful y a producir. Es la opción por defecto en proyectos headless Drupal.

JSON:API (recomendada para la mayoría de casos)

JSON:API sigue la especificación jsonapi.org, contrato predecible: filtrado, paginación, inclusión de relaciones y sparse fieldsets funcionan estándar. Para un frontend en React o Vue que lista artículos con autores y taxonomías, una sola petición con include resuelve lo que en REST clásico te pedía tres o cuatro llamadas. La diferencia entre un picking completo y cuatro viajes al almacén.

REST (útil para integraciones puntuales)

El módulo RESTful Web Services permite endpoints personalizados con control fino sobre la respuesta. Sirve cuando hay que exponer datos que no mapean a entidades de Drupal o cuando integras con legacy que espera un formato concreto: un MES antiguo, un PLC con su dialecto.

GraphQL (para consultas complejas)

El módulo contribuido GraphQL (graphql_compose) deja que el frontend pida exactamente los campos que necesita. En modelos profundos --e-commerce con variantes, atributos, precios por región y stock por almacén, o catálogo industrial con escandallos a tres niveles-- GraphQL recorta el overfetching. Según un benchmark publicado por Amazee Group en 2024, GraphQL redujo el tamaño medio de las respuestas un 38 % frente a JSON:API en un catálogo con más de 10.000 SKUs.

React o Vue: criterios de elección para el frontend

Drupal ya expone los datos. Toca decidir qué framework JavaScript los consume. Las dos opciones dominantes son React y Vue, y la elección depende más del equipo que de la herramienta. Como elegir entre dos marcas de robot: te casas con la que sabe usar tu mantenimiento.

React (con Next.js)

React es el que más cuota acumula. Según la encuesta Stack Overflow Developer Survey 2024, el 39,5 % de los desarrolladores profesionales utilizan React de forma habitual. Ecosistema grande: cualquier problema tiene tres librerías. Hay que elegir bien para no acabar con un Frankenstein.

Next.js añade SSR, SSG, ISR (Incremental Static Regeneration) y API routes. Para un headless Drupal con contenido que se mueve a ritmo razonable, ISR encaja: genera páginas estáticas en build time y las revalida en segundo plano cuando cambia el contenido. Producción contra stock con reposición automática.

Vue (con Nuxt.js)

Vue tiene curva más suave y sintaxis que entra fácil a desarrolladores de plantillas HTML. Nuxt.js ofrece lo mismo que Next.js: SSR, SSG y, desde Nuxt 3, hidratación parcial que reduce el JavaScript enviado al cliente.

Con perfil backend o full-stack sin JavaScript, Vue genera menos fricción. Con frontend sénior peleado con npm, React es la apuesta segura. Innegociable: SSR si te importa el SEO, y que el equipo pueda mantenerlo cuando el consultor se haya ido.

Arquitectura práctica: piezas que necesitas montar

Un proyecto real de headless Drupal con API decoupled y frontend en React o Vue no es enchufar dos servidores. Son varias piezas.

Autenticación y autorización

Si el frontend muestra contenido personalizado o protege rutas, necesitas autenticación. Opciones habituales:

• Simple OAuth (módulo contribuido): genera tokens OAuth 2.0 que el frontend manda en cada petición. Estándar cuando hay login. En entornos regulados --FDA 21 CFR Part 11 en farma, IATF 16949 en automoción-- deja de ser detalle técnico y pasa a requisito.
• API Key: para frontends que solo consumen contenido público, una API key con permisos de lectura llega y sobra.

Gestión de vistas previas (preview)

El editor de contenido pierde la previsualización cuando el frontend va por separado. Y un editor que no ve lo que publica acaba subiendo lo que no debe: soltar un lote sin liberación de calidad. Módulos como Decoupled Preview o el draft mode de Next.js recuperan esa función mostrando contenido no publicado antes de mandarlo a producción.

Gestión de medios e imágenes

Drupal genera derivados de imagen (image styles) en el servidor. En arquitectura desacoplada, el frontend consume las URLs vía API. El módulo Consumer Image Styles expone los estilos como parte de la respuesta JSON:API, así no hardcodeas rutas que se rompen al tocar configuración.

Despliegue y hosting

Dos despliegues independientes: backend Drupal (LAMP/LEMP o plataformas como Platform.sh o Lagoon) y frontend (Vercel, Netlify o Node.js propio). Complica el pipeline de CI/CD, pero escalas cada capa por separado. Como parar envasado sin parar mecanizado: ganas resiliencia.

Errores frecuentes y cómo evitarlos

Tras decenas de migraciones a headless Drupal, los patrones de fallo se repiten como no conformidades en una línea mal balanceada:

• No planificar la API antes del frontend: define tipos de contenido, campos y relaciones en Drupal antes de escribir una línea de React o Vue. Cambiar el modelo a media producción genera retrabajo en ambos lados, como rediseñar el escandallo con el lote ya lanzado.
• Ignorar el rendimiento de las consultas: una petición JSON:API con includes y sin filtros devuelve megabytes de JSON. Usa sparse fieldsets (fields[node--article]=title,body,field_image) y pides solo lo que necesitas.
• Prescindir de caché en el frontend: mete una capa (Redis, Varnish o el propio de Next.js/Nuxt.js) entre frontend y API de Drupal. Sin ella, cada visita golpea el backend y se cae la ventaja del desacoplamiento. Como mandar al carretillero al almacén central pieza a pieza en lugar de tener supermercado de línea.
• Olvidar la accesibilidad: cuando todo renderiza por JavaScript es fácil acabar con interfaces inaccesibles. SSR garantiza HTML inicial completo y navegable sin JS. Accesibilidad es como seguridad en planta: si no la metes en el diseño, la pagas en auditoría.

Caso de uso: portal de formación con 12.000 contenidos

Un caso representativo: una universidad española migró su portal de formación desde Drupal 9 monolítico a headless Drupal con API JSON:API y frontend en Nuxt.js. El catálogo, 12.000 fichas de cursos, 800 perfiles de profesorado y un buscador con filtros combinados por área, modalidad y nivel.

Tras seis meses en producción: el tiempo medio de carga de las páginas de catálogo pasó de 3,2 segundos a 0,9 segundos gracias al SSG con revalidación incremental. La tasa de rebote en las fichas de curso bajó un 22 % (datos de Google Analytics 4). El equipo de contenido siguió en el mismo panel de administración de Drupal, sin herramientas nuevas. Eso importa: el cambio tecnológico que obliga al usuario final a reaprender acaba en el cajón, igual que el MES que nadie usa porque el operario sigue apuntando en la libreta.

Hacia dónde va esta arquitectura

El ecosistema Drupal apunta a facilitar más el modelo headless. Drupal CMS (antes Starshot), previsto para consolidarse durante 2026, incluye de serie experiencias de configuración orientadas a frontends desacoplados. Iniciativas como la Decoupled Menus Initiative y el módulo Experience Builder buscan cerrar la brecha entre flexibilidad del decoupled y facilidad de uso del monolítico.

Por el lado JavaScript, Next.js 15 y Nuxt 4 incorporan streaming y renderizado parcial que reducen la latencia percibida. La combinación de backend Drupal sólido con frontend moderno en React o Vue ya no es apuesta arriesgada: es la arquitectura que adoptan organizaciones que necesitan escala, rendimiento y flexibilidad editorial.

Cierro con lo que veo en planta: muchas fábricas siguen llamando "digitalización" a tres hojas de Excel pasándose por correo. Cuando toca digitalizar control de calidad trazabilidad producción en serio --ligar lote, no conformidad, OEE y especificación de cliente bajo ISO 9001, IATF 16949, FDA 21 CFR Part 11 o estándares de logística como AECOC--, el portal que enseña esa información a operario, cliente y auditor no puede ser una página plana. Tiene que aguantar carga, soportar cambios de modelo sin parar la línea y dejar al editor trabajar sin pedir ticket a TI. Headless Drupal con API decoupled, frontend en React o Vue y un backend bien diseñado encaja cuando el proyecto lo pide. Cuando no, no lo metas: la sobreingeniería se paga en mantenimiento.

Si estás valorando el salto, escríbenos en https://tangramconsulting.es/contacto y lo miramos con datos sobre la mesa.