Cache
Esta página trata do cache 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).
Cache é uma técnica para armazenar o resultado de buscas de dados e de outras computações, para que requisições futuras pelos mesmos dados possam ser atendidas mais rápido, sem refazer o trabalho.
Habilitar Cache Components
Apps novos do App Router criados com os padrões recomendados do create-next-app já vêm com Cache Components e Partial Prefetching habilitados.
Para habilitar em um app existente ou criado manualmente, adicione as opções cacheComponents e partialPrefetching ao arquivo de configuração do Next:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig/** @type {import('next').NextConfig} */
const nextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
module.exports = nextConfigDefina partialPrefetching explicitamente. Deixá-lo sem valor gera um aviso, porque a primeira versão de Cache Components não incluía Partial Prefetching. Defina como false somente enquanto migra um app que adotou Cache Components antes do Partial Prefetching. Os dois recursos serão habilitados em todos os lugares na próxima versão major, e as opções serão removidas.
Bom saber: quando Cache Components está habilitado, Route Handlers
GETseguem o mesmo modelo de prerendering das páginas. Veja Route Handlers com Cache Components para detalhes.
Uso
A diretiva use cache armazena em cache o valor de retorno de funções assíncronas e de componentes. Você pode aplicá-la em dois níveis:
- Nível de dados: armazena em cache uma função que busca ou calcula dados (ex.:
getProducts(),getUser(id)) - Nível de UI: armazena em cache um componente ou uma página inteira (ex.:
async function BlogPosts())
Uma diretiva de cache dá um tempo de vida ao resultado, que o Next.js usa para revalidação baseada em tempo e otimizações de renderização. Para revalidação sob demanda após uma mutação, veja Revalidação. Veja Prerendering para entender como os resultados em cache passam a fazer parte do shell estático e podem ser incluídos em um prefetch.
Bom saber: recomendamos combinar toda diretiva de cache com um
cacheLife. Sem ele, vale o perfil implícitodefault.
Argumentos e valores capturados de escopos pais se tornam automaticamente parte da chave de cache, o que significa que entradas diferentes geram entradas de cache separadas. Veja saída do cache para saber o que uma entrada guarda, e requisitos de serialização e restrições para detalhes sobre o que pode ser armazenado e como os argumentos funcionam.
Caching em nível de dados
Para armazenar em cache uma função assíncrona que busca dados, adicione a diretiva use cache no início do corpo da função:
import { cacheLife } from 'next/cache'
export async function getUsers() {
'use cache'
cacheLife('hours')
return db.query('SELECT * FROM users')
}Cache em nível de dados é útil quando os mesmos dados são usados em vários componentes, ou quando você quer armazenar os dados em cache independentemente da UI.
Caching em nível de UI
Para armazenar em cache um componente, página ou layout inteiro, adicione a diretiva use cache no início do corpo do componente ou da página:
import { cacheLife } from 'next/cache'
export default async function Page() {
'use cache'
cacheLife('hours')
const users = await db.query('SELECT * FROM users')
return (
<ul>
{users.map((user) => (
<li key={user.id}>{user.name}</li>
))}
</ul>
)
}Se você adicionar "
use cache" no início de um arquivo, todas as funções exportadas no arquivo serão armazenadas em cache.
Streaming de dados sem cache
Para componentes que buscam dados de uma fonte assíncrona, como uma API, um banco de dados ou qualquer outra operação assíncrona, e que precisam de dados novos a cada requisição, não use "use cache".
Em vez disso, envolva o componente em <Suspense> e forneça uma UI de fallback. O fallback faz parte do shell estático gerado no prerendering, enquanto o trabalho assíncrono roda no momento da requisição.
import { Suspense } from 'react'
async function LatestPosts() {
const data = await fetch('https://api.example.com/posts')
const posts = await data.json()
return (
<ul>
{posts.map((post) => (
<li key={post.id}>{post.title}</li>
))}
</ul>
)
}
export default function Page() {
return (
<>
<h1>My Blog</h1>
<Suspense fallback={<p>Loading posts...</p>}>
<LatestPosts />
</Suspense>
</>
)
}Por exemplo, <p>Loading posts...</p> faz parte do shell estático, e os posts chegam por streaming no momento da requisição.
Sem um limite <Suspense> ao redor da leitura sem cache, o overlay de desenvolvimento exibe o insight de blocking-route com esta correção:
Bom saber: cada cartão de correção leva a um passo a passo detalhado, com padrões, exemplos de código e trade-offs. Clique em um cartão para se aprofundar.
<Suspense> oferece uma UI de fallback enquanto o trabalho assíncrono é concluído, mas não faz um componente entrar em Dynamic Rendering por conta própria. Se um componente faz apenas trabalho síncrono, ele será concluído durante o prerendering, esteja ou não envolvido em <Suspense>.
Trabalhando com APIs de runtime
APIs de runtime precisam de informações disponíveis apenas quando o usuário faz uma requisição. Elas incluem:
cookies- dados de cookies do usuárioheaders- cabeçalhos da requisiçãosearchParams- parâmetros de query da URLparams- parâmetros de rotas dinâmicas. UsegenerateStaticParamspara fazer prerendering de valores específicos no momento do build, ou ISR com Cache Components para servir um App Shell enquanto parâmetros desconhecidos são resolvidos em segundo plano.
Componentes que acessam APIs de runtime devem ser envolvidos em <Suspense>:
import { cookies } from 'next/headers'
import { Suspense } from 'react'
async function UserGreeting() {
const cookieStore = await cookies()
const theme = cookieStore.get('theme')?.value || 'light'
return <p>Your theme: {theme}</p>
}
export default function Page() {
return (
<>
<h1>Dashboard</h1>
<Suspense fallback={<p>Loading...</p>}>
<UserGreeting />
</Suspense>
</>
)
}Um acesso a API de runtime sem <Suspense> exibe o mesmo insight de blocking-route no overlay de desenvolvimento, com a mesma correção:
Dados que dependem de runtime ainda podem receber um tempo de vida de cache com "use cache: private", outra variante que acompanha Cache Components. Ela dá tempo de vida a uma função que lê cookies, headers ou searchParams diretamente, para que possa ser incluída em um prefetch.
A seção a seguir mostra uma alternativa ao use cache: private: extrair um valor de runtime e passá-lo para uma função em cache compartilhada.
Passando valores de runtime para funções em cache
Você pode extrair valores de APIs de runtime e passá-los como argumentos para funções em cache:
import { cookies } from 'next/headers'
import { Suspense } from 'react'
export default function Page() {
return (
<Suspense fallback={<div>Loading...</div>}>
<ProfileContent />
</Suspense>
)
}
// Component (not cached) reads runtime data
async function ProfileContent() {
const session = (await cookies()).get('session')?.value
return <CachedContent sessionId={session} />
}
// Cached component receives extracted value as a prop
async function CachedContent({ sessionId }: { sessionId: string }) {
'use cache'
// sessionId becomes part of the cache key
const data = await fetchUserData(sessionId)
return <div>{data}</div>
}No momento da requisição, <CachedContent /> é executado se não houver entrada de cache correspondente, e armazena o resultado para requisições futuras com o mesmo sessionId.
Bom saber: como
<CachedContent />fica condicionado a dados da requisição, ele não é incluído no shell estático gerado no prerendering. Em runtime, ele é armazenado em cache em memória por padrão, o que não persiste entre requisições serverless, então pode ser reavaliado a cada requisição. Use'use cache: remote'para um cache durável e compartilhado.
Com esse padrão, o prefetching pode fazer prerendering de <CachedContent /> com a sessão real do usuário durante uma transição no cliente, e ter o resultado pronto antes do clique. Isso funciona mesmo quando as entradas do lado do servidor raramente sobrevivem entre requisições, porque o tempo de vida que você atribui é o que permite ao resultado entrar no prefetch, onde o cliente o trata como atualizado durante a janela stale do cacheLife.
Estático, em cache e em streaming
Aqui está um exemplo completo que mostra conteúdo estático, conteúdo dinâmico em cache e conteúdo dinâmico em streaming funcionando juntos em uma única página:
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
import Link from 'next/link'
export default function BlogPage() {
return (
<>
{/* Static content - prerendered automatically */}
<header>
<h1>Our Blog</h1>
<nav>
<Link href="/">Home</Link> | <Link href="/about">About</Link>
</nav>
</header>
{/* Cached dynamic content - included in the static shell */}
<BlogPosts />
{/* Runtime dynamic content - streams at request time */}
<Suspense fallback={<p>Loading your preferences...</p>}>
<UserPreferences />
</Suspense>
</>
)
}
type Post = { id: string; title: string; author: string; date: string }
// Everyone sees the same blog posts (revalidated every hour)
async function BlogPosts() {
'use cache'
cacheLife('hours')
cacheTag('posts')
const res = await fetch('https://api.vercel.app/blog')
const posts: Post[] = await res.json()
return (
<section>
<h2>Latest Posts</h2>
<ul>
{posts.map((post) => (
<li key={post.id}>
<h3>{post.title}</h3>
<p>
By {post.author} on {post.date}
</p>
</li>
))}
</ul>
</section>
)
}
// UI that depends on a value stored in cookies
async function UserPreferences() {
const theme = (await cookies()).get('theme')?.value || 'light'
const favoriteCategory = (await cookies()).get('category')?.value
return (
<aside>
<p>Your theme: {theme}</p>
{favoriteCategory && <p>Favorite category: {favoriteCategory}</p>}
</aside>
)
}Durante o prerendering, o cabeçalho (estático) e os posts do blog (em cache com use cache) fazem parte do shell estático, junto com a UI de fallback das preferências do usuário. As preferências de UI armazenadas em cookies chegam por streaming no momento da requisição.
Ler cookies() aqui não coloca a rota inteira em Dynamic Rendering, como acontecia no modelo de renderização anterior. O limite <Suspense> fornece a UI de fallback onde o acesso ao runtime faz streaming, enquanto o conteúdo estático e em cache continua sendo enviado no HTML inicial.
Assim como <Suspense> contém acessos assíncronos, um error boundary contém falhas: coloque-o ao redor de uma subárvore que pode falhar durante a renderização. Use catchError para limites no nível de componente, ou a convenção de arquivo error.js para limites no nível de rota.
Ao construir, lembre-se de que dentro de generateMetadata e generateViewport, fetches sem cache ou acessos a dados de runtime exibem os mesmos insights e erros que na sua página, orientando você para a renderização pretendida. Para regeneração estática incremental com valores de parâmetros conhecidos e desconhecidos, veja ISR com Cache Components.
Valores aleatórios e timestamps
Operações como Math.random(), Date.now() ou crypto.randomUUID() produzem valores diferentes a cada execução. Cache Components exige que você trate isso explicitamente.
Bom saber:
performance.now()é feito para telemetria, então o Next.js não o trata como valor a ser protegido. Use-o para medir tempo e passe o resultado para seu logger ou para métricas, em vez de renderizá-lo.
Para gerar valores únicos por requisição, adie para o momento da requisição chamando connection() antes dessas operações, e envolva o componente em <Suspense>:
import { connection } from 'next/server'
import { Suspense } from 'react'
async function UniqueContent() {
await connection()
const uuid = crypto.randomUUID()
return <p>Request ID: {uuid}</p>
}
export default function Page() {
return (
<Suspense fallback={<p>Loading...</p>}>
<UniqueContent />
</Suspense>
)
}Como alternativa, você pode armazenar o resultado em cache, para que todos os usuários vejam o mesmo valor até a revalidação:
export default async function Page() {
'use cache'
const buildId = crypto.randomUUID()
return <p>Build ID: {buildId}</p>
}Você não precisa decorar quais operações se comportam assim. O overlay de desenvolvimento exibe um insight de blocking-prerender-random, blocking-prerender-current-time ou blocking-prerender-crypto (dependendo da chamada), com estas correções:
await connection() const id = Math.random() return <Item id={id} />CacheArmazenar o valor em cache
function RandomId() { "use cache" return String(Math.random())
Valores previsíveis
Diferente de valores aleatórios e timestamps, que podem variar entre renderizações, importações de módulos, I/O síncrono e computações puras produzem o mesmo resultado toda vez que são executados. Componentes que usam apenas essas operações passam por prerendering automaticamente, e a saída deles passa a fazer parte do HTML estático no momento do build.
import fs from 'node:fs'
export default async function Page() {
const constants = await import('./constants.json')
const content = fs.readFileSync('./config.json', 'utf-8')
const items = JSON.parse(content).items ?? []
return (
<div>
<h1>{constants.appName}</h1>
<ul>
{items.map((item) => (
<li key={item.id}>{item.value}</li>
))}
</ul>
</div>
)
}Bom saber: isso inclui consultas a bancos embutidos com APIs síncronas, como
better-sqlite3ou onode:sqliteintegrado do Node.js. Se você precisar de dados por requisição a partir de uma fonte síncrona, chameconnection()antes da consulta.
Algumas APIs assíncronas leem recursos locais que não dependem da requisição recebida, como fontes ou arquivos de configuração. Quando esses recursos devem ser iguais em todas as requisições, leia-os uma vez no escopo do módulo, em vez de durante a renderização.
Se os dados devem ser calculados durante a renderização e reutilizados entre requisições, envolva a leitura com use cache. Se os dados dependem da requisição recebida ou devem mudar com o tempo, leia-os durante a renderização da requisição.
import { readFile } from 'node:fs/promises'
const content = await readFile('./config.json', 'utf-8')
const items = JSON.parse(content).items ?? []
export default function Page() {
return (
<ul>
{items.map((item) => (
<li key={item.id}>{item.value}</li>
))}
</ul>
)
}Neste exemplo, o arquivo de configuração deve ser igual em todas as requisições, então ele é lido uma vez no escopo do módulo. Chamar await readFile() dentro do componente seria tratado como dado sem cache, que precisa estar dentro de use cache ou atrás de um limite <Suspense>. Como esse arquivo não depende da requisição e não deve mudar, o escopo do módulo é a opção mais simples.
Prerendering
No momento do build, o Next.js renderiza a árvore de componentes da sua rota. Cada componente é tratado de acordo com as APIs que usa:
use cache: o resultado é armazenado em cache e incluído no shell estático, desde que seu tempo de vida não seja curto demais<Suspense>: a UI de fallback é incluída no shell estático enquanto o conteúdo chega por streaming no momento da requisição- Valores previsíveis: importações de módulos,
fs.readFileSynce computações puras são concluídos durante o prerendering e entram no shell estático automaticamente - Valores aleatórios e timestamps: use
connection()+<Suspense>para obter um valor único por requisição, ouuse cachepara compartilhar um valor entre usuários
Isso gera um shell estático composto de HTML para carregamentos iniciais de página e de um RSC Payload serializado para navegação no lado do cliente. Assim, o navegador recebe o conteúdo totalmente renderizado instantaneamente, seja quando o usuário acessa a URL diretamente, seja quando vem de outra página. Essa abordagem de renderização se chama Partial Prerendering (PPR), o comportamento padrão com Cache Components.

Todo shell estático gerado pode ser servido diretamente de um CDN, sem passar pelo servidor de origem. Isso torna as navegações diretas instantâneas.
O que acaba no shell estático de uma rota depende do que é conhecido no momento do build. Quando os parâmetros dinâmicos de uma rota são conhecidos, o shell contém esse conteúdo concreto, e qualquer dado sem cache ou de runtime restante continua chegando por streaming atrás do seu fallback de <Suspense>. Quando os parâmetros não são conhecidos, a versão reutilizável e independente da URL é o App Shell: o mesmo shell estático, com as partes específicas de parâmetros deixadas atrás dos fallbacks. A Regeneração Estática Incremental preenche as versões concretas após a primeira visita.
O Next.js exige que você trate explicitamente os componentes que não conseguem ser concluídos durante o prerendering. Ele exibe um insight de validação no overlay de desenvolvimento e no console do dev server, que nomeia a rota e aponta as correções (armazenar o acesso em cache, mover o acesso para dentro de um limite <Suspense> ou tirar a rota dessa validação). Essa validação garante que cada rota produza um shell estático, para que as visitas diretas continuem instantâneas.

🎥 Assista: por que o Partial Prerendering e como ele funciona → YouTube (10 minutos).
Maximizar o shell estático
Quanto mais profundo estiver o trabalho assíncrono na árvore, mais da página pode passar por prerendering. Este é o padrão estrutural que o Cache Components favorece: uma prática geral que vale aplicar em todo lugar, e a base para a navegação instantânea e o prefetching que vêm a seguir. Ele se aplica a todas as APIs de runtime e a operações assíncronas, como buscas de dados.
Considere um layout que desestrutura params no nível superior:
export default async function Layout({
children,
params,
}: LayoutProps<'/shop/[slug]'>) {
const { slug } = await params
return (
<div>
<Sidebar />
<h1>{slug}</h1>
{children}
</div>
)
}Se esse parâmetro for dinâmico (não fornecido por generateStaticParams), ele é um dado de runtime e o layout não pode passar por prerendering.
No entanto, muitas vezes é possível ler o valor do parâmetro mais abaixo na árvore. Em vez de aguardar no nível do layout, passe a promise de params para baixo e aguarde ali:
import { Suspense } from 'react'
// Not async: this layout never awaits params
export default function Layout({
children,
params,
}: LayoutProps<'/shop/[slug]'>) {
return (
<div>
<Sidebar />
<Suspense fallback={<h1>Loading...</h1>}>
{/* await happens inside the boundary, so the shell still renders */}
{params.then(({ slug }) => (
<SlugHeading slug={slug} />
))}
</Suspense>
{children}
</div>
)
}
function SlugHeading({ slug }: { slug: string }) {
return <h1>{slug}</h1>
}Agora <Sidebar />, {children} e o fallback do Suspense fazem parte do shell estático. Apenas SlugHeading chega por streaming no momento da requisição. Você também pode passar a promise inteira de params e aguardá-la no componente filho.
O mesmo princípio vale para cookies(), headers(), searchParams e buscas de dados. Veja Reutilizando dados com React.cache para um padrão relacionado.
Para um fluxo completo, veja Otimizando o shell estático.
Navegação instantânea
Cache Components foi lançado na 16.0.0 com verificação de que visitas diretas a uma rota produzem um shell estático. Navegações no cliente são diferentes: um limite <Suspense> que cobre uma visita direta pode não fazer parte da renderização durante uma transição. Acertar essa estrutura é mais fácil quando o framework ajuda. Agora Cache Components também valida essas navegações, oferecendo insights e erros que orientam você a tornar instantâneas as navegações para a rota. Por exemplo, envolva os dados em <Suspense>, armazene-os em cache com use cache ou mova o ponto em que o acesso acontece.
Leia o guia de navegação instantânea para exemplos e ferramentas de inspeção.
Prefetching
Com o Partial Prefetching habilitado, o router faz prefetch do App Shell de cada rota por padrão. O App Shell inclui conteúdo estático e dados de sessão derivados de cookies() e headers(). Para também fazer prefetch de conteúdo em cache que depende de dados da URL de um link, como searchParams ou params dinâmicos, defina prefetch={true} nesse link.
Com o <Link prefetch={true}> apontando para uma rota com Partial Prefetching, o Next.js renderiza novamente a árvore de componentes dessa rota no momento do prefetch, agora com a URL de destino resolvida. As mesmas regras se aplicam, mas mais da árvore é resolvida, já que searchParams e params estão no escopo:
use cachechamado com valores extraídos de APIs de runtime (passados como argumentos) entra no prefetch do linkuse cache: privateexecuta no servidor, lê dados de runtime diretamente e armazena o resultado no navegador como parte do prefetch do link- Os fallbacks de
<Suspense>permanecem na UI do prefetch enquanto o conteúdo sem cache chega por streaming no momento da requisição
Esse prefetch por link inclui conteúdo em cache que é resolvido depois que a URL de destino é conhecida. Ele custa uma invocação do servidor por link com prefetch.
Por exemplo, considere uma página de busca que lê searchParams da URL:
import { Suspense } from 'react'
export default function SearchPage(props: PageProps<'/search'>) {
return (
<Suspense fallback={<p>Loading results...</p>}>
<Results searchParams={props.searchParams} />
</Suspense>
)
}
async function Results({
searchParams,
}: Pick<PageProps<'/search'>, 'searchParams'>) {
const { q } = await searchParams
const results = await search(q)
return (
<ul>
{results.map((result) => (
<li key={result.id}>{result.title}</li>
))}
</ul>
)
}
async function search(query: string | string[] | undefined) {
'use cache'
return db.search(query)
}Em uma visita direta, <Results> chega por streaming atrás do fallback.
Quando um <Link> para /search?q=shoes recebe prefetch, o framework resolve searchParams a partir da URL do link, então o resultado em cache de search é incluído no prerendering de runtime antes do clique. O navegador então reutiliza esse resultado até que o tempo stale passe ou os searchParams mudem.
Veja Adotando Partial Prefetching para entender como o prefetch de <Link> se comporta e como adotá-lo.
Veja o guia de otimização de prefetching para padrões completos e a referência de prefetch para todos os modos.
Onde o conteúdo em cache é armazenado
A saída de uma função em cache é serializada em um RSC payload, no momento do build ou em runtime. Esse payload é a base de todo o resto. O Next.js o renderiza em HTML, o mantém em um armazenamento do servidor ou remoto, ou o envia ao navegador, e o cacheLife define por quanto tempo cada cópia permanece atual:
- Saída do prerendering. O payload é renderizado em HTML, e o HTML e o RSC payload são armazenados em disco ao hospedar por conta própria, ou no armazenamento durável da sua plataforma atrás de um CDN. Uma visita direta recebe o HTML, e uma navegação no cliente recebe o RSC payload. Juntos, eles formam o shell estático no build e a página concreta depois de uma atualização por ISR, com
revalidateeexpirecontrolando quando ela é reconstruída. - Armazenamento compartilhado. Por padrão, o resultado fica em um armazenamento em memória por instância, que é efêmero em ambientes serverless.
use cache: remoteo move para um cache handler durável, compartilhado entre instâncias. É uma ida e volta pela rede que só compensa com uma taxa de acerto alta. - Navegador. O payload é incluído no RSC enviado para uma navegação no cliente ou prefetch, e o navegador o mantém atual durante a janela
stale. Resultados deuse cache: privatevivem apenas aqui.
Bom saber: um App Shell que lê
cookies()ouheaders()é específico da sessão e fica em cache por sessão no cliente, não no cache compartilhado do servidor.
Todos esses armazenamentos têm escopo de um único deploy. Um novo deploy começa do zero, novos prerenderings são construídos, e as entradas de use cache não são transferidas, nem mesmo as de remote duráveis, porque a chave de cache inclui o build id. Veja Considerações de cache em runtime para o comportamento por ambiente e Hospedagem própria para configurar o cache do servidor.
Regeneração Estática Incremental
Em uma rota com segmentos de parâmetro dinâmicos, generateStaticParams faz prerendering das URLs que você listar no momento do build. Qualquer outra URL recebe o App Shell instantaneamente, depois é atualizada em segundo plano com seus parâmetros agora conhecidos e armazenada em cache para o próximo visitante.
Veja ISR com Cache Components para o passo a passo completo.
Bots e crawlers
Com o Partial Prerendering, os metadados podem ser dinâmicos enquanto o restante da página passa por prerendering e vira um shell estático. O shell é servido imediatamente, e os metadados chegam por streaming depois. Alguns bots e crawlers não conseguem lidar com isso e precisam ver os metadados incluídos na tag <head> do documento. O Next.js os detecta pelo user agent, ignora o shell estático e renderiza a página dinamicamente no momento da requisição.
As fontes de dados disponíveis durante o prerendering no build também precisam estar disponíveis no momento da requisição. Caso contrário, a renderização pode falhar, e esses bots recebem um erro 500. Veja Bots e crawlers no guia de Streaming para saber quais user agents são cobertos e como alterar a lista.
Próximos passos
Saiba mais sobre revalidação e as APIs mencionadas nesta página.