Revalidação
Esta página trata da revalidação com Cache Components, habilitado ao definir
cacheComponents: trueno arquivonext.config.ts. Se você não usa Cache Components, veja o guia Cache e revalidação (modelo anterior).
Revalidação é o processo de atualizar dados em cache. Ela permite continuar servindo respostas rápidas em cache e, ao mesmo tempo, garantir que o conteúdo continue atualizado. Existem duas estratégias:
- Revalidação baseada em tempo: atualiza automaticamente os dados em cache depois de um período definido, usando
cacheLife. - Revalidação sob demanda: invalida manualmente os dados em cache depois de uma mutação, usando
revalidateTag,updateTagourevalidatePath.
cacheLife
cacheLife controla por quanto tempo os dados em cache continuam válidos. Use-o dentro de um escopo use cache para definir o tempo de vida do cache.
import { cacheLife } from 'next/cache'
export async function getProducts() {
'use cache'
cacheLife('hours')
return db.query('SELECT * FROM products')
}cacheLife aceita o nome de um perfil ou um objeto de configuração personalizada:
| Perfil | stale | revalidate | expire |
|---|---|---|---|
default | 5m | 15m | never |
seconds | 30s | 1s | 60s |
minutes | 5m | 1m | 1h |
hours | 5m | 1h | 1d |
days | 5m | 1d | 1w |
weeks | 5m | 1w | 30d |
max | 5m | 30d | 1y |
Para controle detalhado, passe um objeto:
'use cache'
cacheLife({
stale: 3600, // 1 hour until considered stale
revalidate: 7200, // 2 hours until revalidated
expire: 86400, // 1 day until expired
})Bom saber: um cache é considerado "de vida curta" quando usa o perfil
seconds,revalidate: 0ou umexpiremenor que 5 minutos. Caches de vida curta são excluídos automaticamente do prerendering e viram partes dinâmicas (dynamic holes). Veja comportamento do prerendering para detalhes.
Veja a referência da API de cacheLife para todos os perfis e opções de configuração personalizada.
cacheTag
cacheTag permite marcar dados em cache para que possam ser invalidados sob demanda. Use-o dentro de um escopo use cache:
import { cacheTag } from 'next/cache'
export async function getProducts() {
'use cache'
cacheTag('products')
return db.query('SELECT * FROM products')
}import { cacheTag } from 'next/cache'
export async function getProducts() {
'use cache'
cacheTag('products')
return db.query('SELECT * FROM products')
}Depois de marcado, invalide o cache usando revalidateTag ou updateTag.
Veja a referência da API de cacheTag para saber mais.
revalidateTag
revalidateTag com o perfil recomendado 'max' invalida entradas de cache por tag usando semântica de stale-while-revalidate. O conteúdo obsoleto é servido imediatamente enquanto o conteúdo novo carrega em segundo plano. Isso é ideal para conteúdos em que um pequeno atraso nas atualizações é aceitável, como posts de blog ou catálogos de produtos.
import { revalidateTag } from 'next/cache'
export async function updateUser(id: string) {
// Mutate data
revalidateTag('user', 'max') // Recommended: stale-while-revalidate
}import { revalidateTag } from 'next/cache'
export async function updateUser(id) {
// Mutate data
revalidateTag('user', 'max') // Recommended: stale-while-revalidate
}Você pode reutilizar a mesma tag em várias funções para revalidá-las todas de uma vez. Chame revalidateTag em uma Server Action ou em um Route Handler.
Bom saber: o segundo argumento define por quanto tempo conteúdo obsoleto pode ser servido enquanto o conteúdo novo é gerado em segundo plano. Quando ele expira, as requisições seguintes ficam bloqueadas até que o conteúdo novo esteja pronto. Usar
'max'dá a maior janela em que o conteúdo obsoleto pode ser servido.
Veja a referência da API de revalidateTag para saber mais.
updateTag
updateTag expira imediatamente os dados em cache para cenários de leitura das próprias escritas (read-your-own-writes): o usuário vê a alteração na hora, em vez de conteúdo obsoleto. Diferente de revalidateTag, ele só pode ser usado em Server Actions.
Bom saber:
updateTagtambém atualiza a rota que o chamou e invalida entradas do cache do cliente. Veja comportamento do cache do cliente para o escopo e a comparação comrevalidateTag.
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
const post = await db.post.create({
data: {
title: formData.get('title'),
content: formData.get('content'),
},
})
updateTag('posts')
redirect(`/posts/${post.id}`)
}import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData) {
const post = await db.post.create({
data: {
title: formData.get('title'),
content: formData.get('content'),
},
})
updateTag('posts')
redirect(`/posts/${post.id}`)
}updateTag | revalidateTag(tag, 'max') | |
|---|---|---|
| Onde | Somente Server Actions | Server Actions e Route Handlers |
| Comportamento | Expira o cache imediatamente | Stale-while-revalidate |
| Caso de uso | Leitura das próprias escritas (o usuário vê a alteração) | Atualização em segundo plano (pequeno atraso é aceitável) |
Veja a referência da API de updateTag para saber mais.
revalidatePath
revalidatePath invalida todos os dados em cache de um caminho de rota específico. Use-o quando quiser revalidar uma rota sem saber quais tags estão associadas a ela.
import { revalidatePath } from 'next/cache'
export async function updateUser(id: string) {
// Mutate data
revalidatePath('/profile')
}import { revalidatePath } from 'next/cache'
export async function updateUser(id) {
// Mutate data
revalidatePath('/profile')
}Bom saber: prefira a revalidação por tag (
revalidateTag/updateTag) à revalidação por caminho sempre que possível. Tags atingem os dados em cache do lado do servidor com mais precisão e evitam invalidar em excesso. A invalidação do cache do cliente tem um escopo mais amplo.
Veja a referência da API de revalidatePath para saber mais.
O que devo colocar em cache?
Coloque em cache dados que não dependem de dados de runtime e que você aceita servir do cache por um período. Use use cache com cacheLife para descrever esse comportamento.
Quando o conteúdo não precisa de revalidação baseada em tempo, por exemplo dados de um CMS, use cacheTag e um cacheLife longo, como max, para mantê-lo no shell estático. Configure a fonte do conteúdo para disparar um webhook ou outra notificação que chame revalidateTag quando o conteúdo mudar. Isso reduz revalidações baseadas em tempo desnecessárias para conteúdo que não foi alterado.
Bom saber: em ambientes serverless, entradas de cache em memória podem não persistir entre revalidações. Veja considerações sobre cache em runtime para detalhes.
Referência da API
Saiba mais sobre as APIs mencionadas nesta página.