Tutorial Drupal Headless con Next.js: de Cero a Producción

Tutorial Drupal headless: qué vamos a montar

En este tutorial de Drupal headless vamos a construir la arquitectura mínima viable desde cero: Drupal actuando únicamente como API de contenido y un frontend en Next.js que lo consume y lo renderiza en servidor. Al terminar tendrás un listado de artículos y sus páginas de detalle funcionando con ISR (regeneración estática incremental), listo para desplegar.

No es un “hola mundo” de juguete: es el mismo esqueleto sobre el que se montan portales reales. Si aún dudas sobre si este enfoque es el adecuado para tu proyecto, antes de nada lee la comparativa Drupal headless vs decoupled, donde explico qué implica cada grado de desacoplamiento.

Requisitos previos

• Un Drupal 10 u 11 funcionando (en local con DDEV es lo más cómodo).
• Node.js 18+ y un proyecto Next.js con App Router.
• Drush para activar módulos.
• Un tipo de contenido con el que trabajar; usaremos article, que viene de serie en el perfil estándar.

Paso 1: activar JSON:API en Drupal

Drupal incluye JSON:API en core desde Drupal 8.7: no hay que instalar nada, solo activarlo:

drush en jsonapi -y
drush cr

Con esto, cada entidad de Drupal queda expuesta automáticamente bajo la ruta /jsonapi. Compruébalo:

curl https://tu-drupal.ddev.site/jsonapi/node/article | jq '.data[0].attributes.title'

Puntos clave de JSON:API que conviene conocer desde el principio:

• Respeta permisos: los usuarios anónimos solo ven contenido publicado. No expones borradores por accidente.
• Paginación: por defecto devuelve 50 elementos; controla con page[limit] y page[offset].
• Campos dispersos: con fields[node--article]=title,body,created reduces la respuesta a lo que necesitas.
• Relaciones: con include=field_image,uid incrustas las entidades relacionadas en la misma petición.

Una petición realista para un listado queda así:

curl "https://tu-drupal.ddev.site/jsonapi/node/article?fields[node--article]=title,created,path&page[limit]=10&sort=-created"

Paso 2: consumir Drupal desde Next.js

En el frontend creamos un cliente mínimo. La URL base de Drupal la guardamos en una variable de entorno (DRUPAL_BASE_URL en un .env.local), así el mismo código vale para local, staging y producción.

El listado de artículos con App Router es un Server Component que hace fetch con revalidación:

// app/articulos/page.jsx
async function getArticulos() {
  const url = `${process.env.DRUPAL_BASE_URL}/jsonapi/node/article` +
    `?fields[node--article]=title,created,path` +
    `&page[limit]=10&sort=-created`;

  const res = await fetch(url, { next: { revalidate: 60 } });
  if (!res.ok) throw new Error('Error al cargar artículos de Drupal');
  return res.json();
}

export default async function ArticulosPage() {
  const { data } = await getArticulos();

  return (
    <main>
      <h1>Artículos</h1>
      <ul>
        {data.map((articulo) => (
          <li key={articulo.id}>
            <a href={`/articulos/${articulo.id}`}>{articulo.attributes.title}</a>
          </li>
        ))}
      </ul>
    </main>
  );
}

El parámetro next: { revalidate: 60 } es la clave: Next.js genera la página de forma estática y la regenera en segundo plano cada 60 segundos como máximo (ISR). Obtenemos el rendimiento de un estático sin renunciar a contenido fresco.

Paso 3: páginas de detalle con rutas dinámicas

Para el detalle usamos el id (UUID) que JSON:API asigna a cada nodo. Con generateStaticParams pre-generamos las páginas existentes y con ISR las nuevas aparecen solas:

// app/articulos/[id]/page.jsx
export async function generateStaticParams() {
  const res = await fetch(
    `${process.env.DRUPAL_BASE_URL}/jsonapi/node/article?page[limit]=50`
  );
  const { data } = await res.json();
  return data.map((nodo) => ({ id: nodo.id }));
}

async function getArticulo(id) {
  const url = `${process.env.DRUPAL_BASE_URL}/jsonapi/node/article/${id}` +
    `?fields[node--article]=title,body,created`;
  const res = await fetch(url, { next: { revalidate: 60 } });
  if (!res.ok) throw new Error('Artículo no encontrado');
  return res.json();
}

export default async function ArticuloPage({ params }) {
  const { data } = await getArticulo(params.id);

  return (
    <article>
      <h1>{data.attributes.title}</h1>
      <div
        dangerouslySetInnerHTML={{ __html: data.attributes.body.processed }}
      />
    </article>
  );
}

Dos detalles importantes:

• body.processed ya viene con el HTML filtrado por el formato de texto de Drupal, así que es seguro de insertar. Si algún día renderizas texto sin procesar, sanitízalo antes.
• Para producción querrás añadir generateMetadata en estas páginas para que el <title> y la meta description salgan del contenido de Drupal — el SEO de un headless depende por completo del frontend.

Paso 4: de aquí a producción

Con esto tienes el esqueleto funcionando. Para llevarlo a producción real, estos son los siguientes pasos habituales:

1. Rutas por alias en lugar de UUID. JSON:API no resuelve aliases de URL por defecto. El módulo Decoupled Router expone un endpoint que traduce /mi-alias a su entidad, y es la pieza que usan casi todos los proyectos serios.
2. El ecosistema next-drupal. El proyecto Next.js for Drupal te da cliente JSON:API, previsualización de borradores, manejo de menús y revalidación on-demand cuando el editor publica. Cuando el proyecto crece, es el camino maduro.
3. CORS. Las peticiones de este tutorial van de servidor a servidor, así que CORS no aplica. Si algún día consultas JSON:API desde el navegador, configura cors.config en el services.yml de Drupal.
4. Caché en Drupal. Aunque el frontend cachee, JSON:API también se beneficia de la caché interna de Drupal. Si el tema te interesa, en la guía de cache bins en Drupal explico cómo funciona a bajo nivel.

Errores que ya he cometido para que no los cometas tú

De la experiencia llevando esta arquitectura a producción con portales universitarios:

• No hagas N peticiones por página. Si tu home necesita noticias, eventos y avisos, pedir cada bloque por separado desde el frontend multiplica la latencia. En el caso real lo resolvimos en el lado de Drupal: las peticiones de nodo —tanto en su versión por defecto (por id) como por alias— devolvían el layout configurado en el tema, con todos sus bloques ya resueltos en una única respuesta. Toda la historia está en la guía de Drupal headless con Next.js.
• No gestiones caché a mano en Node. La tentación existe y acaba en código espagueti. Usa ISR y la caché de Drupal, que es mucho más madura.
• No dejes el SEO para el final. Sin SSR/SSG y sin metadatos generados en el frontend, Google solo ve una página vacía. En un monolito eso salía gratis; aquí es tu responsabilidad.

Conclusión

Montar un Drupal headless con Next.js hoy es sorprendentemente directo: JSON:API viene en core, Next.js resuelve el renderizado con ISR y el despliegue son dos aplicaciones independientes. La dificultad no está en el tutorial, sino en las decisiones que vienen después: alias, previsualización, agregación de datos y caché.

Si quieres ver cómo se resuelven esos problemas en un proyecto real, el siguiente paso es la guía de Drupal headless con Next.js en producción. Y si estás explorando el CMS en general, todo lo que publico sobre él está en el hub de Drupal.