Was macht Cache-Komponenten (Next.js 16+)?
Cache-Komponenten ermöglichen Partial Prerendering (PPR) – statische, gecachte und dynamische Inhalte in einer einzigen Route.
Cache-Komponenten aktivieren
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
Dies ersetzt das alte experimental.ppr-Flag.
Drei Inhaltstypen
Mit aktivierten Cache-Komponenten fallen Inhalte in drei Kategorien:
1. Statisch (automatisch vorgerendert)
Synchroner Code, Importe, reine Berechnungen – werden zur Build-Zeit vorgerendert:
export default function Page() {
return (
<header>
<h1>Unser Blog</h1> {/* Statisch - sofort */}
<nav>...</nav>
</header>
)
}
2. Gecacht (use cache)
Asynchrone Daten, die nicht bei jeder Anfrage neu geladen werden müssen:
async function BlogPosts() {
'use cache'
cacheLife('hours')
const posts = await db.posts.findMany()
return <PostList posts={posts} />
}
3. Dynamisch (Suspense)
Laufzeitdaten, die aktuell sein müssen – in Suspense einwickeln:
import { Suspense } from 'react'
export default function Page() {
return (
<>
<BlogPosts /> {/* Gecacht */}
<Suspense fallback={<p>Lade...</p>}>
<UserPreferences /> {/* Dynamisch - streamt ein */}
</Suspense>
</>
)
}
async function UserPreferences() {
const theme = (await cookies()).get('theme')?.value
return <p>Theme: {theme}</p>
}
use cache-Direktiv
Dateiebene
'use cache'
export default async function Page() {
// Ganze Seite wird gecacht
const data = await fetchData()
return <div>{data}</div>
}
Komponentenebene
export async function CachedComponent() {
'use cache'
const data = await fetchData()
return <div>{data}</div>
}
Funktionsebene
export async function getData() {
'use cache'
return db.query('SELECT * FROM posts')
}
Cache-Profile
Integrierte Profile
'use cache' // Standard: 5 Min veraltet, 15 Min Neuvalidierung
'use cache: remote' // Plattform-eigener Cache (Redis, KV)
'use cache: private' // Für Compliance, erlaubt Laufzeit-APIs
cacheLife() - Benutzerdefinierte Lebensdauer
import { cacheLife } from 'next/cache'
async function getData() {
'use cache'
cacheLife('hours') // Integriertes Profil
return fetch('/api/data')
}
Integrierte Profile: 'default', 'minutes', 'hours', 'days', 'weeks', 'max'
Inline-Konfiguration
async function getData() {
'use cache'
cacheLife({
stale: 3600, // 1 Stunde – veraltet bedienen während Neuvalidierung
revalidate: 7200, // 2 Stunden – Hintergrund-Neuvalidierungsintervall
expire: 86400, // 1 Tag – harte Ablaufzeit
})
return fetch('/api/data')
}
Cache-Invalidierung
cacheTag() - Gecachten Inhalt markieren
import { cacheTag } from 'next/cache'
async function getProducts() {
'use cache'
cacheTag('products')
return db.products.findMany()
}
async function getProduct(id: string) {
'use cache'
cacheTag('products', `product-${id}`)
return db.products.findUnique({ where: { id } })
}
updateTag() - Sofortige Invalidierung
Verwenden, wenn der Cache innerhalb derselben Anfrage aktualisiert werden muss:
'use server'
import { updateTag } from 'next/cache'
export async function updateProduct(id: string, data: FormData) {
await db.products.update({ where: { id }, data })
updateTag(`product-${id}`) // Sofortige Aktualisierung – dieselbe Anfrage sieht neue Daten
}
revalidateTag() - Hintergrund-Neuvalidierung
Verwenden für das stale-while-revalidate-Verhalten:
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost(data: FormData) {
await db.posts.create({ data })
revalidateTag('posts') // Hintergrund – nächste Anfrage sieht neue Daten
}
Einschränkung bei Laufzeitdaten
Innerhalb von use cache darf nicht auf cookies(), headers() oder searchParams zugegriffen werden.
Lösung: Als Argumente übergeben
// Falsch – Laufzeit-API innerhalb von use cache
async function CachedProfile() {
'use cache'
const session = (await cookies()).get('session')?.value // Fehler!
return <div>{session}</div>
}
// Richtig – außerhalb extrahieren, als Argument übergeben
async function ProfilePage() {
const session = (await cookies()).get('session')?.value
return <CachedProfile sessionId={session} />
}
async function CachedProfile({ sessionId }: { sessionId: string }) {
'use cache'
// sessionId wird automatisch Teil des Cache-Schlüssels
const data = await fetchUserData(sessionId)
return <div>{data.name}</div>
}
Ausnahme: use cache: private
Für Compliance-Anforderungen, wenn ein Refactoring nicht möglich ist:
async function getData() {
'use cache: private'
const session = (await cookies()).get('session')?.value // Erlaubt
return fetchData(session)
}
Cache-Schlüsselgenerierung
Cache-Schlüssel werden automatisch basierend auf folgenden Faktoren erstellt:
- Build-ID – macht alle Caches bei einem Deployment ungültig
- Funktions-ID – Hash des Funktionsspeicherorts
- Serialisierbare Argumente – Props werden Teil des Schlüssels
- Closure-Variablen – Werte aus dem äußeren Gültigkeitsbereich werden einbezogen
async function Component({ userId }: { userId: string }) {
const getData = async (filter: string) => {
'use cache'
// Cache-Schlüssel = userId (Closure) + filter (Argument)
return fetch(`/api/users/${userId}?filter=${filter}`)
}
return getData('active')
}
Vollständiges Beispiel
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
export default function DashboardPage() {
return (
<>
{/* Statisches Grundgerüst – sofort vom CDN */}
<header><h1>Dashboard</h1></header>
<nav>...</nav>
{/* Gecacht – schnell, stündlich neu validiert */}
<Stats />
{/* Dynamisch – streamt mit aktuellen Daten ein */}
<Suspense fallback={<NotificationsSkeleton />}>
<Notifications />
</Suspense>
</>
)
}
async function Stats() {
'use cache'
cacheLife('hours')
cacheTag('dashboard-stats')
const stats = await db.stats.aggregate()
return <StatsDisplay stats={stats} />
}
async function Notifications() {
const userId = (await cookies()).get('userId')?.value
const notifications = await db.notifications.findMany({
where: { userId, read: false }
})
return <NotificationList items={notifications} />
}
Migration von früheren Versionen
| Alte Konfiguration | Ersatz |
|---|---|
experimental.ppr | cacheComponents: true |
dynamic = 'force-dynamic' | Entfernen (Standardverhalten) |
dynamic = 'force-static' | 'use cache' + cacheLife('max') |
revalidate = N | cacheLife({ revalidate: N }) |
unstable_cache() | 'use cache'-Direktiv |
Einschränkungen
- Edge-Laufzeit nicht unterstützt – Node.js erforderlich
- Statischer Export nicht unterstützt – Server erforderlich
- Nicht-deterministische Werte (
Math.random(),Date.now()) werden innerhalb vonuse cachenur einmal zur Build-Zeit ausgeführt
Für Laufzeit-Zufall außerhalb des Caches:
import { connection } from 'next/server'
async function DynamicContent() {
await connection() // Zur Anfragezeit verschieben
const id = crypto.randomUUID() // Unterschiedlich pro Anfrage
return <div>{id}</div>
}
Quellen: