use cache in Next.js 16: Caching auf dem Server mit Cache Components

Caching auf dem Server war in Next.js lange ein zersplittertes Thema: ein eigenes Verhalten für fetch-Aufrufe, eine eigene API für unstable_cache und React.cache für Wiederholungen innerhalb derselben Anfrage. use cache ersetzt diese drei durch eine einzige Direktive – du cachst die Ausgabe einer Funktion, einer Komponente oder einer ganzen Datei, und den Key erzeugt Next.js selbst.

Zuerst: Ohne Aktivierung läuft nichts

Das ist der am häufigsten übersehene Schritt. use cache zu schreiben reicht nicht, du musst die Funktion Cache Components aktivieren:

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
	cacheComponents: true,
};
 
export default nextConfig;

Wenn du die Direktive ohne diese Option schreibst, wird nichts gecacht und alles läuft stillschweigend einfach weiter – du bekommst auch keinen Fehler. Das ist das, was bei der Suche nach der Ursache für Langsamkeit am meisten Zeit kostet.

Wo schreibt man sie hin?

Es gibt drei Stellen, und an allen dreien muss die Funktion async sein:

// 1. Fonksiyon seviyesi
export async function getData() {
	"use cache";
	const res = await fetch("https://api.example.com/data");
	return res.json();
}
 
// 2. Bileşen seviyesi — prop'lar önbellek anahtarına girer
export async function Bookings({ type = "haircut" }: { type: string }) {
	"use cache";
	const res = await fetch(`https://api.example.com/bookings?type=${type}`);
	return <List items={await res.json()} />;
}

// 3. Dosya seviyesi — dosyadaki her export önbelleğe alınır
"use cache";
 
export async function getMonthlyTotals(accountId: string) {
	return db.orders.aggregate({ where: { accountId }, _sum: { amount: true } });
}
 
export async function getTopProducts() {
	return db.products.findMany({ orderBy: { sales: "desc" }, take: 10 });
}

Wenn du sie auf Dateiebene verwendest, fällt jeder Export darunter, einschließlich generateMetadata und generateStaticParams; alle müssen async sein. Wenn du ein Route-Segment komplett vorab generieren willst, musst du die Direktive an den Anfang jeder Datei setzen, die diese Route bildet (page, layout, Slots paralleler Routen) – jedes Segment ist ein eigener Cache-Eintrag.

Wie wird der Cache-Key erzeugt?

Der Key besteht aus vier Teilen:

1. Build-ID – ändert sich bei jedem Build, also macht jedes Deployment den gesamten Cache ungültig
2. Funktionsidentität – die Position der Funktion im Code und ein sicherer Hash ihrer Signatur
3. Serialisierbare Argumente – bei Komponenten die Props, bei Funktionen die Parameter
4. HMR-Hash – nur in der Entwicklung, verwirft den Cache bei Hot Reload

Die eigentliche Feinheit liegt nicht im vierten Punkt, sondern bei den Argumenten: Variablen, die du aus dem äußeren Scope verwendest, werden automatisch ebenfalls als Argumente gezählt und gehen in den Key ein.

async function Component({ userId }: { userId: string }) {
	const getData = async (filter: string) => {
		"use cache";
		// Anahtar hem userId'yi (kapanıştan) hem filter'ı (argümandan) içerir
		const res = await fetch(
			`https://api.example.com/users/${userId}/data?filter=${filter}`
		);
		return res.json();
	};
 
	return getData("active");
}

Wie lange bleibt es frisch: cacheLife

Wenn du cacheLife nicht aufrufst, gilt das Profil default:

• stale: 5 Minuten (clientseitig)
• revalidate: 15 Minuten (serverseitig)
• expire: läuft zeitlich nie ab

import { cacheLife } from "next/cache";
 
export async function getOrderSummary(accountId: string) {
	"use cache";
	cacheLife("hours");
 
	const orders = await getOrders(accountId);
	return { orders };
}

Eine Warnung: Wenn du in ein use cache ohne angegebenes cacheLife ein weiteres, kurzlebiges use cache setzt, schlägt der Build mit einem Fehler fehl. Bei verschachtelten Caches musst du die Lebensdauern bewusst wählen.

Taggen und manuell leeren: cacheTag

Zeitbasierte Aktualisierung ist nicht immer die richtige Antwort. Wenn du den Cache sofort leeren willst, sobald sich der Inhalt ändert, nutze Tags:

// lib/products.ts
import { cacheTag } from "next/cache";
 
export async function getProducts() {
	"use cache";
	cacheTag("products");
	const res = await fetch("https://api.example.com/products");
	return res.json();
}

// app/actions.ts
"use server";
 
import { updateTag } from "next/cache";
 
export async function updateProduct() {
	await db.products.update(/* ... */);
	updateTag("products"); // "products" etiketli tüm girdiler düşer
}

In der Praxis nutzt man beides zusammen: Ein selten geänderter Blogbeitrag bekommt ein langes cacheLife plus cacheTag und wird nur beim Speichern geleert; eine Liste, die sich im Tagesverlauf ständig ändert, aktualisiert sich dagegen mit einem kurzen Profil von selbst.

Die häufigste Stolperfalle: cookies() funktioniert darin nicht

In einem gecachten Scope sind cookies(), headers() und searchParams nicht verwendbar. Die Einschränkung folgt außerdem dem Call Stack: Wenn eine Hilfsfunktion, die du von innen aufrufst, eines davon liest, knallt es auch dort (next-request-in-use-cache).

