Caching in Next.js

Next.js verbessert die Leistung Ihrer Anwendung und reduziert Kosten durch das Caching von Rendering-Arbeiten und Datenanfragen. Diese Seite bietet einen detaillierten Einblick in die Caching-Mechanismen von Next.js, die APIs zur Konfiguration und ihre Interaktionen.

Gut zu wissen: Diese Seite hilft Ihnen zu verstehen, wie Next.js intern funktioniert, ist aber nicht essenzielles Wissen für produktives Arbeiten mit Next.js. Die meisten Caching-Heuristiken von Next.js werden durch Ihre API-Nutzung bestimmt und haben Standardwerte für beste Leistung ohne oder mit minimaler Konfiguration.

Übersicht

Hier ist eine hochrangige Übersicht der verschiedenen Caching-Mechanismen und ihrer Zwecke:

Standardmäßig cached Next.js so viel wie möglich, um die Leistung zu verbessern und Kosten zu reduzieren. Das bedeutet, Routen werden statisch gerendert und Datenanfragen werden gecached, sofern Sie nicht explizit widersprechen. Das Diagramm unten zeigt das Standard-Caching-Verhalten: wenn eine Route zur Build-Zeit statisch gerendert wird und wenn eine statische Route erstmals besucht wird.

Das Caching-Verhalten ändert sich je nachdem, ob die Route statisch oder dynamisch gerendert wird, Daten gecached oder uncached sind und ob eine Anfrage Teil eines ersten Besuchs oder einer nachfolgenden Navigation ist. Abhängig von Ihrem Anwendungsfall können Sie das Caching-Verhalten für individuelle Routen und Datenanfragen konfigurieren.

Request Memoization

React erweitert die fetch-API, um Anfragen mit derselben URL und denselben Optionen automatisch zu memoizen. Das bedeutet, Sie können eine fetch-Funktion für dieselben Daten an mehreren Stellen im React-Komponentenbaum aufrufen, während sie nur einmal ausgeführt wird.

Zum Beispiel, wenn Sie dieselben Daten in einer Route benötigen (z.B. in einem Layout, einer Page und mehreren Komponenten), müssen Sie die Daten nicht an der Spitze des Baums abfragen und als Props zwischen Komponenten weitergeben. Stattdessen können Sie die Daten in den Komponenten abfragen, die sie benötigen, ohne sich um die Leistungsauswirkungen mehrerer Netzwerkanfragen für dieselben Daten kümmern zu müssen.

async function getItem() {
  // Die `fetch`-Funktion wird automatisch memoized und das Ergebnis
  // wird gecached
  const res = await fetch('https://.../item/1')
  return res.json()
}

// Diese Funktion wird zweimal aufgerufen, aber nur beim ersten Mal ausgeführt
const item = await getItem() // cache MISS

// Der zweite Aufruf könnte überall in Ihrer Route erfolgen
const item = await getItem() // cache HIT

async function getItem() {
  // Die `fetch`-Funktion wird automatisch memoized und das Ergebnis
  // wird gecached
  const res = await fetch('https://.../item/1')
  return res.json()
}

// Diese Funktion wird zweimal aufgerufen, aber nur beim ersten Mal ausgeführt
const item = await getItem() // cache MISS

// Der zweite Aufruf könnte überall in Ihrer Route erfolgen
const item = await getItem() // cache HIT

Wie Request Memoization funktioniert

• Während des Renderings einer Route wird beim ersten Aufruf einer bestimmten Anfrage das Ergebnis nicht im Speicher sein, was zu einem Cache MISS führt.
• Daher wird die Funktion ausgeführt, die Daten von der externen Quelle abgerufen und das Ergebnis im Speicher gespeichert.
• Nachfolgende Funktionsaufrufe derselben Anfrage im selben Render-Pass führen zu einem Cache HIT, und die Daten werden aus dem Speicher zurückgegeben, ohne die Funktion erneut auszuführen.
• Sobald die Route gerendert wurde und der Render-Pass abgeschlossen ist, wird der Speicher "zurückgesetzt" und alle Memoization-Einträge gelöscht.

Gut zu wissen:

