Que fait Composants de Cache (Next.js 16+) ?
Les composants de cache permettent le rendu partiel (PPR) - mélanger contenu statique, en cache et dynamique dans une seule route.
Activer les composants de cache
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
Ceci remplace l'ancien flag experimental.ppr.
Trois types de contenu
Avec les composants de cache activés, le contenu se répartit en trois catégories :
1. Statique (prérendu automatiquement)
Code synchrone, imports, calculs purs - prérendu à la compilation :
export default function Page() {
return (
<header>
<h1>Notre Blog</h1> {/* Statique - instantané */}
<nav>...</nav>
</header>
)
}
2. En cache (use cache)
Données asynchrones qui n'ont pas besoin d'être récupérées à chaque requête :
async function BlogPosts() {
'use cache'
cacheLife('hours')
const posts = await db.posts.findMany()
return <PostList posts={posts} />
}
3. Dynamique (Suspense)
Données d'exécution qui doivent être fraîches - enveloppez-les dans Suspense :
import { Suspense } from 'react'
export default function Page() {
return (
<>
<BlogPosts /> {/* En cache */}
<Suspense fallback={<p>Chargement...</p>}>
<UserPreferences /> {/* Dynamique - diffusé en continu */}
</Suspense>
</>
)
}
async function UserPreferences() {
const theme = (await cookies()).get('theme')?.value
return <p>Thème : {theme}</p>
}
Directive use cache
Au niveau du fichier
'use cache'
export default async function Page() {
// La page entière est mise en cache
const data = await fetchData()
return <div>{data}</div>
}
Au niveau du composant
export async function CachedComponent() {
'use cache'
const data = await fetchData()
return <div>{data}</div>
}
Au niveau de la fonction
export async function getData() {
'use cache'
return db.query('SELECT * FROM posts')
}
Profils de cache
Profils intégrés
'use cache' // Par défaut : 5min obsolète, 15min revalidation
'use cache: remote' // Cache fourni par la plateforme (Redis, KV)
'use cache: private' // Pour la conformité, autorise les API d'exécution
cacheLife() - Durée de vie personnalisée
import { cacheLife } from 'next/cache'
async function getData() {
'use cache'
cacheLife('hours') // Profil intégré
return fetch('/api/data')
}
Profils intégrés : 'default', 'minutes', 'hours', 'days', 'weeks', 'max'
Configuration inline
async function getData() {
'use cache'
cacheLife({
stale: 3600, // 1 heure - servir obsolète pendant la revalidation
revalidate: 7200, // 2 heures - intervalle de revalidation en arrière-plan
expire: 86400, // 1 jour - expiration dure
})
return fetch('/api/data')
}
Invalidation du cache
cacheTag() - Marquer le contenu mis en cache
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() - Invalidation immédiate
À utiliser lorsque vous avez besoin que le cache soit rafraîchi dans la même requête :
'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}`) // Immédiat - la même requête voit les données fraîches
}
revalidateTag() - Revalidation en arrière-plan
À utiliser pour le comportement stale-while-revalidate :
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost(data: FormData) {
await db.posts.create({ data })
revalidateTag('posts') // Arrière-plan - la prochaine requête voit les données fraîches
}
Contrainte des données d'exécution
Impossible d'accéder à cookies(), headers() ou searchParams à l'intérieur de use cache.
Solution : passer en tant qu'arguments
// Erroné - API d'exécution dans use cache
async function CachedProfile() {
'use cache'
const session = (await cookies()).get('session')?.value // Erreur !
return <div>{session}</div>
}
// Correct - extraire en dehors, passer en argument
async function ProfilePage() {
const session = (await cookies()).get('session')?.value
return <CachedProfile sessionId={session} />
}
async function CachedProfile({ sessionId }: { sessionId: string }) {
'use cache'
// sessionId devient automatiquement partie de la clé de cache
const data = await fetchUserData(sessionId)
return <div>{data.name}</div>
}
Exception : use cache: private
Pour les besoins de conformité lorsque vous ne pouvez pas refactoriser :
async function getData() {
'use cache: private'
const session = (await cookies()).get('session')?.value // Autorisé
return fetchData(session)
}
Génération de la clé de cache
Les clés de cache sont automatiques basées sur :
- ID de build - invalide tous les caches au déploiement
- ID de fonction - hachage de l'emplacement de la fonction
- Arguments sérialisables - les props deviennent partie de la clé
- Variables de fermeture - les valeurs de la portée externe incluses
async function Component({ userId }: { userId: string }) {
const getData = async (filter: string) => {
'use cache'
// Clé de cache = userId (fermeture) + filter (argument)
return fetch(`/api/users/${userId}?filter=${filter}`)
}
return getData('active')
}
Exemple complet
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
export default function DashboardPage() {
return (
<>
{/* Coque statique - instantané depuis le CDN */}
<header><h1>Tableau de bord</h1></header>
<nav>...</nav>
{/* En cache - rapide, revalidation toutes les heures */}
<Stats />
{/* Dynamique - diffusé en continu avec des données fraîches */}
<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 depuis les versions précédentes
| Ancienne configuration | Remplacement |
|---|---|
experimental.ppr | cacheComponents: true |
dynamic = 'force-dynamic' | Supprimer (comportement par défaut) |
dynamic = 'force-static' | 'use cache' + cacheLife('max') |
revalidate = N | cacheLife({ revalidate: N }) |
unstable_cache() | Directive 'use cache' |
Limitations
- Edge runtime non supporté - nécessite Node.js
- Export statique non supporté - nécessite un serveur
- Valeurs non déterministes (
Math.random(),Date.now()) exécutées une fois à la compilation dansuse cache
Pour l'aléatoire au moment de la requête en dehors du cache :
import { connection } from 'next/server'
async function DynamicContent() {
await connection() // Reporter au moment de la requête
const id = crypto.randomUUID() // Différent par requête
return <div>{id}</div>
}
Sources :