O que Componentes de Cache (Next.js 16+) faz?
Os Componentes de Cache habilitam o Partial Prerendering (PPR) – misture conteúdo estático, cached e dinâmico em uma única rota.
Ativar Componentes de Cache
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
Isso substitui o antigo flag experimental.ppr.
Três Tipos de Conteúdo
Com os Componentes de Cache ativados, o conteúdo se enquadra em três categorias:
1. Estático (Pré-renderizado Automaticamente)
Código síncrono, importações, computações puras – pré-renderizado em tempo de build:
export default function Page() {
return (
<header>
<h1>Nosso Blog</h1> {/* Estático - instantâneo */}
<nav>...</nav>
</header>
)
}
2. Em Cache (use cache)
Dados assíncronos que não precisam de buscas novas a cada requisição:
async function BlogPosts() {
'use cache'
cacheLife('hours')
const posts = await db.posts.findMany()
return <PostList posts={posts} />
}
3. Dinâmico (Suspense)
Dados de runtime que precisam estar frescos – envolva em Suspense:
import { Suspense } from 'react'
export default function Page() {
return (
<>
<BlogPosts /> {/* Em Cache */}
<Suspense fallback={<p>Carregando...</p>}>
<UserPreferences /> {/* Dinâmico - entra em streaming */}
</Suspense>
</>
)
}
async function UserPreferences() {
const theme = (await cookies()).get('theme')?.value
return <p>Tema: {theme}</p>
}
Diretiva use cache
Nível de Arquivo
'use cache'
export default async function Page() {
// Página inteira é armazenada em cache
const data = await fetchData()
return <div>{data}</div>
}
Nível de Componente
export async function CachedComponent() {
'use cache'
const data = await fetchData()
return <div>{data}</div>
}
Nível de Função
export async function getData() {
'use cache'
return db.query('SELECT * FROM posts')
}
Perfis de Cache
Perfis Integrados
'use cache' // Padrão: 5 min stale, 15 min revalidação
'use cache: remote' // Cache fornecido pela plataforma (Redis, KV)
'use cache: private' // Para conformidade, permite APIs de runtime
cacheLife() - Vida Útil Personalizada
import { cacheLife } from 'next/cache'
async function getData() {
'use cache'
cacheLife('hours') // Perfil integrado
return fetch('/api/data')
}
Perfis integrados: 'default', 'minutes', 'hours', 'days', 'weeks', 'max'
Configuração Inline
async function getData() {
'use cache'
cacheLife({
stale: 3600, // 1 hora - serve stale enquanto revalida
revalidate: 7200, // 2 horas - intervalo de revalidação em segundo plano
expire: 86400, // 1 dia - expiração forçada
})
return fetch('/api/data')
}
Invalidação de Cache
cacheTag() - Marcar Conteúdo em 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() - Invalidação Imediata
Use quando precisar que o cache seja atualizado dentro da mesma requisição:
'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}`) // Imediato - mesma requisição vê dados frescos
}
revalidateTag() - Revalidação em Segundo Plano
Use para comportamento stale-while-revalidate:
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost(data: FormData) {
await db.posts.create({ data })
revalidateTag('posts') // Segundo plano - próxima requisição vê dados frescos
}
Restrição de Dados de Runtime
Não é possível acessar cookies(), headers() ou searchParams dentro de use cache.
Solução: Passe como Argumentos
// Errado - API de runtime dentro de use cache
async function CachedProfile() {
'use cache'
const session = (await cookies()).get('session')?.value // Erro!
return <div>{session}</div>
}
// Correto - extraia fora, passe 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 torna parte da chave de cache automaticamente
const data = await fetchUserData(sessionId)
return <div>{data.name}</div>
}
Exceção: use cache: private
Para requisitos de conformidade quando não é possível refatorar:
async function getData() {
'use cache: private'
const session = (await cookies()).get('session')?.value // Permitido
return fetchData(session)
}
Geração de Chave de Cache
As chaves de cache são automáticas e baseadas em:
- Build ID - invalida todos os caches no deploy
- Function ID - hash da localização da função
- Argumentos serializáveis - props se tornam parte da chave
- Variáveis de closure - valores do escopo externo incluídos
async function Component({ userId }: { userId: string }) {
const getData = async (filter: string) => {
'use cache'
// Chave de cache = userId (closure) + filter (argumento)
return fetch(`/api/users/${userId}?filter=${filter}`)
}
return getData('active')
}
Exemplo Completo
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
export default function DashboardPage() {
return (
<>
{/* Shell estático - instantâneo do CDN */}
<header><h1>Dashboard</h1></header>
<nav>...</nav>
{/* Em cache - rápido, revalida a cada hora */}
<Stats />
{/* Dinâmico - entra em streaming com dados 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} />
}
Migração de Versões Anteriores
| Configuração Antiga | Substituição |
|---|---|
experimental.ppr | cacheComponents: true |
dynamic = 'force-dynamic' | Remover (comportamento padrão) |
dynamic = 'force-static' | 'use cache' + cacheLife('max') |
revalidate = N | cacheLife({ revalidate: N }) |
unstable_cache() | Diretiva 'use cache' |
Limitações
- Runtime Edge não suportado - requer Node.js
- Exportação estática não suportada - precisa de servidor
- Valores não determinísticos (
Math.random(),Date.now()) executam uma vez em tempo de build dentro deuse cache
Para aleatoriedade em tempo de requisição fora do cache:
import { connection } from 'next/server'
async function DynamicContent() {
await connection() // Adiar para o tempo de requisição
const id = crypto.randomUUID() // Diferente por requisição
return <div>{id}</div>
}
Fontes: