Incremental Static Regeneration (ISR)

Was ist Incremental Static Regeneration (ISR)?

Incremental Static Regeneration (ISR) liefert vorgerenderte statische Seiten aus und aktualisiert sie nach dem Deployment im Hintergrund, ohne die ganze Website neu zu bauen. Läuft der Cache einer Seite ab, bekommt der nächste Besucher noch die gespeicherte Kopie, während eine neue Version entsteht, und alle danach sehen die frische. ISR ist ein Next.js-Feature und arbeitet pro Seite, nicht pro Website.

So funktioniert ISR

Nehmen wir einen Blog mit einer Route wie /blog/[id]. Die Next.js-Dokumentation beschreibt diesen Ablauf:

1. Bei next build rendert Next.js für jede ID aus generateStaticParams eine Seite vor.
2. Anfragen an diese Seiten werden aus dem Cache bedient und sind sehr schnell.
3. Ist die Revalidierungszeit abgelaufen (zum Beispiel 60 Sekunden), erhält die nächste Anfrage noch die gecachte, nun veraltete Seite.
4. Diese Anfrage löst außerdem im Hintergrund die Neugenerierung der Seite aus.
5. Sobald die neue Version erfolgreich erzeugt ist, ersetzt sie die gecachte, und die nächste Anfrage bekommt sie.
6. Eine nicht vorgerenderte Seite wie /blog/26 wird beim ersten Aufruf bei Bedarf erzeugt, sofern sie existiert. Existiert sie nicht, lautet die Antwort 404. Die Einstellung dynamicParams ändert dieses Verhalten.

Das ist das Muster stale-while-revalidate: erst Geschwindigkeit, einen Moment später Aktualität. Wirft die Neugenerierung einen Fehler, wird weiter die zuletzt erfolgreich erzeugte Seite ausgeliefert, und Next.js versucht es bei der nächsten Anfrage erneut.

Zeitbasierte und bedarfsgesteuerte Revalidierung

Die zeitbasierte Revalidierung gibt einer Seite über die Route-Segment-Option revalidate eine Lebensdauer in Sekunden:

export const revalidate = 3600 // höchstens einmal pro Stunde aktualisieren

Die bedarfsgesteuerte Revalidierung macht eine Seite ungültig, wenn sich der Inhalt wirklich ändert, etwa nachdem eine Redakteurin einen Beitrag veröffentlicht hat. Im App Router rufen Sie dafür revalidatePath oder revalidateTag aus einer Server Action oder einem Route Handler auf:

'use server'
import { revalidatePath } from 'next/cache'

export async function createPost() {
  // Route /posts als veraltet markieren
  revalidatePath('/posts')
}

Beide Funktionen machen den Cache-Eintrag ungültig, die Neugenerierung passiert erst bei der nächsten Anfrage, nicht sofort. Die Doku empfiehlt einen hohen zeitbasierten Wert, etwa eine Stunde statt einer Sekunde, und bei Bedarf an mehr Präzision die bedarfsgesteuerte Revalidierung.

ISR mit Cache Components

Next.js dokumentiert inzwischen zwei Modelle, und die Schritte oben beschreiben ISR ohne Cache Components. Ist cacheComponents in Ihrer Next.js-Konfiguration aktiviert, cachen Sie mit der Direktive use cache und geben Ergebnissen mit cacheLife eine Lebensdauer. ISR funktioniert dann anders: Für eine URL, die nicht in generateStaticParams steht, liefert Next.js sofort eine generische App Shell aus und wertet sie im Hintergrund auf, sobald die Parameter bekannt sind. Laut Dokumentation wird die App Shell für nicht aufgeführte Parameter ab Next.js 16.3 ausgeliefert, frühere Versionen warten auf ein vollständiges Server-Rendering. Die Migrationshinweise ordnen getStaticProps mit revalidate dem Muster use cache mit cacheLife zu. Prüfen Sie, welches Modell Ihr Projekt nutzt, bevor Sie ein Beispiel übernehmen.

ISR im Vergleich zu SSG und SSR

• Static Site Generation (SSG) baut jede Seite einmal beim Build, Inhalte ändern sich also erst nach einem neuen Build.
• ISR startet wie SSG mit vorgerenderten Seiten und aktualisiert sie nach dem Deployment, per Zeitplan oder auf Abruf.
• Server-Side Rendering (SSR) rendert bei jeder Anfrage. Das ist immer aktuell, aber der Server arbeitet jedes Mal, sofern kein Cache davorsitzt.

