Drupal découplé avec Next.js : guide d'architecture

Pourquoi découpler Drupal

Le Drupal découplé (headless) sépare le back-end de gestion de contenu de la couche de présentation. Cette architecture permet d'utiliser un framework JavaScript moderne comme Next.js pour le front-end, tout en conservant la puissance de modélisation de contenu et les outils éditoriaux de Drupal.

Mettre en place JSON:API

Le module JSON:API, intégré au cœur depuis Drupal 9, fournit une API conforme aux standards sans configuration lourde. Il suffit de l'activer et de configurer les types de ressources :

// Activer JSON:API depuis un fichier .install
function mon_module_install() {
  \Drupal::service('module_installer')->install(['jsonapi']);
}

JSON:API expose automatiquement tous les types d'entités avec les opérations CRUD complètes, le filtrage, le tri, la pagination et l'inclusion des relations.

Modéliser le contenu pour une consommation par API

Quand on conçoit des types de contenu pour une architecture découplée, il faut penser aux besoins du consommateur de l'API. Structurez les entités avec des relations claires et évitez les références profondément imbriquées, qui créent des schémas de requêtes N+1.

Principes clés :

• Plat plutôt qu'imbriqué : limitez la profondeur des références à deux niveaux
• Champs calculés : utilisez des plugins de champs calculés pour les données dérivées
• Références d'entités : préférez les références d'entités au texte libre pour les données structurées
• Entités média : utilisez toujours Media pour les images et les fichiers, leur représentation dans l'API est meilleure

Stratégie d'authentification

Pour du contenu public, JSON:API fonctionne sans authentification. Pour les ressources protégées, on met en place OAuth2 avec le module Simple OAuth :

# Configuration des portées OAuth2
simple_oauth.settings:
  access_token_expiration: 3600
  refresh_token_expiration: 1209600

Récupérer les données côté Next.js

Côté Next.js, on récupère les données au moment du build avec generateStaticParams et fetch, en s'appuyant sur l'ISR (régénération statique incrémentale) :

async function getArticles() {
  const res = await fetch(
    `${process.env.DRUPAL_BASE_URL}/jsonapi/node/article?sort=-created&page[limit]=10`,
    { next: { revalidate: 60 } }
  );
  return res.json();
}

Stratégie de cache

Une architecture découplée exige une stratégie de cache solide :

• Couche CDN : mettez en cache les réponses JSON:API en périphérie
• Cache tags Drupal : activez les en-têtes de cache tags pour une invalidation ciblée
• ISR Next.js : revalidez les pages selon un calendrier ou à la demande via des webhooks
• Webhooks : Drupal déclenche un webhook à chaque changement de contenu, et Next.js revalide les chemins concernés

Architecture de déploiement

Le schéma de déploiement recommandé :

1. Drupal : hébergé sur une pile LAMP/Docker classique
2. Next.js : déployé sur Vercel ou une plateforme edge équivalente
3. CDN : entre Drupal et Next.js, pour la mise en cache de l'API
4. Relais de webhooks : les changements de contenu déclenchent la revalidation Next.js

Conclusion

Drupal découplé avec Next.js offre le meilleur des deux mondes : la maturité de la gestion de contenu et de l'expérience éditoriale de Drupal, associée aux performances et au confort de développement de Next.js sur le front-end.