• Request Memoization ist ein React-Feature, kein Next.js-Feature. Es wird hier gezeigt, um die Interaktion mit anderen Caching-Mechanismen zu veranschaulichen.
• Memoization gilt nur für die GET-Methode in fetch-Anfragen.
• Memoization gilt nur für den React-Komponentenbaum, das bedeutet:
  • Es gilt für fetch-Anfragen in generateMetadata, generateStaticParams, Layouts, Pages und anderen Server Components.
  • Es gilt nicht für fetch-Anfragen in Route Handlers, da diese nicht Teil des React-Komponentenbaums sind.
• Für Fälle, in denen fetch nicht geeignet ist (z.B. einige Datenbank-Clients, CMS-Clients oder GraphQL-Clients), können Sie die React cache-Funktion verwenden, um Funktionen zu memoizen.

Dauer

Der Cache hält für die Lebensdauer einer Server-Anfrage, bis der React-Komponentenbaum fertig gerendert wurde.

Revalidierung

Da die Memoization nicht über Server-Anfragen hinweg geteilt wird und nur während des Renderings gilt, ist keine Revalidierung notwendig.

Deaktivierung

Memoization gilt standardmäßig nur für die GET-Methode in fetch-Anfragen. Andere Methoden wie POST und DELETE werden nicht memoized. Dieses Standardverhalten ist eine React-Optimierung, und wir empfehlen nicht, es zu deaktivieren.

Für individuelle Anfragen können Sie die signal-Eigenschaft von AbortController verwenden. Dies deaktiviert jedoch nicht die Memoization, sondern bricht laufende Anfragen ab.

const { signal } = new AbortController()
fetch(url, { signal })

Data Cache

Next.js verfügt über einen integrierten Data Cache, der die Ergebnisse von Datenabfragen über eingehende Server-Anfragen und Deployments hinweg persistent speichert. Dies ist möglich, weil Next.js die native fetch-API erweitert, sodass jede Anfrage auf dem Server ihre eigenen persistenten Caching-Semantiken festlegen kann.

Gut zu wissen: Im Browser gibt die cache-Option von fetch an, wie eine Anfrage mit dem HTTP-Cache des Browsers interagiert. In Next.js gibt die cache-Option an, wie eine serverseitige Anfrage mit dem Data Cache des Servers interagiert.

Standardmäßig werden Datenanfragen mit fetch gecached. Sie können die cache- und next.revalidate-Optionen von fetch verwenden, um das Caching-Verhalten zu konfigurieren.

Wie der Data Cache funktioniert

• Beim ersten Aufruf einer fetch-Anfrage während des Renderings prüft Next.js den Data Cache auf eine gecachte Antwort.
• Wenn eine gecachte Antwort gefunden wird, wird sie sofort zurückgegeben und memoized.
• Wenn keine gecachte Antwort gefunden wird, wird die Anfrage an die Datenquelle gesendet, das Ergebnis im Data Cache gespeichert und memoized.
• Für ungecachte Daten (z.B. { cache: 'no-store' }) wird das Ergebnis immer von der Datenquelle abgerufen und memoized.
• Unabhängig davon, ob die Daten gecached oder ungecached sind, werden die Anfragen immer memoized, um doppelte Anfragen für dieselben Daten während eines React-Render-Passes zu vermeiden.

Unterschiede zwischen Data Cache und Request Memoization

Während beide Caching-Mechanismen die Leistung durch Wiederverwendung gecachter Daten verbessern, ist der Data Cache persistent über eingehende Anfragen und Deployments hinweg, während Memoization nur für die Lebensdauer einer Anfrage gilt.

Mit Memoization reduzieren wir die Anzahl der duplizierten Anfragen im selben Render-Pass, die die Netzwerkgrenze vom Rendering-Server zum Data Cache-Server (z.B. ein CDN oder Edge-Netzwerk) oder zur Datenquelle (z.B. eine Datenbank oder CMS) überschreiten müssen. Mit dem Data Cache reduzieren wir die Anzahl der Anfragen an unsere ursprüngliche Datenquelle.

Dauer

Der Data Cache ist persistent über eingehende Anfragen und Deployments hinweg, es sei denn, Sie revalidieren oder deaktivieren ihn.

Revalidierung

Gecachte Daten können auf zwei Arten revalidiert werden:

• Zeitbasierte Revalidierung: Daten nach einer bestimmten Zeit und einer neuen Anfrage revalidieren. Dies ist nützlich für Daten, die sich selten ändern und bei denen Aktualität nicht kritisch ist.
• On-Demand-Revalidierung: Daten basierend auf einem Ereignis revalidieren (z.B. Formularübermittlung). On-Demand-Revalidierung kann einen tag- oder pfadbasierten Ansatz verwenden, um Gruppen von Daten gleichzeitig zu revalidieren. Dies ist nützlich, wenn Sie sicherstellen möchten, dass die neuesten Daten so schnell wie möglich angezeigt werden (z.B. wenn Inhalte aus Ihrem Headless-CMS aktualisiert werden).

Zeitbasierte Revalidierung

Um Daten in regelmäßigen Abständen zu revalidieren, können Sie die next.revalidate-Option von fetch verwenden, um die Cache-Lebensdauer einer Ressource (in Sekunden) festzulegen.

// Höchstens jede Stunde revalidieren
fetch('https://...', { next: { revalidate: 3600 } })

Alternativ können Sie Route Segment Config-Optionen verwenden, um alle fetch-Anfragen in einem Segment zu konfigurieren oder für Fälle, in denen Sie fetch nicht verwenden können.

Wie zeitbasierte Revalidierung funktioniert

• Beim ersten Aufruf einer fetch-Anfrage mit revalidate werden die Daten von der externen Datenquelle abgerufen und im Data Cache gespeichert.
• Alle Anfragen innerhalb des angegebenen Zeitraums (z.B. 60 Sekunden) geben die gecachten Daten zurück.
• Nach dem Zeitraum gibt die nächste Anfrage weiterhin die gecachten (nun veralteten) Daten zurück.
  • Next.js löst eine Hintergrund-Revalidierung der Daten aus.
  • Sobald die Daten erfolgreich abgerufen wurden, aktualisiert Next.js den Data Cache mit den frischen Daten.
  • Wenn die Hintergrund-Revalidierung fehlschlägt, bleiben die vorherigen Daten unverändert.

Dies ähnelt dem stale-while-revalidate-Verhalten.

On-Demand-Revalidierung

Daten können on-demand nach Pfad (revalidatePath) oder Cache-Tag (revalidateTag) revalidiert werden.

Wie On-Demand-Revalidierung funktioniert

• Beim ersten Aufruf einer fetch-Anfrage werden die Daten von der externen Datenquelle abgerufen und im Data Cache gespeichert.
• Wenn eine On-Demand-Revalidierung ausgelöst wird, werden die entsprechenden Cache-Einträge aus dem Cache entfernt.
  • Dies unterscheidet sich von der zeitbasierten Revalidierung, bei der veraltete Daten im Cache bleiben, bis die frischen Daten abgerufen werden.
• Bei der nächsten Anfrage wird es wieder ein Cache MISS sein, und die Daten werden von der externen Datenquelle abgerufen und im Data Cache gespeichert.

Deaktivierung

Für individuelle Datenabfragen können Sie das Caching deaktivieren, indem Sie die cache-Option auf no-store setzen. Das bedeutet, die Daten werden bei jedem fetch-Aufruf abgerufen.

// Caching für eine individuelle `fetch`-Anfrage deaktivieren
fetch(`https://...`, { cache: 'no-store' })

Alternativ können Sie auch die Route Segment Config-Optionen verwenden, um das Caching für ein bestimmtes Routensegment zu deaktivieren. Dies betrifft alle Datenanfragen im Routensegment, einschließlich Drittanbieter-Bibliotheken.

// Caching für alle Datenanfragen im Routensegment deaktivieren
export const dynamic = 'force-dynamic'

Hinweis: Der Data Cache ist derzeit nur in Pages/Routes verfügbar, nicht in Middleware. Alle fetches in Ihrer Middleware sind standardmäßig ungecached.

Vercel Data Cache

Wenn Ihre Next.js-Anwendung auf Vercel deployed ist, empfehlen wir die Dokumentation zum Vercel Data Cache für ein besseres Verständnis der Vercel-spezifischen Features.