ISR passt zu Inhalten, die sich ändern, aber nicht jede Sekunde: Produktseiten, Artikel, Dokumentation. Für nutzerspezifische oder Echtzeitdaten verweist die Next.js-Doku auf dynamisches Rendering. Solche statische Ausgabe lässt sich außerdem besonders gut über ein Content Delivery Network (CDN) cachen. Mehr zum Framework finden Sie unter Next.js.

Häufige Fehler

• Sofortige Aktualität erwarten. Der erste Besucher nach Ablauf sieht die veraltete Seite. Ist das nicht akzeptabel, nutzen Sie bedarfsgesteuerte Revalidierung oder dynamisches Rendering.
• Einen sehr kurzen revalidate-Wert setzen. Eine Sekunde erzeugt die Seite ständig neu und hebelt den Sinn statischer Ausgabe aus.
• Mehrere Instanzen mit dem Standard-Cache betreiben. Der Standard-Dateisystem-Cache gilt pro Instanz, daher macht eine bedarfsgesteuerte Revalidierung nur die Instanz ungültig, die den Aufruf erhält. Verwenden Sie einen gemeinsamen eigenen Cache-Handler.
• ISR dort einsetzen, wo es nicht unterstützt wird. ISR braucht die Node.js-Runtime und funktioniert nicht mit statischem Export.
• Den falschen Pfad revalidieren. Proxy läuft bei bedarfsgesteuerten ISR-Anfragen nicht, revalidieren Sie also den exakten Pfad (/post/1, nicht das umgeschriebene /post-1).
• Fetch-Einstellungen mischen. Bei mehreren Fetches in einer Route gilt die kürzeste Revalidierungszeit, und ein Fetch mit revalidate 0 oder no-store macht die Route dynamisch.

ISR-Seiten testen und überwachen

Eine gecachte Seite und eine Seite, die gerade neu erzeugt wird, verhalten sich sehr unterschiedlich. Ein Test, der nur warme URLs abruft, misst deshalb den Cache und nicht Ihren Server. Next.js setzt den Antwort-Header x-nextjs-cache mit den Werten HIT, STALE, MISS oder REVALIDATED, der zeigt, welcher Weg die Anfrage bedient hat. Zeichnen Sie ihn in Ihren Prüfungen auf.

Nehmen Sie in einen Lasttest auch URLs auf, die nie vorgerendert wurden oder gerade abgelaufen sind, denn bei der Erzeugung auf Abruf steigen die Antwortzeiten. Vergleichen Sie Perzentile für gecachte und ungecachte URLs statt eines gemischten Durchschnitts. Einen solchen Test fahren Sie mit LoadFocus Load Testing, und mit dem Page Speed Monitoring verfolgen Sie die Seitengeschwindigkeit nach Deployments und Inhaltsänderungen nach Zeitplan. Fallstricke bei der Invalidierung beschreibt Cache-Invalidierung und Performance-Tests (Artikel auf Englisch).

Häufige Fragen

Was ist der Unterschied zwischen ISR und SSG?

SSG baut Seiten einmal beim Build. ISR startet mit denselben vorgerenderten Seiten, kann aber jede nach dem Deployment neu erzeugen, per Zeitplan oder auf Abruf. So bauen Sie nie die ganze Website neu, nur um eine Seite zu ändern.

Sieht der erste Besucher alte Inhalte?

Ja. Ist die zeitbasierte Revalidierung abgelaufen, bekommt die nächste Anfrage die veraltete gecachte Seite, während Next.js sie im Hintergrund neu erzeugt. Der Besucher danach erhält die neue Seite.

Kann ich ISR mit statischem Export nutzen?

Nein. Laut Next.js-Dokumentation wird ISR beim Erstellen eines statischen Exports nicht unterstützt und setzt die Node.js-Runtime voraus.

Ist ISR dasselbe wie Cache Components?

Nein, es sind zwei Caching-Modelle. Mit aktiviertem cacheComponents nutzen Sie die Direktive use cache und cacheLife, und ISR bedeutet, für nicht aufgeführte URLs eine App Shell auszuliefern und sie im Hintergrund aufzuwerten. Die routenweite Option revalidate gehört zum Modell ohne Cache Components.

Woran erkenne ich, ob eine Seite aus dem Cache kam?

Prüfen Sie den Antwort-Header x-nextjs-cache. HIT heißt aus dem Cache geliefert, STALE aus dem Cache geliefert und im Hintergrund revalidiert, MISS frisch gerendert, REVALIDATED über bedarfsgesteuerte Revalidierung neu erzeugt.