use cache

Die use cache-Direktive ermöglicht es Ihnen, eine Route, eine React-Komponente oder eine Funktion als zwischengespeichert zu markieren. Sie kann am Anfang einer Datei verwendet werden, um anzugeben, dass alle Exporte in der Datei zwischengespeichert werden sollen, oder inline am Anfang einer Funktion oder Komponente, um den Rückgabewert zwischenzuspeichern.

Verwendung

use cache ist derzeit ein experimentelles Feature. Um es zu aktivieren, fügen Sie die Option useCache zu Ihrer next.config.ts-Datei hinzu:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    useCache: true,
  },
}

export default nextConfig

Gut zu wissen: use cache kann auch mit der Option dynamicIO aktiviert werden.

Fügen Sie dann use cache auf Datei-, Komponenten- oder Funktionsebene hinzu:

// Dateiebene
'use cache'

export default async function Page() {
  // ...
}

// Komponentenebene
export async function MyComponent() {
  'use cache'
  return <></>
}

// Funktionsebene
export async function getData() {
  'use cache'
  const data = await fetch('/api/data')
  return data
}

Wie use cache funktioniert

Cache-Schlüssel

Der Schlüssel eines Cache-Eintrags wird mit einer serialisierten Version seiner Eingaben generiert, die Folgendes umfasst:

• Build-ID (für jeden Build generiert)
• Funktions-ID (eine sichere, eindeutige Kennung für die Funktion)
• Die serialisierbaren Funktionsargumente (oder Props).

Die an die zwischengespeicherte Funktion übergebenen Argumente sowie alle Werte, die sie aus dem übergeordneten Scope liest, werden automatisch Teil des Schlüssels. Das bedeutet, dass derselbe Cache-Eintrag wiederverwendet wird, solange die Eingaben gleich sind.

Nicht-serialisierbare Argumente

Alle nicht-serialisierbaren Argumente, Props oder geschlossenen Werte werden innerhalb der zwischengespeicherten Funktion zu Referenzen und können nur durchgereicht, aber nicht inspiziert oder modifiziert werden. Diese nicht-serialisierbaren Werte werden zur Laufzeit der Anfrage ausgefüllt und werden nicht Teil des Cache-Schlüssels.

Beispielsweise kann eine zwischengespeicherte Funktion JSX als children-Prop entgegennehmen und <div>{children}</div> zurückgeben, aber sie kann das tatsächliche children-Objekt nicht untersuchen. Dies ermöglicht es Ihnen, nicht zwischengespeicherte Inhalte in einer zwischengespeicherten Komponente zu verschachteln.

function CachedComponent({ children }: { children: ReactNode }) {
  'use cache'
  return <div>{children}</div>
}

Rückgabewerte

Der Rückgabewert der zwischengespeicherten Funktion muss serialisierbar sein. Dies stellt sicher, dass die zwischengespeicherten Daten korrekt gespeichert und abgerufen werden können.

use cache zur Build-Zeit

Wenn use cache am Anfang eines Layouts oder einer Seite verwendet wird, wird das Routensegment vorgerendert, sodass es später neu validiert werden kann.

Das bedeutet, dass use cache nicht mit Request-Time-APIs wie cookies oder headers verwendet werden kann.

use cache zur Laufzeit

Auf dem Server werden die Cache-Einträge einzelner Komponenten oder Funktionen im Arbeitsspeicher zwischengespeichert.

Auf dem Client wird jeder vom Server-Cache zurückgegebene Inhalt für die Dauer der Sitzung oder bis zur Neuvalidierung im Browser-Speicher gespeichert.

Während der Neuvalidierung

Standardmäßig hat use cache eine Neuvalidierungsdauer von 15 Minuten auf der Serverseite. Während dieser Zeitraum für Inhalte nützlich sein kann, die keine häufigen Aktualisierungen erfordern, können Sie die cacheLife- und cacheTag-APIs verwenden, um zu konfigurieren, wann einzelne Cache-Einträge neu validiert werden sollten.

• cacheLife: Konfigurieren Sie die Lebensdauer des Cache-Eintrags.
• cacheTag: Erstellen Sie Tags für die bedarfsgesteuerte Neuvalidierung.

Beide APIs integrieren sich in die Client- und Server-Caching-Schichten, was bedeutet, dass Sie Ihre Caching-Semantik an einer Stelle konfigurieren können und sie überall angewendet werden.

Weitere Informationen finden Sie in den API-Dokumentationen zu cacheLife und cacheTag.

Beispiele

Zwischenspeichern einer gesamten Route mit use cache

Um eine gesamte Route vorzurrendern, fügen Sie use cache am Anfang sowohl der layout- als auch der page-Datei hinzu. Jedes dieser Segmente wird als separater Einstiegspunkt in Ihrer Anwendung behandelt und unabhängig zwischengespeichert.

'use cache'

export default function Layout({ children }: { children: ReactNode }) {
  return <div>{children}</div>
}

Alle Komponenten, die in die page-Datei importiert und verschachtelt werden, erben das Cache-Verhalten der page.

'use cache'

async function Users() {
  const users = await fetch('/api/users')
  // Benutzer durchlaufen
}

export default function Page() {
  return (
    <main>
      <Users />
    </main>
  )
}

Gut zu wissen:

• Wenn use cache nur zum layout oder zur page hinzugefügt wird, wird nur dieses Routensegment und alle darin importierten Komponenten zwischengespeichert.
• Wenn eines der verschachtelten Kinder in der Route Dynamische APIs verwendet, wird die Route nicht vorgerendert.

Zwischenspeichern der Ausgabe einer Komponente mit use cache

Sie können use cache auf Komponentenebene verwenden, um Abfragen oder Berechnungen, die innerhalb dieser Komponente durchgeführt werden, zwischenzuspeichern. Der Cache-Eintrag wird wiederverwendet, solange die serialisierten Props in jeder Instanz denselben Wert erzeugen.

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }
  return //...
}

interface BookingsProps {
  type: string
}

Zwischenspeichern der Ausgabe einer Funktion mit use cache

Da Sie use cache zu jeder asynchronen Funktion hinzufügen können, sind Sie nicht auf das Zwischenspeichern von Komponenten oder Routen beschränkt. Sie können beispielsweise eine Netzwerkanfrage, eine Datenbankabfrage oder eine langsame Berechnung zwischenzuspeichern.

export async function getData() {
  'use cache'

  const data = await fetch('/api/data')
  return data
}

Verschachtelung

Wenn Sie nicht-serialisierbare Argumente an eine zwischengespeicherte Funktion übergeben müssen, können Sie sie als children übergeben. Dies bedeutet, dass sich die children-Referenz ändern kann, ohne den Cache-Eintrag zu beeinflussen.

export default async function Page() {
  const uncachedData = await getData()
  return (
    <CacheComponent>
      <DynamicComponent data={uncachedData} />
    </CacheComponent>
  )
}

async function CacheComponent({ children }: { children: ReactNode }) {
  'use cache'
  const cachedData = await fetch('/api/cached-data')
  return (
    <div>
      <PrerenderedComponent data={cachedData} />
      {children}
    </div>
  )
}

Sie können auch Server-Actions durch zwischengespeicherte Komponenten an Client-Komponenten übergeben, ohne sie innerhalb der zwischengespeicherten Funktion aufzurufen.

import ClientComponent from './ClientComponent'

export default async function Page() {
  const performUpdate = async () => {
    'use server'
    // Führen Sie eine serverseitige Aktualisierung durch
    await db.update(...)
  }

  return <CacheComponent performUpdate={performUpdate} />
}

async function CachedComponent({
  performUpdate,
}: {
  performUpdate: () => Promise<void>
}) {
  'use cache'
  // Rufen Sie performUpdate hier nicht auf
  return <ClientComponent action={performUpdate} />
}

Plattformunterstützung

Erfahren Sie, wie Sie Caching konfigurieren, wenn Sie Next.js selbst hosten.

Versionsverlauf