Full Route Cache

Verwandte Begriffe:

Sie könnten die Begriffe Automatic Static Optimization, Static Site Generation oder Static Rendering sehen, die synonym verwendet werden, um den Prozess des Renderings und Cachings von Routen Ihrer Anwendung zur Build-Zeit zu beschreiben.

Next.js rendert und cached Routen automatisch zur Build-Zeit. Dies ist eine Optimierung, die es ermöglicht, die gecachte Route statt sie bei jeder Anfrage auf dem Server zu rendern, was zu schnelleren Seitenladungen führt.

Um zu verstehen, wie der Full Route Cache funktioniert, ist es hilfreich zu betrachten, wie React mit Rendering umgeht und wie Next.js das Ergebnis cached:

1. React-Rendering auf dem Server

Auf dem Server verwendet Next.js React-APIs, um das Rendering zu orchestrieren. Die Rendering-Arbeit wird in Chunks aufgeteilt: nach individuellen Routensegmenten und Suspense-Grenzen.

Jeder Chunk wird in zwei Schritten gerendert:

1. React rendert Server Components in ein spezielles Datenformat, optimiert für Streaming, genannt React Server Component Payload.
2. Next.js verwendet den React Server Component Payload und Client Component JavaScript-Anweisungen, um HTML auf dem Server zu rendern.

Das bedeutet, wir müssen nicht warten, bis alles gerendert ist, bevor wir die Arbeit cachen oder eine Antwort senden. Stattdessen können wir eine Antwort streamen, während die Arbeit abgeschlossen wird.

Was ist der React Server Component Payload?

Der React Server Component Payload ist eine kompakte binäre Darstellung des gerenderten React Server Components-Baums. Er wird von React auf dem Client verwendet, um den DOM des Browsers zu aktualisieren. Der React Server Component Payload enthält:

• Das gerenderte Ergebnis von Server Components
• Platzhalter für Client Components und Referenzen zu ihren JavaScript-Dateien
• Alle Props, die von einer Server Component an eine Client Component übergeben werden

Weitere Informationen finden Sie in der Server Components-Dokumentation.

2. Next.js-Caching auf dem Server (Full Route Cache)

Das Standardverhalten von Next.js ist, das gerenderte Ergebnis (React Server Component Payload und HTML) einer Route auf dem Server zu cachen. Dies gilt für statisch gerenderte Routen zur Build-Zeit oder während der Revalidierung.

3. React Hydration und Reconciliation auf dem Client

Zur Laufzeit der Anfrage auf dem Client:

1. Das HTML wird verwendet, um sofort eine schnelle, nicht-interaktive Vorschau der Client- und Server-Komponenten anzuzeigen.
2. Das React Server Components Payload wird verwendet, um die Client- und gerenderten Server-Komponenten-Bäume abzugleichen und das DOM zu aktualisieren.
3. Die JavaScript-Anweisungen werden verwendet, um Client-Komponenten zu hydratisieren und die Anwendung interaktiv zu machen.

4. Next.js Caching auf dem Client (Router Cache)

Das React Server Component Payload wird im clientseitigen Router Cache gespeichert - einem separaten In-Memory-Cache, der nach einzelnen Routensegmenten aufgeteilt ist. Dieser Router Cache wird verwendet, um das Navigationserlebnis zu verbessern, indem zuvor besuchte Routen gespeichert und zukünftige Routen vorab geladen werden.

5. Nachfolgende Navigationen

Bei nachfolgenden Navigationen oder während des Prefetching prüft Next.js, ob das React Server Components Payload im Router Cache gespeichert ist. Falls ja, wird eine neue Anfrage an den Server übersprungen.

Wenn die Routensegmente nicht im Cache sind, holt Next.js das React Server Components Payload vom Server und füllt den Router Cache auf dem Client.

Statisches und dynamisches Rendering

Ob eine Route zur Build-Zeit gecached wird oder nicht, hängt davon ab, ob sie statisch oder dynamisch gerendert wird. Statische Routen werden standardmäßig gecached, während dynamische Routen zur Laufzeit der Anfrage gerendert und nicht gecached werden.

Dieses Diagramm zeigt den Unterschied zwischen statisch und dynamisch gerenderten Routen mit gecachten und nicht gecachten Daten:

Erfahren Sie mehr über statisches und dynamisches Rendering.

Dauer

Standardmäßig ist der Full Route Cache persistent. Das bedeutet, dass das Render-Ergebnis über Benutzeranfragen hinweg gecached wird.

Invalidierung

Es gibt zwei Möglichkeiten, den Full Route Cache zu invalidieren:

• Daten-Revalidierung: Die Revalidierung des Data Cache invalidiert wiederum den Router Cache, indem Komponenten auf dem Server neu gerendert und das neue Render-Ergebnis gecached wird.
• Neue Bereitstellung: Im Gegensatz zum Data Cache, der über Bereitstellungen hinweg bestehen bleibt, wird der Full Route Cache bei neuen Bereitstellungen gelöscht.

Opt-out

Sie können den Full Route Cache deaktivieren, also Komponenten für jede eingehende Anfrage dynamisch rendern, indem Sie:

• Eine dynamische Funktion verwenden: Dies deaktiviert die Route für den Full Route Cache und rendert sie dynamisch zur Laufzeit der Anfrage. Der Data Cache kann weiterhin verwendet werden.
• Die Route-Segment-Konfigurationsoptionen dynamic = 'force-dynamic' oder revalidate = 0 verwenden: Dies überspringt den Full Route Cache und den Data Cache. Das bedeutet, Komponenten werden für jede eingehende Serveranfrage gerendert und Daten abgerufen. Der Router Cache gilt weiterhin, da es sich um einen clientseitigen Cache handelt.
• Den Data Cache deaktivieren: Wenn eine Route einen fetch-Request hat, der nicht gecached wird, deaktiviert dies die Route für den Full Route Cache. Die Daten für den spezifischen fetch-Request werden für jede eingehende Anfrage abgerufen. Andere fetch-Requests, die das Caching nicht deaktivieren, werden weiterhin im Data Cache gecached. Dies ermöglicht eine Mischung aus gecachten und nicht gecachten Daten.

Router Cache

Verwandte Begriffe:

Der Router Cache wird möglicherweise als Client-seitiger Cache oder Prefetch Cache bezeichnet. Während Prefetch Cache sich auf die vorab geladenen Routensegmente bezieht, bezieht sich Client-seitiger Cache auf den gesamten Router Cache, der sowohl besuchte als auch vorab geladene Segmente enthält. Dieser Cache gilt speziell für Next.js und Server-Komponenten und unterscheidet sich vom bfcache des Browsers, obwohl er ein ähnliches Ergebnis hat.

Next.js hat einen clientseitigen In-Memory-Cache, der das React Server Component Payload für die Dauer einer Benutzersitzung speichert, aufgeteilt nach einzelnen Routensegmenten. Dies wird als Router Cache bezeichnet.

Wie der Router Cache funktioniert

Wenn ein Benutzer zwischen Routen navigiert, cached Next.js besuchte Routensegmente und lädt Routen vorab, zu denen der Benutzer wahrscheinlich navigieren wird (basierend auf <Link>-Komponenten in seinem Viewport).

Dies führt zu einem verbesserten Navigationserlebnis für den Benutzer:

• Sofortige Vorwärts-/Rückwärtsnavigation, weil besuchte Routen gecached sind, und schnelle Navigation zu neuen Routen aufgrund von Prefetching und partiellem Rendering.
• Kein vollständiger Seitenneuladung zwischen Navigationen, und React-Status und Browser-Status bleiben erhalten.

Unterschied zwischen Router Cache und Full Route Cache:

Der Router Cache speichert das React Server Component Payload temporär im Browser für die Dauer einer Benutzersitzung, während der Full Route Cache das React Server Component Payload und HTML persistent auf dem Server über mehrere Benutzeranfragen hinweg speichert.

Während der Full Route Cache nur statisch gerenderte Routen cached, gilt der Router Cache für sowohl statisch als auch dynamisch gerenderte Routen.

Dauer

Der Cache wird im temporären Speicher des Browsers gespeichert. Zwei Faktoren bestimmen, wie lange der Router Cache bestehen bleibt:

