Next.js para Drupal: Guía completa para un frontend moderno y desacoplado

Drupal y Next.js se han consolidado en los últimos años como una combinación ganadora para quienes buscan flexibilidad, escalabilidad y una experiencia de usuario moderna en proyectos web. Si bien Drupal es uno de los CMS más potentes y versátiles, Next.js es el framework líder de React para creación de interfaces ultrarrápidas y dinámicas. ¿Qué sucede cuando fusionamos lo mejor de ambos mundos gracias a Next.js for Drupal? El resultado es una solución headless robusta, capaz de aprovechar todo el potencial de Drupal y las últimas innovaciones del frontend moderno.

Hoy en día, el concepto de headless CMS está en boca de todos los profesionales del desarrollo web. Drupal, tradicionalmente asociado a proyectos monolíticos, se adapta perfectamente a este enfoque desacoplado, permitiendo que el backend y el frontend evolucionen de manera independiente y mucho más ágil. Por su parte, Next.js aporta una velocidad sobresaliente, opciones avanzadas de renderizado y una experiencia de desarrollo optimizada. El ecosistema Next-Drupal aglutina recursos, herramientas, plantillas y una comunidad creciente que no deja de proponer mejoras. Si quieres saber cómo aprovechar todas estas ventajas y poner en marcha tu proyecto con garantías, aquí tienes la guía más completa, con todos los secretos, trucos y mejores prácticas para no perderte nada.

¿Qué es Next.js for Drupal y por qué es tan relevante?

Para entender la aportación real de Next.js for Drupal, conviene repasar en qué consiste cada una de las tecnologías y por qué su integración genera tanta expectación. Next.js es un framework de React que facilita el desarrollo de aplicaciones web con funcionalidades de renderizado híbrido (SSG, SSR, ISR), internacionalización, optimización automática, TypeScript, y una experiencia de despliegue sencilla y ágil. Por su parte, Drupal es un CMS open source de referencia, famoso por su robustez, flexibilidad y extensibilidad para gestionar grandes volúmenes de contenido y casos de uso complejos.

La integración Next.js for Drupal, impulsada principalmente por Chapter Three y una comunidad de desarrolladores activa, facilita desacoplar Drupal y emplearlo como backend, mientras Next.js se encarga de la presentación y experiencia de usuario. Esta arquitectura presenta ventajas sobresalientes:

• Separa el backend del frontend, lo que permite evolucionar cada parte sin depender de la otra.
• Mejora el rendimiento aprovechando las capacidades de generación estática, SSR e ISR de Next.js.
• Facilita la internacionalización y el soporte a sitios multilenguaje.
• Ofrece opciones avanzadas de previsualización de contenido durante la edición en Drupal.
• Integra autenticación, búsquedas facetadas, formularios complejos y roles de usuario sin renunciar a la seguridad ni a las capacidades avanzadas de Drupal.

Principales características del ecosistema Next-Drupal

El proyecto Next.js for Drupal no se limita a ser un puente básico entre backend y frontend. Dispone de un conjunto de módulos, paquetes, plantillas y utilidades listas para abordar los retos habituales de los proyectos desacoplados. De entre todas sus ventajas, destacan:

• Multi-sitio Next.js desde un único backend Drupal.
• Actualización de contenido casi instantánea gracias a las capacidades de revalidación bajo demanda y renderizado por petición.
• Previsualización de páginas y revisiones de contenido directamente desde la interfaz de Drupal.
• Autenticación avanzada, incluyendo soporte para roles, permisos y formularios desacoplados mediante React/Webforms.
• Búsquedas facetadas integradas con Search API y soporte para Elasticsearch.
• Detección automática de idioma y funcionalidades avanzadas de internacionalización.
• Seguridad reforzada al mantener separados los datos y la capa de presentación.

Recursos oficiales, comunidad y plantillas Starterkit

Para los desarrolladores que buscan un arranque rápido, existen varios recursos y plantillas open source:

• La web next-drupal.org centraliza documentación, ejemplos, guías y novedades de la integración.
• npmjs.com/package/next-drupal y los repositorios de GitHub (chapter-three/next-drupal) ofrecen bibliotecas, starter kits y directrices para contribuir o crear nuevas funcionalidades.
• El Next-Drupal Starter Kit de Wunderio es una plantilla exhaustiva enfocada en multilenguaje, automatización de entornos locales, metatags, búsquedas con Elastic UI y una completa experiencia de edición, pensada para reducir la fricción y acelerar el desarrollo de sitios desacoplados.

Estas herramientas, junto con la documentación y el soporte comunitario, son clave para nuevos proyectos o para migraciones desde arquitecturas monolíticas tradicionales.

Primeros pasos: cómo montar Drupal y Next.js en local con Docker y DDEV

Una de las grandes ventajas del enfoque desacoplado es la posibilidad de desarrollar y probar tanto el backend como el frontend en local de forma sencilla y homogénea, independientemente del sistema operativo. Gracias a Docker (contenedores universales) y herramientas como DDEV (interfaz de alto nivel para Docker centrada en PHP y proyectos web), puedes reproducir la infraestructura de producción en tu propio equipo sin complicaciones.

El proceso general implica:

• Instalar Docker en tu sistema (hay guías específicas para Linux, Windows y MacOS).
• Instalar DDEV, que se encarga de configurar los servicios de backend (PHP, bases de datos, etc.) y automatizar todo el ciclo de vida del entorno de desarrollo.

Para Windows, se recomienda emplear Docker Desktop y WSL2 para disfrutar de mejor rendimiento y evitar errores comunes de red o timeouts.

Una vez listos Docker y DDEV, tienes dos opciones: seguir la guía oficial de DDEV para Drupal o clonar un repositorio preconfigurado, donde solo tendrás que seguir los pasos del README. Esto agiliza mucho los primeros pasos.

Configuración de Drupal: paquetes, módulos y parches

Con el entorno en marcha, el siguiente paso es instalar el paquete Next.js for Drupal vía Composer:

composer require drupal/next

A menudo será necesario aplicar parches para resolver incompatibilidades conocidas, especialmente si trabajas con módulos como subrequests o decoupled_router. Puedes añadir estos parches en tu composer.json:

"extra": { "patches": { ... } }

Después, recuerda ejecutar:

composer require cweagans/composer-patches

Acto seguido, entra en la administración de módulos de Drupal y activa los módulos siguientes según tu preferencia:

• Next.js (es el principal, imprescindible).
• JSON:API o GraphQL (elige el que más se ajuste a tu modelo de consumo de datos).

Para esta guía se asume el uso de JSON:API por su sencillez y rápida integración.

Creación y estructura de un proyecto Next.js preparado para Drupal

En el lado frontend, lo más eficiente es recurrir a una plantilla básica adaptada para Drupal y Next.js, utilizando:

npx create-next-app -e https://github.com/chapter-three/next-drupal-basic-starter

Esto instalará una base de proyecto con configuración mínima, que puedes personalizar con tus módulos, rutas y componentes.

Es fundamental configurar correctamente la conexión entre el frontend y el backend. Dirígete en Drupal a /admin/config/services/next y añade tu nuevo sitio Next.js. Aquí obtendrás variables como DRUPAL_CLIENT_ID y DRUPAL_CLIENT_SECRET, que deberás trasladar a los archivos .env.local (en Next.js).

No olvides incluir:

NODE_TLS_REJECT_UNAUTHORIZED=0

Esto es necesario cuando tu Drupal local usa HTTPS con certificados autofirmados, evitando errores de verificación de certificado.

Creación de tipos de contenido y alias de rutas en Drupal

Drupal se basa en tipos de contenido o content types como plantilla estructural para organizar y mostrar la información. Por defecto existen tipos genéricos como Article o Page, pero nada te impide crear uno personalizado.

Imaginemos que quieres una sección de Noticias. Puedes crear el tipo News desde /admin/structure/types, asignarle campos (título, cuerpo, imagen destacada) y definir patrones de alias para sus rutas:

• Accede a /admin/config/search/path/.
• En "Patterns", crea un patrón para el tipo News, por ejemplo: news/[node:title].

De esta manera, los artículos de noticias tendrán URLs amigables (como /news/tendencias-tecnologicas) en lugar de los aburridos /node/123, facilitando el SEO y la experiencia de usuario.

Cómo funciona la revalidación bajo demanda (On-demand Revalidation) en Next.js y Drupal

Una de las grandes aportaciones de Next.js al ecosistema desacoplado es la posibilidad de elegir entre varias estrategias de obtención/renderizado de datos:

• Static Generation: Genera las páginas en tiempo de build. Ideal para contenido estático.
• Server-side Rendering (SSR): La página se genera en cada petición, siempre mostrando la información más reciente.
• Incremental Static Regeneration (ISR): Mezcla lo mejor de ambos mundos, permitiendo regenerar páginas de forma granular cuando hay actualizaciones, evitando rebuilds globales.
• On-demand Revalidation: Actualiza páginas específicas cuando cambian datos en Drupal, disparando la regeneración solo de las rutas afectadas.

La integración Next.js for Drupal simplifica enormemente la configuración de on-demand revalidation. Desde el admin de Drupal, puedes definir los endpoints de revalidación y el secreto compartido para garantizar la seguridad del proceso. Así, cuando edites, crees o borres un nodo (por ejemplo, una noticia), Drupal notificará a Next.js y éste regenerará automáticamente la URL correspondiente, sin intervención manual.

Para ponerlo en práctica:

• En Drupal, accede a /admin/config/services/next y configura el endpoint de revalidación y el secreto (DRUPAL_REVALIDATE_SECRET).
• En Next.js, crea el archivo pages/api/revalidate.ts y programa la lógica para aceptar las llamadas entrantes desde Drupal asegurando autenticidad (verificación del secreto) y procesando el slug de la URL a revalidar.

Con este sistema, los cambios de contenido en Drupal se reflejan casi instantáneamente en el frontend, sin tener que esperar a procesos de despliegue ni builds costosos.

Obtención y presentación de datos desde Drupal usando Next.js

Para mostrar contenido dinámico (por ejemplo, un listado de noticias), lo habitual es emplear librerías como next-drupal o realizar llamadas directas a la JSON:API de Drupal. Usando paquetes como drupal-jsonapi-params, puedes construir consultas sofisticadas para filtrar, ordenar e incluir relaciones (imágenes, autores, etc.).

Un ejemplo típico de integración sería crear, en Next.js, el archivo pages/news/index.tsx y definir la función de obtención de datos empleando la API correspondiente a tu tipo de contenido, incluyendo filtros por estado (publicado), orden descendente por fecha de creación, etc. Así, puedes renderizar cada noticia directamente en React, integrando los componentes de interfaz que desees.

Además, puedes aprovechar TypeScript para garantizar la tipificación de datos y reducir errores en desarrollo, así como herramientas de validación de variables de entorno como Zod para asegurarte de que tu aplicación tiene siempre la configuración adecuada antes de desplegarla.

Automatización, tests y optimización en el ciclo de desarrollo

El Starterkit de Wunderio y otras plantillas comunitarias apuestan por una experiencia de desarrollo sin tropiezos. Automatizan la instalación de dependencias, la configuración de entornos, la creación de contenido de demo (incluso multilingüe) y la puesta a punto de servicios complementarios como Elasticsearch y Redis.

• Puedes elegir entre Lando o DDEV como sistema de contenedores local.
• Incluyen scripts para arrancar, parar y reiniciar el entorno fácilmente.
• Permiten ejecutar operaciones npm dentro de los contenedores para garantizar que todos los desarrolladores usan versiones compatibles de Node y las mismas dependencias.
• Incluyen instrucciones sobre cómo importar/exportar bases de datos, limpiar cachés y gestionar la configuración avanzada.

Además, se incorporan pruebas automáticas de frontend empleando Cypress, listas para ejecutarse en local o en entornos CI/CD, asegurando calidad y estabilidad del trabajo realizado en el frontend.

Internacionalización y multilingüismo: la joya de la corona

En proyectos complejos, el soporte a varios idiomas suele ser un dolor de cabeza. Las plantillas y soluciones Next-Drupal ofrecen:

• Soporte completo para inglés, finés, sueco y cualquier otro idioma añadido en Drupal mediante las herramientas nativas de traducción.
• Indexación automática de contenido multilingüe en Elasticsearch.
• Integración de módulos como next-intl en el frontend para facilitar la gestión de traducciones en React.
• Interfaz y experiencia completamente traducidas, garantizando la coherencia entre backend y frontend, incluso con búsquedas facetadas y formularios avanzados.

Gestión de autenticación, roles y formularios desacoplados

La integración soporta casos complejos de autenticación, permitiendo:

• Restringir acciones o secciones a usuarios autenticados y con roles específicos.
• Permitir el registro de usuarios directamente desde el frontend Next.js, gestionando el flujo completo de alta, asignación de roles y envío de correos de confirmación.
• Crear formularios desacoplados con React que interactúen con módulos como Webform en Drupal para recibir datos, validarlos y proporcionar mensajes de feedback personalizados.

Esto abre la puerta a experiencias de usuario avanzadas, combinando la potencia del backend Drupal con la flexibilidad total del frontend React.

SEO y generación de sitemap

El SEO no se deja de lado: las plantillas Next-Drupal facilitan la generación automática de sitemap.xml, la integración de metatags dinámicos (combinando los datos estructurados de Drupal y las traducciones del frontend), así como la configuración de rutas amigables y accesibles desde el principio.

Consejos avanzados y mejores prácticas

• Cuando trabajes con múltiples entornos (local, test, producción), asegúrate de mantener todas las variables de entorno actualizadas y protegidas.
• Utiliza las extensiones recomendadas para VSCode, obteniendo autocompletado y sintaxis avanzada para trabajar tanto con GraphQL como con TypeScript.
• No olvides actualizar y revisar los parches disponibles en la comunidad antes de cada despliegue, para evitar sorpresas de incompatibilidad.
• En proyectos de grande escala, divide tus queries y fragmentos GraphQL para aprovechar las herramientas de codegen, asegurando siempre la máxima tipificación y validación de datos entre backend y frontend.

La integración entre Drupal y Next.js ha alcanzado un nivel de madurez que permite a equipos de cualquier tamaño y experiencia lanzarse a proyectos desacoplados de altísimo nivel, disfrutando de las mejores prácticas del sector sin renunciar a ninguna funcionalidad ni a la eficiencia. Tanto si buscas modernizar tu portal, como si eres desarrollador en busca de nuevos retos, el ecosistema Next-Drupal tiene todo lo que necesitas para crear webs modernas, seguras y escalables, ofreciendo una experiencia de usuario sobresaliente y un flujo de trabajo ágil desde el primer minuto.