Das richtige Muster: Lies die Request-Daten außerhalb des Cache-Scopes und gib sie als Argument hinein.

// YANLIŞ — çalışma anında patlar
async function getCart() {
	"use cache";
	const store = await cookies();
	return db.cart.find({ id: store.get("cart")?.value });
}
 
// DOĞRU — okuma dışarıda, argüman içeride
export default async function Page() {
	const store = await cookies();
	const cartId = store.get("cart")?.value;
	return <Cart cartId={cartId} />;
}
 
async function Cart({ cartId }: { cartId?: string }) {
	"use cache";
	return <CartView data={await db.cart.find({ id: cartId })} />;
}

Für Fälle, in denen es wirklich unvermeidbar ist, gibt es use cache: private, aber die Dokumentation kennzeichnet es als „sehr selten" – gedacht für Compliance-Vorgaben oder wenn du den Code nicht umstrukturieren kannst.

Grenzen der Serialisierung

Argumente und Rückgabewerte müssen serialisierbar sein.

Gültig: primitive Typen, einfache Objekte, Arrays, Date, Map, Set, TypedArray, ArrayBuffer. Der Rückgabewert darf außerdem JSX sein.

Ungültig: Klasseninstanzen, Funktionen, Symbol, WeakMap/WeakSet und – leicht zu vergessen – URL-Instanzen.

Der rettende Detailpunkt: Du kannst einen Wert durchreichen und verwenden, ohne hineinzuschauen. So funktionieren children und Server Actions.

async function CachedWrapper({ children }: { children: ReactNode }) {
	"use cache";
	// children okunmuyor, sadece geçiriliyor — anahtarı etkilemiyor
	return (
		<div className="wrapper">
			<header>Önbelleğe alınmış başlık</header>
			{children}
		</div>
	);
}
 
export default function Page() {
	return (
		<CachedWrapper>
			<DynamicComponent /> {/* önbelleğe alınmıyor */}
		</CachedWrapper>
	);
}

Wo wird es gespeichert? Die Hosting-Art ändert das Ergebnis

Der Standard-Handler ist ein In-Memory-LRU. Das verhält sich je nachdem, wo du deployst, ganz unterschiedlich:

Außerdem wird keine Cache-Direktive in ein neues Deployment übernommen, weil der Key die Build-ID enthält. Für Daten, die über Deployments hinweg erhalten bleiben sollen, brauchst du weiterhin unstable_cache oder den fetch-Cache. use cache ersetzt nicht alles.

Wenn der Build nach 50 Sekunden hängt

Wenn du diesen Fehler siehst, ist die Ursache fast immer dieselbe:

Filling a cache during prerender timed out, likely because request-specific arguments such as params, searchParams, cookies() or uncached data were used inside "use cache".

Der gecachte Scope wartet auf ein Promise, das sich beim Build nicht auflösen lässt. Typisch sind drei Wege: ein solches Promise als Prop übergeben, über eine Closure darauf zugreifen oder es über eine geteilte Map beziehen. Die Lösung ist immer dieselbe: den Wert außerhalb mit await auflösen und einfache Daten hineingeben.

cookies() direkt im Inneren aufzurufen führt dagegen nicht zu einem Timeout, sondern sofort zu einem Fehler – verwechsle die beiden nicht.

Zwei weitere Verhaltensweisen, die du kennen solltest

Bei aktivem Draft Mode werden alle gecachten Funktionen bei jeder Anfrage neu ausgeführt und das Ergebnis wird nicht gespeichert. In der Vorschau besteht kein Risiko, veraltete Inhalte zu sehen; dafür musst du keinen zusätzlichen Code schreiben.

React.cache ist isoliert. Ein Wert, den du außerhalb der use cache-Grenze mit React.cache speicherst, ist von innen nicht sichtbar. Der einzige Weg, Daten hineinzubringen, ist ein Argument.

Wann du es nicht verwenden solltest

• Beim statischen Export (output: "export") wird es nicht unterstützt. Ein Node.js-Server und Docker werden unterstützt.
• Bei nutzerspezifischen Daten, die sich bei jeder Anfrage ändern – du müsstest sie aus dem Scope herausholen und als Argument übergeben, was den Cache meist sinnlos macht.
• Bei teuren Berechnungen, die über Deployments hinweg leben sollen; der Build-ID-Key setzt sie zurück.
• Wenn die Aktualität der Daten auf die Sekunde ankommt: Der Client-Router erzwingt eine Stale-Zeit von mindestens 30 Sekunden, unabhängig von der Konfiguration.

Debugging

NEXT_PRIVATE_DEBUG_CACHE=1 npm run dev
# ya da üretim için
NEXT_PRIVATE_DEBUG_CACHE=1 npm run start

Zusammenfassung

In der ersten Fassung dieses Beitrags gab es einen Abschnitt „Performance-Test“ mit Zahlen wie 78 % Beschleunigung. Ich habe ihn entfernt, weil diese Zahlen nicht aus einer echten Messung stammten, sondern aus einem erfundenen setTimeout-Aufbau und dir nichts nützten, um den Gewinn in deinem Projekt abzuschätzen. Der Gewinn hängt ganz davon ab, was du cachst: Eine Datenbankabfrage, die 200 ms dauert, zu cachen ist nicht dasselbe wie eine Berechnung, die 2 ms dauert. Miss selbst mit NEXT_PRIVATE_DEBUG_CACHE=1.