• Sitzung: Der Cache bleibt über Navigationen hinweg bestehen. Er wird jedoch bei einem Seitenrefresh gelöscht.
• Automatischer Invalidierungszeitraum: Der Cache von Layouts und Ladezuständen wird automatisch nach einem bestimmten Zeitraum invalidiert. Die Dauer hängt davon ab, wie die Ressource vorab geladen wurde und ob die Ressource statisch generiert wurde:
  • Standard-Prefetching (prefetch={null} oder nicht angegeben): nicht gecached für dynamische Seiten, 5 Minuten für statische Seiten.
  • Vollständiges Prefetching (prefetch={true} oder router.prefetch): 5 Minuten für sowohl statische als auch dynamische Seiten.

Während ein Seitenrefresh alle gecachten Segmente löscht, betrifft der automatische Invalidierungszeitraum nur das einzelne Segment ab dem Zeitpunkt, zu dem es vorab geladen wurde.

Gut zu wissen: Die experimentelle staleTimes-Konfigurationsoption kann verwendet werden, um die oben genannten automatischen Invalidierungszeiten anzupassen.

Invalidierung

Es gibt zwei Möglichkeiten, den Router Cache zu invalidieren:

• In einer Server-Aktion:
  • Daten-On-Demand-Revalidierung nach Pfad mit (revalidatePath) oder nach Cache-Tag mit (revalidateTag)
  • Die Verwendung von cookies.set oder cookies.delete invalidiert den Router Cache, um zu verhindern, dass Routen, die Cookies verwenden, veraltet werden (z.B. Authentifizierung).
• Der Aufruf von router.refresh invalidiert den Router Cache und stellt eine neue Anfrage an den Server für die aktuelle Route.

Opt-out

Es ist nicht möglich, den Router Cache zu deaktivieren. Sie können ihn jedoch durch Aufruf von router.refresh, revalidatePath oder revalidateTag invalidieren (siehe oben). Dadurch wird der Cache gelöscht und eine neue Anfrage an den Server gestellt, um sicherzustellen, dass die neuesten Daten angezeigt werden.

Sie können auch das Prefetching deaktivieren, indem Sie die prefetch-Prop der <Link>-Komponente auf false setzen. Dadurch werden die Routensegmente jedoch weiterhin für 30 Sekunden temporär gespeichert, um eine sofortige Navigation zwischen verschachtelten Segmenten, wie Tab-Leisten, oder Vor- und Zurück-Navigation zu ermöglichen. Besuchte Routen werden weiterhin gecached.

Cache-Interaktionen

Bei der Konfiguration der verschiedenen Caching-Mechanismen ist es wichtig zu verstehen, wie sie miteinander interagieren:

Data Cache und Full Route Cache

• Die Revalidierung oder Deaktivierung des Data Cache wird den Full Route Cache invalidieren, da das Render-Ergebnis von den Daten abhängt.
• Die Invalidierung oder Deaktivierung des Full Route Cache betrifft nicht den Data Cache. Sie können eine Route dynamisch rendern, die sowohl gecachte als auch nicht gecachte Daten enthält. Dies ist nützlich, wenn der größte Teil Ihrer Seite gecachte Daten verwendet, Sie jedoch einige Komponenten haben, die auf Daten angewiesen sind, die zur Laufzeit der Anfrage abgerufen werden müssen. Sie können dynamisch rendern, ohne sich Gedanken über die Leistungsauswirkungen des erneuten Abrufs aller Daten machen zu müssen.

Data Cache und Client-seitiger Router Cache

• Die Revalidierung des Data Cache in einem Route Handler wird den Router Cache nicht sofort invalidieren, da der Route Handler nicht an eine bestimmte Route gebunden ist. Das bedeutet, der Router Cache wird weiterhin das vorherige Payload bereitstellen, bis ein Hard Refresh durchgeführt wird oder der automatische Invalidierungszeitraum abgelaufen ist.
• Um den Data Cache und Router Cache sofort zu invalidieren, können Sie revalidatePath oder revalidateTag in einer Server-Aktion verwenden.

APIs

Die folgende Tabelle gibt einen Überblick darüber, wie verschiedene Next.js-APIs das Caching beeinflussen:

