Une fiche produit e-commerce affiche un prix mis à jour cinq minutes plus tôt dans le CMS, mais toujours l'ancien prix côté site public. L'équipe vérifie la base de données, le prix est correct. Elle vérifie l'API, elle renvoie la bonne valeur. Le problème n'est ni dans la donnée ni dans la requête : il est dans la couche de cache de Next.js, que l'Incremental Static Regeneration (ISR) rend à la fois extrêmement efficace et facile à mal comprendre.

Le problème concret

ISR permet de générer des pages statiquement au build, puis de les régénérer en arrière-plan après un certain délai, sans reconstruire tout le site. C'est le compromis entre le SSG pur (rapide mais figé) et le SSR pur (toujours frais mais coûteux en calcul serveur à chaque requête). Le piège, c'est que "régénération en arrière-plan" ne veut pas dire "immédiatement après la mise à jour des données" : ça veut dire "à la prochaine requête qui arrive après l'expiration du délai configuré".

Comment ISR fonctionne réellement

Avec l'App Router (Next.js 13+), la revalidation par délai se configure via revalidate sur un segment ou dans un fetch :

// app/products/[slug]/page.tsx
export const revalidate = 300; // 5 minutes

async function getProduct(slug: string) {
  const res = await fetch(`https://api.example.com/products/${slug}`, {
    next: { revalidate: 300 },
  });
  if (!res.ok) throw new Error("Failed to fetch product");
  return res.json();
}

export default async function ProductPage({ params }: { params: { slug: string } }) {
  const product = await getProduct(params.slug);
  return <ProductDetails product={product} />;
}

Le mécanisme sous-jacent s'appelle stale-while-revalidate. Voici ce qui se passe réellement :

  1. Une page est générée et mise en cache avec un horodatage.
  2. Pendant les 300 premières secondes, toute requête reçoit la page en cache instantanément, sans aucun appel à l'API.
  3. Après 300 secondes, la prochaine requête reçoit encore la version en cache (c'est la clé du comportement), mais déclenche en arrière-plan une régénération.
  4. Une fois la régénération terminée, le cache est remplacé, et les requêtes suivantes reçoivent la nouvelle version.

Autrement dit, entre la mise à jour réelle de la donnée et son affichage effectif, il peut s'écouler le délai de revalidate plus le temps d'attente avant qu'une requête ne déclenche la régénération. Pour un contenu qui change rarement (page "À propos", article de blog), c'est un excellent compromis. Pour un prix ou un stock, c'est potentiellement un bug fonctionnel.

Diagnostiquer le problème

Le symptôme typique : "ça finit par se mettre à jour, mais pas tout de suite, et pas de façon prévisible." Pour vérifier que c'est bien ISR en cause et pas un problème de cache CDN ou navigateur :

curl -I https://monsite.com/products/chaussure-running

L'en-tête x-nextjs-cache (sur Vercel, x-vercel-cache) indique HIT, STALE ou MISS. Un STALE confirme que vous recevez une version périmée en attendant la régénération en arrière-plan.

La correction : revalidation à la demande

Pour du contenu qui doit refléter une mise à jour immédiatement après qu'elle se produit (changement de prix, publication d'un article, mise à jour de stock), la bonne approche n'est pas de réduire revalidate à une valeur agressive comme 10 secondes - ça ne fait que déplacer le problème et multiplie les appels à l'origine. La bonne approche est la revalidation à la demande, déclenchée par un webhook depuis le CMS ou l'admin :

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

export async function POST(req: NextRequest) {
  const secret = req.nextUrl.searchParams.get("secret");
  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ message: "Invalid token" }, { status: 401 });
  }

  const { slug, tag } = await req.json();

  if (tag) {
    revalidateTag(tag);
  } else if (slug) {
    revalidatePath(`/products/${slug}`);
  }

  return NextResponse.json({ revalidated: true, now: Date.now() });
}

Côté fetch, on associe un tag plutôt qu'un simple délai :

const res = await fetch(`https://api.example.com/products/${slug}`, {
  next: { tags: [`product-${slug}`] },
});

Le CMS (ou l'endpoint admin qui modifie le prix) appelle ensuite /api/revalidate juste après l'écriture en base, avec le tag concerné. Le cache est invalidé exactement au moment voulu, sans polling et sans sacrifier les performances du reste du temps. C'est la différence entre une revalidation "basée sur le temps" (approximative, pour du contenu tolérant à la latence) et une revalidation "basée sur l'événement" (précise, pour du contenu sensible).

Un piège fréquent : le cache de données côté fetch vs le cache du routeur côté client

Même après une revalidation serveur réussie, un utilisateur qui navigue côté client peut encore voir l'ancienne page, parce que le Router Cache de Next.js (côté client, dans le navigateur) garde ses propres segments en mémoire pendant la navigation, indépendamment du cache de données côté serveur. Une navigation complète (rechargement de page, ou retour après un délai) finit par resynchroniser, mais ça explique pourquoi un revalidatePath réussi côté serveur ne se voit parfois pas "immédiatement" dans l'onglet déjà ouvert de l'utilisateur qui vient de naviguer entre deux pages du même site sans recharger.

Le piège des pages jamais pré-générées : dynamicParams et le premier visiteur

ISR ne se limite pas à la revalidation des pages déjà construites : il faut aussi décider ce qui se passe pour une page dont le chemin n'a pas été inclus dans generateStaticParams au moment du build - typiquement un produit ajouté après le dernier déploiement.

// app/products/[slug]/page.tsx
export async function generateStaticParams() {
  const products = await getTopProducts(500); // seulement les 500 plus consultés au build
  return products.map((p) => ({ slug: p.slug }));
}

export const dynamicParams = true; // comportement par défaut : autorise les slugs non pré-générés

Avec dynamicParams à true (la valeur par défaut), le premier visiteur sur un slug non pré-généré déclenche un rendu à la demande côté serveur, qui est ensuite mis en cache comme n'importe quelle page ISR pour les visiteurs suivants. Ce visiteur paie donc le coût de latence du premier rendu, sans erreur 404. C'est le comportement souhaitable pour un catalogue qui grossit en continu.

Le piège apparaît quand on met dynamicParams à false pour "forcer" un catalogue figé : toute page non incluse dans generateStaticParams renvoie alors une 404, même si le produit existe réellement en base. C'est parfois un choix légitime (contenu volontairement limité à un ensemble connu), mais c'est une cause fréquente de "pourquoi ce produit tout juste publié renvoie une 404" quand ce choix a été fait sans que toute l'équipe le sache.

Le contenu en brouillon : draft mode et contournement volontaire du cache

Un cas différent, mais lié : un éditeur veut prévisualiser un article non publié, ou une page produit avec un prix pas encore effectif, sans attendre une revalidation ni affecter ce que voient les autres visiteurs. Le Draft Mode de Next.js sert exactement ce besoin en court-circuitant le cache ISR pour la session de l'éditeur uniquement.

// app/api/draft/route.ts
import { draftMode } from "next/headers";
import { redirect } from "next/navigation";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const secret = searchParams.get("secret");
  const slug = searchParams.get("slug");

  if (secret !== process.env.DRAFT_SECRET) {
    return new Response("Invalid token", { status: 401 });
  }

  (await draftMode()).enable();
  redirect(`/products/${slug}`);
}
// app/products/[slug]/page.tsx
import { draftMode } from "next/headers";

async function getProduct(slug: string) {
  const isDraft = (await draftMode()).isEnabled;
  const res = await fetch(`https://api.example.com/products/${slug}?preview=${isDraft}`, {
    cache: isDraft ? "no-store" : "default",
    next: isDraft ? undefined : { tags: [`product-${slug}`] },
  });
  return res.json();
}

Le cookie de draft mode n'affecte que le navigateur qui l'a activé : les autres visiteurs continuent de recevoir la version en cache normale. C'est un outil distinct de la revalidation à la demande, mais les deux se complètent dans un pipeline éditorial réel : draft mode pour la prévisualisation avant publication, revalidateTag pour la mise à jour effective après publication.

Quand la solution ne suffit pas

Pour des données qui doivent être garanties à jour à la milliseconde (solde d'un compte, disponibilité d'un siège en réservation), ISR n'est simplement pas le bon outil, même avec revalidation à la demande : il reste une fenêtre de cache, aussi courte soit-elle. Dans ce cas, la bonne approche est le rendu dynamique explicite (export const dynamic = "force-dynamic" ou un appel fetch avec cache: "no-store") sur ce segment précis, en acceptant le coût de calcul serveur à chaque requête, tout en gardant ISR pour le reste du site qui n'a pas cette contrainte.

À retenir

ISR ne garantit jamais une fraîcheur immédiate par défaut : il garantit une fraîcheur bornée par votre délai de revalidation, avec un décalage additionnel lié au trafic. Pour du contenu critique, remplacez le délai temporel par une invalidation événementielle via revalidateTag ou revalidatePath déclenchée au moment précis de l'écriture des données, et réservez le rendu entièrement dynamique aux données qui ne tolèrent aucune fenêtre de cache.