Capítulo 176 de 456

revalidatePath

Core Idea

Invalida dados cacheados sob demanda para um path específico (página, layout ou route handler), forçando dados frescos na próxima visita.

Key Concepts

  • revalidatePath(path, type?): path é literal (/product/123) ou padrão com segmento dinâmico (/product/[slug], exige type); não anexar /page ou /layout ao path, use o parâmetro type. Máx. 1024 caracteres, case-sensitive.
  • Server Functions vs Route Handlers: em Server Functions atualiza a UI imediatamente se a página afetada está sendo vista; em Route Handlers, apenas marca para revalidação na próxima visita.
  • Escopo de invalidação por tipo: Pages invalida só a página específica; Layouts invalida o layout + todos os layouts/páginas aninhados abaixo; Route Handlers invalida dados cacheados acessados dentro do handler.
  • Com rewrites: deve usar o path de destino (arquivo de rota real), não o path de origem visível na URL do browser.

Code Examples

import { revalidatePath } from 'next/cache'
revalidatePath('/blog/post-1')
  • O que demonstra: revalidação de um path literal específico.
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'page')
  • O que demonstra: revalidar todas as páginas que casam com um padrão dinâmico, sem afetar rotas aninhadas abaixo.
import { revalidatePath } from 'next/cache'
revalidatePath('/', 'layout')
  • O que demonstra: purga o Client Cache inteiro e invalida todos os dados cacheados da aplicação.
'use server'
import { revalidatePath, updateTag } from 'next/cache'

export async function updatePost() {
  await updatePostInDatabase()
  revalidatePath('/blog')
  updateTag('posts')
}
  • O que demonstra: combinar revalidatePath (path específico) com updateTag (todas as páginas que usam a tag) para consistência abrangente.

Reference Tables

ParameterTypeDescription
pathstringrota literal ou padrão dinâmico, máx 1024 chars
type'page' | 'layout' (opcional)obrigatório se path tem segmento dinâmico

Anti-patterns

  • Usar o path de origem de um rewrite: revalidatePath opera na estrutura de arquivo de rota, não na URL visível — use o destino do rewrite.
  • Confundir com revalidateTag/updateTag: revalidatePath só afeta o path específico; páginas diferentes que usam os mesmos dados com tags continuam servindo cache stale até a tag ser invalidada também.
  • Chamar em Client Component ou Proxy: só funciona em Server Functions e Route Handlers.

Key Takeaways

  1. Só o path (ou padrão) especificado é invalidado — outras páginas com a mesma tag de dados continuam stale.
  2. Em Route Handlers, a invalidação é preguiçosa (só na próxima visita), evitando rajadas de revalidação com paths dinâmicos.
  3. Combine com updateTag para invalidação abrangente entre páginas diferentes que compartilham dados.

Connects To

  • revalidateTag: invalida por tag, aplicando-se a todas as páginas que a usam.
  • updateTag: expira dados por tag imediatamente, ao invés de marcar como stale.
AnteriorrefreshPróximorevalidateTag