<Link>

Standardmäßig lädt die <Link>-Komponente Routen automatisch aus dem Full Route Cache vor und fügt das React Server Component Payload dem Router Cache hinzu.

Um das Prefetching zu deaktivieren, können Sie die prefetch-Prop auf false setzen. Dies überspringt den Cache jedoch nicht dauerhaft, das Routensegment wird weiterhin clientseitig gecached, wenn der Benutzer die Route besucht.

Erfahren Sie mehr über die <Link>-Komponente.

router.prefetch

Die prefetch-Option des useRouter-Hooks kann verwendet werden, um manuell eine Route vorab zu laden. Dies fügt das React Server Component Payload dem Router Cache hinzu.

Siehe die useRouter-Hook-API-Referenz.

router.refresh

Die refresh-Option des useRouter-Hooks kann verwendet werden, um manuell eine Route zu aktualisieren. Dies löscht den Router Cache vollständig und stellt eine neue Anfrage an den Server für die aktuelle Route. refresh betrifft nicht den Data oder Full Route Cache.

Das gerenderte Ergebnis wird auf dem Client abgeglichen, während der React-Status und Browser-Status erhalten bleiben.

Siehe die useRouter-Hook-API-Referenz.

fetch

Daten, die von fetch zurückgegeben werden, werden automatisch im Data Cache gecached.

// Standardmäßig gecached. `force-cache` ist die Standardoption und kann weggelassen werden.
fetch(`https://...`, { cache: 'force-cache' })

Siehe die fetch-API-Referenz für weitere Optionen.

fetch options.cache

Sie können einzelne fetch-Requests vom Data Caching ausschließen, indem Sie die cache-Option auf no-store setzen:

// Caching deaktivieren
fetch(`https://...`, { cache: 'no-store' })

Da das Render-Ergebnis von den Daten abhängt, wird durch cache: 'no-store' auch der Full Route Cache für die Route deaktiviert, in der der fetch-Request verwendet wird. Das heißt, die Route wird bei jeder Anfrage dynamisch gerendert, aber Sie können weiterhin andere gecachte Datenanfragen in derselben Route haben.

Siehe die fetch-API-Referenz für weitere Optionen.

fetch options.next.revalidate

Sie können die next.revalidate-Option von fetch verwenden, um den Revalidierungszeitraum (in Sekunden) eines einzelnen fetch-Requests festzulegen. Dies revalidiert den Data Cache, was wiederum den Full Route Cache revalidiert. Frische Daten werden abgerufen und Komponenten auf dem Server neu gerendert.

// Höchstens nach 1 Stunde revalidieren
fetch(`https://...`, { next: { revalidate: 3600 } })

Siehe die fetch-API-Referenz für weitere Optionen.

fetch options.next.tags und revalidateTag

Next.js verfügt über ein Cache-Tagging-System für präzises Daten-Caching und Revalidierung.

1. Bei der Verwendung von fetch oder unstable_cache können Sie Cache-Einträge mit einem oder mehreren Tags versehen.
2. Anschließend können Sie revalidateTag aufrufen, um die mit diesem Tag verknüpften Cache-Einträge zu löschen.

Beispielsweise können Sie beim Abrufen von Daten ein Tag setzen:

// Daten mit einem Tag cachen
fetch(`https://...`, { next: { tags: ['a', 'b', 'c'] } })

Dann rufen Sie revalidateTag mit einem Tag auf, um den Cache-Eintrag zu löschen:

// Einträge mit einem bestimmten Tag revalidieren
revalidateTag('a')

Es gibt zwei Orte, an denen Sie revalidateTag verwenden können, abhängig von Ihrem Ziel:

1. Route Handler - um Daten als Reaktion auf ein externes Ereignis (z.B. Webhook) zu revalidieren. Dies wird den Router Cache nicht sofort ungültig machen, da der Route Handler nicht an eine bestimmte Route gebunden ist.
2. Server Actions - um Daten nach einer Benutzeraktion (z.B. Formularübermittlung) zu revalidieren. Dies wird den Router Cache für die zugehörige Route ungültig machen.

revalidatePath

revalidatePath ermöglicht es Ihnen, Daten manuell zu revalidieren und die Routen-Segmente unter einem bestimmten Pfad in einem einzigen Vorgang neu zu rendern. Der Aufruf der revalidatePath-Methode revalidiert den Data Cache, was wiederum den Full Route Cache ungültig macht.

revalidatePath('/')

Es gibt zwei Orte, an denen Sie revalidatePath verwenden können, abhängig von Ihrem Ziel:

1. Route Handler - um Daten als Reaktion auf ein externes Ereignis (z.B. Webhook) zu revalidieren.
2. Server Actions - um Daten nach einer Benutzerinteraktion (z.B. Formularübermittlung, Klicken eines Buttons) zu revalidieren.

Weitere Informationen finden Sie in der revalidatePath API-Referenz.

revalidatePath vs. router.refresh:

Der Aufruf von router.refresh löscht den Router Cache und rendert die Routen-Segmente auf dem Server neu, ohne den Data Cache oder den Full Route Cache ungültig zu machen.

Der Unterschied besteht darin, dass revalidatePath den Data Cache und Full Route Cache löscht, während router.refresh() den Data Cache und Full Route Cache nicht verändert, da es sich um eine Client-seitige API handelt.

Dynamische Funktionen

Dynamische Funktionen wie cookies und headers sowie die searchParams-Prop in Pages hängen von Laufzeitinformationen der eingehenden Anfrage ab. Ihre Verwendung führt dazu, dass eine Route aus dem Full Route Cache ausgeschlossen wird, mit anderen Worten, die Route wird dynamisch gerendert.

cookies

Die Verwendung von cookies.set oder cookies.delete in einer Server Action macht den Router Cache ungültig, um zu verhindern, dass Routen, die Cookies verwenden, veraltet werden (z.B. um Authentifizierungsänderungen widerzuspiegeln).

Weitere Informationen finden Sie in der cookies API-Referenz.

Segment-Konfigurationsoptionen

Die Route Segment Config-Optionen können verwendet werden, um die Standardwerte des Routen-Segments zu überschreiben oder wenn Sie die fetch-API nicht verwenden können (z.B. Datenbank-Client oder Bibliotheken von Drittanbietern).

Die folgenden Route Segment Config-Optionen schließen den Data Cache und Full Route Cache aus:

• const dynamic = 'force-dynamic'
• const revalidate = 0

Weitere Optionen finden Sie in der Route Segment Config-Dokumentation.

generateStaticParams

Für dynamische Segmente (z.B. app/blog/[slug]/page.js) werden Pfade, die von generateStaticParams bereitgestellt werden, zur Build-Zeit im Full Route Cache gespeichert. Zur Laufzeit werden auch Pfade, die zur Build-Zeit nicht bekannt waren, beim ersten Aufruf im Cache gespeichert.

Sie können das Caching zur Laufzeit deaktivieren, indem Sie die Option export const dynamicParams = false in einem Routen-Segment verwenden. Wenn diese Konfigurationsoption verwendet wird, werden nur die von generateStaticParams bereitgestellten Pfade bedient, andere Routen führen zu einem 404-Fehler oder werden gematcht (im Fall von Catch-all-Routen).

Weitere Informationen finden Sie in der generateStaticParams API-Referenz.

React cache-Funktion

Die React cache-Funktion ermöglicht es Ihnen, den Rückgabewert einer Funktion zu memoisieren, sodass Sie dieselbe Funktion mehrfach aufrufen können, während sie nur einmal ausgeführt wird.

Da fetch-Anfragen automatisch memoisiert werden, müssen Sie sie nicht in React cache einwickeln. Sie können jedoch cache verwenden, um Datenanfragen manuell zu memoisieren, wenn die fetch-API nicht geeignet ist. Zum Beispiel bei einigen Datenbank-Clients, CMS-Clients oder GraphQL-Clients.

import { cache } from 'react'
import db from '@/lib/db'

export const getItem = cache(async (id: string) => {
  const item = await db.item.findUnique({ id })
  return item
})

import { cache } from 'react'
import db from '@/lib/db'

export const getItem = cache(async (id) => {
  const item = await db.item.findUnique({ id })
  return item
})