Vous avez branché un webhook Drupal sur votre site Next.js pour que chaque publication se voie tout de suite. Résultat : à chaque modification, même mineure, le site entier se recache. La facture d'hébergement grimpe, la latence revient. L'ISR Next.js, censé réduire les coûts, produit l'effet inverse.
Le problème : l'invalidation naïve recache tout le site
Le réflexe immédiat consiste à appeler revalidatePath('/', 'layout') dans le gestionnaire du webhook. Cet appel purge le cache client et invalide toutes les données en cache pour la prochaine visite de n'importe quelle page du site (documentation Next.js). Concrètement, publier un article sur votre blog force la reconstruction de la page d'accueil, des pages produits et de tout le reste, alors qu'une seule URL a réellement changé.
Le symptôme se repère facilement : un pic de charge sur le trafic qui suit chaque sauvegarde dans Drupal, et des temps de réponse dégradés le temps que les pages se régénèrent. Le point de revalidation choisi est en cause, pas Next.js ni Drupal.
ISR Next.js et revalidation à la demande : path vs tag
La revalidation temporelle, régie par un délai
L'ISR sert une page depuis le cache, puis la régénère en arrière-plan une fois le délai de revalidation dépassé. Next.js recommande de fixer un délai élevé, par exemple une heure plutôt qu'une seconde, et de réserver la revalidation à la demande aux cas où une précision plus fine est nécessaire (guide ISR Next.js). L'ISR seule ne résout donc pas le problème d'une page qui doit changer au moment exact de la publication.
revalidatePath('/', 'layout') : le recaching générique à éviter
Comme vu plus haut, cet appel invalide l'ensemble du cache. Il a sa place pour un déploiement ou un changement de structure globale, pas pour la mise à jour d'un seul article.
revalidateTag : une invalidation ciblée, différée à la prochaine requête
revalidateTag marque des données comme obsolètes. La revalidation réelle se déclenche à la requête suivante sur cette donnée, pas au moment de l'appel : les pages qui portent le tag se régénèrent au fil des visites, pas toutes en même temps (documentation revalidateTag). Cette fonction ne s'appelle que dans une Server Function ou un Route Handler, jamais dans un Client Component.
Pour la plupart des cas, Next.js recommande de revalider des chemins entiers avec revalidatePath ; revalidateTag entre en jeu quand vous avez besoin d'un contrôle plus granulaire, par exemple invalider une fiche produit sans toucher au reste du catalogue (guide ISR Next.js).
Les cache tags Drupal, déclencheur des webhooks ciblés
Ce que Drupal envoie une fois le mode tag activé
Le module next expédie par défaut le revalidator « Path », qui revalide le site en fonction du chemin de l'entité (documentation du revalidator). Depuis la version 2.0 du module, un second revalidator, « Cache Tag », permet d'invalider le contenu de votre site Next.js en s'appuyant directement sur le système de cache tags de Drupal (guide revalidation à la demande). Ce second revalidator ouvre la voie à une invalidation précise.
Pour activer ce comportement sur un type d'entité, il faut sélectionner le plugin « Cache Tag » dans /admin/config/services/next/entity-types (configuration des types d'entités). Drupal envoie alors, à chaque création, modification ou suppression, les cache tags de l'entité concernée plutôt qu'un simple chemin : votre endpoint Next.js reçoit de quoi ne rafraîchir que les données concernées.
Le module expose aussi deux événements utiles pour instrumenter cette chaîne : EntityEvents::ENTITY_ACTION, déclenché à l'insertion, la modification ou la suppression d'une entité, et EntityEvents::ENTITY_REVALIDATED, déclenché après la revalidation (documentation des événements). Vous pouvez vous en servir pour journaliser chaque invalidation et vérifier, dans vos traces, que le bon tag a bien été rafraîchi (notre article sur l'observabilité Next.js / Drupal).
Construire et sécuriser le endpoint de revalidation
La route /api/revalidate côté Next.js
L'implémentation de référence proposée par next-drupal vérifie un secret transmis en paramètre de requête, le compare à une variable d'environnement, puis appelle revalidatePath ou revalidateTag (guide de configuration de la route). Ce secret en query string a une limite concrète : il peut se retrouver dans des journaux d'accès ou des outils de monitoring tiers. Si votre site passe par un proxy ou un CDN entre Drupal et Next.js, vérifiez que ces journaux ne sont pas exposés, au même titre que pour toute couche de cache HTTP partagée (notre article sur les caches HTTP unifiés).
Le secret de revalidation côté Drupal
La configuration d'un site Next.js dans Drupal, sous /admin/config/services/next, demande une URL de revalidation et un secret partagé avec votre endpoint (configuration du site). Ce secret distingue un appel légitime de Drupal d'une requête anonyme, rejetée en 401.
Une fois le mode tag activé sur un type de contenu, l'option tags remplace le délai de revalidation en secondes : la donnée reste en cache jusqu'à ce que Drupal appelle la route de revalidation avec un tag correspondant (paramètres de revalidation). Ce mécanisme permet de garder une donnée en cache sans délai fixe, puis de la marquer comme obsolète dès la modification dans Drupal : la page concernée se régénère à la visite suivante, pas au moment de l'appel.
Choisir le bon profil revalidateTag pour un webhook
revalidateTag prend un second argument qui fixe la durée pendant laquelle du contenu obsolète peut encore être servi. Le profil max, recommandé dans la documentation officielle, ouvre une fenêtre d'un an, assez longue pour que les requêtes continuent d'être servies depuis le cache obsolète pendant la revalidation (documentation revalidateTag). Ce choix convient par défaut à un webhook de contenu classique.
Un cas particulier mérite votre attention : quand l'invalidation vient de l'extérieur d'une Server Action, par exemple un webhook qui appelle un Route Handler, la fonction updateTag n'est pas disponible. Next.js recommande alors de passer { expire: 0 } pour faire disparaître le contenu obsolète immédiatement (documentation revalidateTag). Réservez cette option aux contenus où montrer une version périmée, même une seconde, pose un vrai problème : une page de prix ou un statut de stock, par exemple.
Aller plus loin : événements d'entité et revalidateurs personnalisés
Au-delà de « Path » et « Cache Tag », le module next permet d'implémenter votre propre revalidator via l'API Plugin de Drupal (documentation du revalidator). Cette voie convient si votre site combine plusieurs sources de contenu, ou si une entité doit invalider des tags qui ne correspondent pas à sa propre page, par exemple une page de catégorie qui doit se rafraîchir quand un seul produit qu'elle liste change. Cette logique rejoint le soin que nous mettons à documenter les contrats entre Drupal et Next.js pour éviter les régressions front (notre article sur les contrats d'API).
Conclusion
Mettre en place cette chaîne, du cache tag Drupal jusqu'au bon profil revalidateTag, demande de connaître à la fois les entités de votre modèle de contenu et les contraintes réelles de votre infrastructure Next.js.
Demander un diagnostic reste le point de départ pour identifier où votre site découplé recache plus qu'il ne devrait.