Componentes de Caché (Next.js 16+)
Los Componentes de Caché permiten el Prerenderizado Parcial (PPR): mezclar contenido estático, en caché y dinámico en una sola ruta.
Habilitar Componentes de Caché
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
Esto reemplaza el antiguo flag experimental.ppr.
Tres Tipos de Contenido
Con los Componentes de Caché habilitados, el contenido se divide en tres categorías:
1. Estático (Pre-renderizado automáticamente)
Código síncrono, importaciones, cálculos puros: pre-renderizados en tiempo de compilación:
export default function Page() {
return (
<header>
<h1>Nuestro Blog</h1> {/* Estático - instantáneo */}
<nav>...</nav>
</header>
)
}
2. En Caché (use cache)
Datos asíncronos que no necesitan búsquedas frescas en cada solicitud:
async function BlogPosts() {
'use cache'
cacheLife('hours')
const posts = await db.posts.findMany()
return <PostList posts={posts} />
}
3. Dinámico (Suspense)
Datos en tiempo de ejecución que deben estar frescos: envuélvelos en Suspense:
import { Suspense } from 'react'
export default function Page() {
return (
<>
<BlogPosts /> {/* En caché */}
<Suspense fallback={<p>Cargando...</p>}>
<UserPreferences /> {/* Dinámico - se transmite */}
</Suspense>
</>
)
}
async function UserPreferences() {
const theme = (await cookies()).get('theme')?.value
return <p>Tema: {theme}</p>
}
Directiva use cache
A Nivel de Archivo
'use cache'
export default async function Page() {
// Toda la página se almacena en caché
const data = await fetchData()
return <div>{data}</div>
}
A Nivel de Componente
export async function CachedComponent() {
'use cache'
const data = await fetchData()
return <div>{data}</div>
}
A Nivel de Función
export async function getData() {
'use cache'
return db.query('SELECT * FROM posts')
}
Perfiles de Caché
Perfiles Incorporados
'use cache' // Por defecto: 5m obsoleto, 15m revalidación
'use cache: remote' // Caché proporcionado por la plataforma (Redis, KV)
'use cache: private' // Para cumplimiento, permite APIs de tiempo de ejecución
cacheLife() - Vida Útil Personalizada
import { cacheLife } from 'next/cache'
async function getData() {
'use cache'
cacheLife('hours') // Perfil incorporado
return fetch('/api/data')
}
Perfiles incorporados: 'default', 'minutes', 'hours', 'days', 'weeks', 'max'
Configuración en Línea
async function getData() {
'use cache'
cacheLife({
stale: 3600, // 1 hora - servir obsoleto mientras se revalida
revalidate: 7200, // 2 horas - intervalo de revalidación en segundo plano
expire: 86400, // 1 día - expiración forzosa
})
return fetch('/api/data')
}
Invalidación de Caché
cacheTag() - Etiquetar Contenido en Caché
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() - Invalidación Inmediata
Úsalo cuando necesites que la caché se refresque dentro de la misma solicitud:
'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}`) // Inmediato - la misma solicitud ve datos frescos
}
revalidateTag() - Revalidación en Segundo Plano
Úsalo para el comportamiento de obsoleto-mientras-revalida:
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost(data: FormData) {
await db.posts.create({ data })
revalidateTag('posts') // Segundo plano - la próxima solicitud ve datos frescos
}
Restricción de Datos en Tiempo de Ejecución
No se puede acceder a cookies(), headers() o searchParams dentro de use cache.
Solución: Pasar como Argumentos
// Incorrecto - API de tiempo de ejecución dentro de use cache
async function CachedProfile() {
'use cache'
const session = (await cookies()).get('session')?.value // ¡Error!
return <div>{session}</div>
}
// Correcto - extraer fuera, pasar como argumento
async function ProfilePage() {
const session = (await cookies()).get('session')?.value
return <CachedProfile sessionId={session} />
}
async function CachedProfile({ sessionId }: { sessionId: string }) {
'use cache'
// sessionId se convierte automáticamente en parte de la clave de caché
const data = await fetchUserData(sessionId)
return <div>{data.name}</div>
}
Excepción: use cache: private
Para requisitos de cumplimiento cuando no se puede refactorizar:
async function getData() {
'use cache: private'
const session = (await cookies()).get('session')?.value // Permitido
return fetchData(session)
}
Generación de Claves de Caché
Las claves de caché se generan automáticamente basándose en:
- ID de compilación - invalida todas las cachés al desplegar
- ID de función - hash de la ubicación de la función
- Argumentos serializables - las props se convierten en parte de la clave
- Variables de cierre - se incluyen valores del ámbito externo
async function Component({ userId }: { userId: string }) {
const getData = async (filter: string) => {
'use cache'
// Clave de caché = userId (cierre) + filter (argumento)
return fetch(`/api/users/${userId}?filter=${filter}`)
}
return getData('active')
}
Ejemplo Completo
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
export default function DashboardPage() {
return (
<>
{/* Esqueleto estático - instantáneo desde CDN */}
<header><h1>Dashboard</h1></header>
<nav>...</nav>
{/* En caché - rápido, se revalida cada hora */}
<Stats />
{/* Dinámico - se transmite con datos frescos */}
<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} />
}
Migración desde Versiones Anteriores
| Configuración Antigua | Reemplazo |
|---|---|
experimental.ppr | cacheComponents: true |
dynamic = 'force-dynamic' | Eliminar (comportamiento por defecto) |
dynamic = 'force-static' | 'use cache' + cacheLife('max') |
revalidate = N | cacheLife({ revalidate: N }) |
unstable_cache() | Directiva 'use cache' |
Limitaciones
- Edge runtime no soportado - requiere Node.js
- Exportación estática no soportada - necesita servidor
- Valores no deterministas (
Math.random(),Date.now()) se ejecutan una vez en tiempo de compilación dentro deuse cache
Para aleatoriedad en tiempo de solicitud fuera de la caché:
import { connection } from 'next/server'
async function DynamicContent() {
await connection() // Diferir al momento de la solicitud
const id = crypto.randomUUID() // Diferente por solicitud
return <div>{id}</div>
}
Fuentes: