Revalidation Next.js sur Vercel : invalider les donnees publiques de maniere sure

Publié le

14 juil. 2026

La mise en cache temporelle est un filet de securite utile, mais un catalogue, une page de documentation ou une collection marketing doivent souvent etre rafraichis peu apres leur publication. Next.js 16 permet d'associer des tags aux donnees mises en cache et d'invalider les entrees concernees depuis un environnement serveur. Une conception sure est etroite, authentifiee, observable et testee sur une preview avant la production.

Ce que vous allez mettre en place

Ce guide suppose un catalogue de produits public. Vous allez :

1. taguer le catalogue et chaque recuperation de produit ;
2. creer un Route Handler de webhook protege ;
3. utiliser revalidateTag avec le profil "max" de Next.js 16 ;
4. revalider les chemins de pages concernes ; et
5. verifier le comportement apres un deploiement de preview.

Utilisez ce pattern pour le contenu public. Le tableau de bord d'un visiteur connecte ou une confirmation de commande doivent normalement recuperer des donnees privees et fraiches.

Etape 1 : associer des tags stables et intentionnels

Choisissez des tags autour de la responsabilite des donnees, non autour des composants d'interface. Gardez des noms de tags courts, deterministes et comprehensibles par le systeme de publication.

// lib/products.ts
export type Product = {
  slug: string
  name: string
  price: number
}

export async function getProducts(): Promise<Product[]> {
  const response = await fetch("https://api.example.com/products", {
    next: {
      revalidate: 3600,
      tags: ["products"],
    },
  })

  if (!response.ok) throw new Error("Unable to load products")
  return response.json()
}

export async function getProduct(slug: string): Promise<Product> {
  const response = await fetch(`https://api.example.com/products/${slug}`, {
    next: {
      revalidate: 3600,
      tags: ["products", `product:${slug}`],
    },
  })

  if (!response.ok) throw new Error("Unable to load product")
  return response.json()
}

L'intervalle d'une heure est un filet de securite, pas une promesse que les donnees resteront obsoletes exactement une heure. Un tag permet a un evenement de publication faisant autorite de demander une revalidation plus tot.

Etape 2 : identifier les chemins qui rendent les donnees

Etablissez une petite correspondance avant d'ecrire le webhook. Dans cet exemple, une mise a jour produit change la page de collection et une page detail :

Les tags invalident les donnees partagees dans toutes les pages qui les utilisent. revalidatePath cible une route. Utilisez les deux uniquement lorsque l'evenement affecte reellement les donnees sous-jacentes et un chemin rendu.

Etape 3 : ajouter un Route Handler de webhook protege

Stockez un secret aleatoire dans les variables d'environnement Vercel. Ne le placez pas dans un bundle client, un fichier source, un parametre d'URL ou une configuration visible par le navigateur.

// app/api/revalidate-products/route.ts
import { revalidatePath, revalidateTag } from "next/cache"
import { NextRequest } from "next/server"

type ProductEvent = {
  type: "product.published"
  slug: string
}

export async function POST(request: NextRequest) {
  const expected = process.env.REVALIDATE_PRODUCTS_SECRET
  const authorization = request.headers.get("authorization")

  if (!expected || authorization !== `Bearer ${expected}`) {
    return Response.json({ error: "Unauthorized" }, { status: 401 })
  }

  const event = (await request.json()) as ProductEvent

  if (event.type !== "product.published" || !event.slug) {
    return Response.json({ error: "Unsupported event" }, { status: 400 })
  }

  revalidateTag("products", "max")
  revalidateTag(`product:${event.slug}`, "max")
  revalidatePath("/products")
  revalidatePath(`/products/${event.slug}`)

  return Response.json({ revalidated: true, slug: event.slug })
}

revalidateTag(tag, "max") utilise un comportement stale-while-revalidate : la visite suivante peut recevoir une reponse obsolete pendant que Next.js la rafraichit en arriere-plan. C'est un bon defaut pour les catalogues et contenus editoriaux publics. Utilisez une Server Action avec updateTag lorsqu'un meme utilisateur doit lire immediatement sa propre mise a jour ; ne transformez pas un webhook public en rafraichissement global synchrone sans besoin produit clair.

Etape 4 : configurer l'emetteur et tester une preview

Ajoutez d'abord REVALIDATE_PRODUCTS_SECRET dans l'environnement de preview. Configurez le systeme de contenu ou de produits pour qu'il n'appelle que l'URL de preview pendant le test. Depuis un terminal utilisant une variable de secret temporaire, envoyez un evenement connu :

curl -sS -i -X POST https://preview.example.com/api/revalidate-products \
  -H "Authorization: Bearer $REVALIDATE_PRODUCTS_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"type":"product.published","slug":"running-shoe"}'

Attendez une reponse 200 contenant le slug exact. Verifiez qu'un en-tete d'autorisation absent ou incorrect renvoie 401, et qu'un type d'evenement inattendu renvoie 400. Ne journalisez pas l'en-tete d'autorisation ni le corps complet du webhook s'ils peuvent contenir des donnees metier sensibles.

Etape 5 : verifier la fraicheur sans deviner

Avant de declencher l'evenement, relevez le nom du produit visible, le prix, la revision ou un autre marqueur inoffensif. Publiez un changement connu, appelez le webhook une fois et demandez les deux URL concernees :

curl -sS https://preview.example.com/products | grep "Running Shoe"
curl -sS https://preview.example.com/products/running-shoe | grep "Running Shoe"

La premiere reponse apres revalidateTag(..., "max") peut etre obsolete pendant la regeneration. Demandez a nouveau apres un court intervalle et comparez le marqueur. Considerez les en-tetes comme une preuve complementaire, non comme la source de verite : le corps rendu, les logs applicatifs et l'enregistrement amont doivent concorder.

Etape 6 : promouvoir progressivement

Apres validation de la preview :

1. ajoutez le meme secret a la production sans l'exposer au navigateur ;
2. pointez l'emetteur vers la production seulement lorsque le deploiement est sain ;
3. declenchez une mise a jour controlee pour un element public connu ;
4. verifiez la collection concernee et la route detail ; et
5. surveillez les echecs de webhook, les erreurs de recuperation amont, les erreurs de revalidation de cache et les signalements de contenu obsolete.

Conservez la valeur normale de revalidate basee sur le temps. Elle limite l'impact si un emetteur est indisponible ou si une livraison de webhook echoue.

Retour arriere et reprise

Si un mauvais evenement ou un changement de code atteint la production, desactivez d'abord l'emetteur ou restaurez le deploiement precedent. Utilisez ensuite le meme handler authentifie pour revalider uniquement les tags et chemins connus apres correction des donnees source. Evitez une purge CDN large comme premiere reponse a un probleme de donnees applicatives : elle peut creer une charge d'origine evitable tout en laissant les donnees source ou la correspondance de routes incorrectes.

Erreurs frequentes

• Appeler la forme depreciee revalidateTag(tag) a un seul argument dans Next.js 16.
• Laisser un corps de requete choisir des tags ou chemins arbitraires.
• Taguer chaque produit avec un schema de noms de tags illimite et opaque.
• Supposer qu'un tag invalide rechauffe instantanement chaque route dans chaque region.
• Ne revalider qu'un chemin alors que les memes donnees apparaissent sur plusieurs pages.
• Utiliser une route API publique pour invalider du contenu sans authentification ni validation d'evenement.

References faisant autorite

• Next.js revalidateTag
• Next.js revalidatePath
• Mise en cache et revalidation Next.js
• Vue d'ensemble du cache Vercel