Entenda Componentes de Cache no Next.js

O modelo de cache do Next.js 16 por trás das Navegações Instantâneas. Aprenda a usar use cache, cacheLife e cacheTag, e por que os dados são dinâmicos por padrão.

Se você já trabalhou com o App Router do Next.js, provavelmente já passou algum tempo rastreando por que uma rota foi armazenada em cache quando você não pediu, ou por que ela foi executada dinamicamente quando você esperava que fosse estática. O cache estava ativado por padrão e era, na maior parte, invisível no seu código.

Os Componentes de Cache, introduzidos no Next.js 16, invertem esse padrão. Os dados são dinâmicos e executados em cada requisição, a menos que você os armazene em cache com a diretiva "use cache", tornando o cache uma escolha que você faz no código. Uma listagem de produtos parece a mesma para todos, então pode ser armazenada em cache, enquanto o carrinho de um usuário logado precisa ser executado novamente a cada vez. Os Componentes de Cache são a forma de dizer ao Next.js qual é qual. O post Our Journey with Caching aborda como o padrão antigo evoluiu e por que está mudando, e o lançamento do Next.js 16.3 Instant Navigations é construído diretamente sobre este modelo.

Neste post, vamos percorrer os conceitos usando uma única página de loja como exemplo contínuo, desde o cache do primeiro componente até a invalidação sob demanda. Presume-se que você esteja confortável com Server Components e Suspense. Para uma recapitulação, veja React Frameworks and Server-Side Features e React Server Components in Practice.

Ativando a funcionalidade

Você ativa os Componentes de Cache com uma única flag no seu arquivo de configuração do Next.js:

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;

Isso altera o padrão para toda a sua aplicação: todo acesso a dados é dinâmico até que você o armazene em cache. Também substitui as opções mais antigas dynamicIO, useCache e ppr, que agora fazem parte desta única configuração. Como altera o padrão em toda a aplicação de uma só vez, ativá-lo em um projeto existente é uma migração, não apenas uma alternância rápida.

Aqui está a página com a qual trabalharemos, a página inicial de uma loja. Ela busca o catálogo de produtos e um conjunto de recomendações personalizadas:

// app/page.tsx
export default async function StorePage() {
  const products = await getProducts();
  return (
    <main>
      <h1>Loja</h1>
      <ProductGrid products={products} />
      <Recommendations />
    </main>
  );
}

Sob o modelo antigo, esta página seria executada e se tornaria estática ou dinâmica dependendo do que getProducts fazia internamente. Com os Componentes de Cache ativados, ela não será renderizada silenciosamente. Em desenvolvimento, o Next.js sinaliza que getProducts lê dados não armazenados em cache fora de um limite de Suspense, portanto a rota não pode ser pré-renderizada, e oferece três maneiras de resolver isso.

Nada no código diz se o resultado pode ser reutilizado ou precisa ser buscado por requisição, e o framework não vai adivinhar. Então, ele pede que você decida.

Transmitir, Armazenar em Cache ou Bloquear

Cada parte de dados que uma rota aguarda é tratada de uma das três maneiras:

• Transmita com <Suspense>. O usuário vê um fallback imediatamente, e o conteúdo real é transmitido quando é resolvido.
• Armazene em cache com "use cache". O resultado é reutilizado entre requisições, então já está lá quando a página renderiza.
• Bloqueie com export const instant = false. A rota aguarda o servidor terminar antes de renderizar qualquer coisa.

Transmitir e Armazenar em Cache permitem que a página mostre algo assim que carrega, seja um fallback de carregamento ou conteúdo previamente em cache. Bloquear é a opção de exclusão. Use-o para uma rota onde você prefere esperar pelo servidor a mostrar um esqueleto primeiro, como um post de blog que não deve exibir um skeleton.

Nossa página de loja tem duas fontes de dados que requerem respostas diferentes. O catálogo é o mesmo para todos os visitantes, então vamos armazená-lo em cache. As recomendações são por usuário e precisam ser executadas em cada requisição, então vamos transmiti-las atrás de um fallback.

Para armazenar em cache o catálogo, retiramos sua busca da página e a colocamos em seu próprio componente Products. Isso dá ao "use cache" um escopo para atuar e permite que a página renderize o catálogo e as recomendações como partes separadas:

// app/page.tsx
import { Suspense } from 'react';

export default function StorePage() {
  return (
    <main>
      <h1>Loja</h1>
      <Products />
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Recommendations />
      </Suspense>
    </main>
  );
}

async function Products() {
  'use cache';
  const products = await getProducts();
  return <ProductGrid products={products} />;
}

O erro desapareceu e a página agora é renderizada em duas camadas. O cabeçalho e a grade de produtos são pré-renderizados: o Next.js calcula seu HTML antes da requisição e o envia imediatamente como um shell. As recomendações são executadas por requisição e transmitidas atrás do esqueleto. O usuário vê o catálogo imediatamente, em vez de uma tela em branco enquanto a consulta mais lenta termina.

Como o shell não depende da requisição, ele também pode ser armazenado em cache em uma CDN e servido próximo ao usuário, sem ida e volta ao seu servidor. Apenas as recomendações precisam do servidor em cada requisição.

Essa divisão em duas camadas é a Pré-renderização Parcial (PPR). Costumava ser uma flag experimental separada. Agora é o modelo de renderização sobre o qual os Componentes de Cache são construídos, então você o obtém sem configurar nada.

A diretiva use cache

Armazenamos Products em cache colocando "use cache" no topo do componente. Como as outras diretivas do React, "use client" e "use server", é uma string no topo de um escopo que altera a forma como o código dentro dele é tratado. Funciona em três níveis, dependendo de quanto você deseja armazenar em cache.

No topo de um arquivo, cada exportação é armazenada em cache. Esta é a versão de página inteira, para páginas sem dados por requisição:

// app/about/page.tsx
'use cache';

export default async function AboutPage() {
  const team = await getTeamMembers();
  return <TeamList members={team} />;
}

Em um único componente, como Products acima, quando apenas parte de uma página deve ser armazenada em cache:

async function Products() {
  'use cache';
  const products = await getProducts();
  return <ProductGrid products={products} />;
}

Ou em uma função assíncrona simples, para armazenar em cache uma consulta de onde quer que seja chamada:

export async function getProducts() {
  'use cache';
  return db.product.findMany();
}

O nível de função geralmente é o mais útil. Se várias páginas chamam getProducts, elas compartilham uma única entrada de cache, e os componentes que a chamam não precisam saber que ela está em cache.

Na primeira vez que uma função em cache é executada, o Next.js armazena o resultado. A próxima chamada com as mesmas entradas retorna o valor armazenado em vez de executar a função novamente.

Você nunca escreve a chave de cache manualmente. O Next.js a deriva da identidade da função e de seus argumentos serializados, portanto, chamar uma função em cache com argumentos diferentes armazena em cache cada variante separadamente:

async function getProduct(slug: string) {
  'use cache';
  return db.product.findUnique({ where: { slug } });
}

Chamar getProduct('sapato') e getProduct('chapéu') produz duas entradas separadas, porque o argumento faz parte da chave. Variáveis de fechamento também contam, portanto, se a função lê um valor de um escopo externo, esse valor se torna parte da chave também.

Como a chave vem dos argumentos, esses argumentos precisam ser serializáveis: primitivos, objetos simples, arrays, Date, Map e Set. O valor de retorno usa a mesma serialização que o React já usa para a saída do Server Component, e é por isso que Products pode retornar JSX e não apenas dados simples.

Definindo um tempo de vida com cacheLife

Por quanto tempo o catálogo em cache é válido? Por padrão, uma entrada permanece atualizada por um período de tempo definido, mas geralmente você vai querer definir a sua própria. É para isso que serve o cacheLife. Chame-o dentro de um escopo use cache com um perfil nomeado:

import { cacheLife } from 'next/cache';

export async function getProducts() {
  'use cache';
  cacheLife('hours');
  return db.product.findMany();
}

Um perfil agrupa três valores:

• stale é por quanto tempo o cliente reutiliza a entrada antes de verificar com o servidor novamente.
• revalidate é a frequência com que o servidor atualiza a entrada em segundo plano.
• expire é o limite máximo, o ponto em que a entrada é muito antiga para ser servida e é regenerada sob demanda.

Os perfis integrados variam de seconds a max. O perfil hours acima é atualizado em segundo plano a cada hora e expira após um dia, o que se adequa a um catálogo que muda algumas vezes por semana. Quando nenhum perfil nomeado se encaixa, passe números exatos em segundos:

cacheLife({ stale: 300, revalidate: 900, expire: 3600 });

Se você já usou o React Query, stale é a mesma ideia de staleTime: por quanto tempo um valor é tratado como atualizado antes de valer a pena buscá-lo novamente. A janela revalidate é como a atualização em segundo plano que você obtém de uma biblioteca como o SWR. A diferença é que isso é executado no servidor e se aplica a cada função em cache, permitindo ajustar cada dado individualmente em vez de definir uma política única para toda a rota.

Invalidando com cacheTag

A expiração baseada em tempo funciona para dados que mudam gradualmente, mas não para dados que mudam em um momento conhecido. Quando alguém da equipe renomeia um produto no painel administrativo, o catálogo não deve continuar mostrando o nome antigo por até uma hora.

Para isso, marque a entrada com cacheTag onde você lê os dados e, em seguida, limpe a tag quando você escrever. Se você já usou o React Query, esta é a versão do lado do servidor de invalidar uma consulta por chave com queryClient.invalidateQueries({ queryKey: ['products'] }).

Marque os dados onde você os lê:

import { cacheLife, cacheTag } from 'next/cache';

export async function getProducts() {
  'use cache';
  cacheLife('hours');
  cacheTag('products');
  return db.product.findMany();
}

Em seguida, invalide a tag a partir da Server Action que realiza a escrita:

'use server';
import { revalidateTag } from 'next/cache';

export async function renameProduct(id: string, formData: FormData) {
  await db.product.update({
    where: { id },
    data: { name: formData.get('name') },
  });
  revalidateTag('products', 'max');
}

Duas coisas mudaram aqui no Next.js 16. O revalidateTag agora aceita um segundo argumento, um perfil cacheLife que controla como a entrada se comporta após você invalidá-la. E há um novo updateTag para Server Actions, para quando o usuário precisa ver a própria mudança imediatamente, seja na mesma tela ou na próxima:

'use server';
import { updateTag } from 'next/cache';

export async function renameProduct(id: string, formData: FormData) {
  await db.product.update({
    where: { id },
    data: { name: formData.get('name') },
  });
  updateTag('products'); // expira e relê antes da resposta retornar
}

A diferença entre os dois é o momento. updateTag expira a entrada e a relê antes que a resposta retorne, para que o administrador que renomeou o produto veja o novo nome assim que o formulário for enviado. revalidateTag limpa a tag e a atualiza em segundo plano, para que o administrador ainda possa ver o nome antigo por um momento, mas o próximo visitante receba o novo.

Use updateTag para fluxos de leitura-própria-escrita, onde um resultado obsoleto pareceria que a escrita falhou. Use revalidateTag quando um pequeno atraso for aceitável. Ambos limpam a entrada no servidor e no cache do roteador do cliente na mesma chamada.

Lendo cookies e cabeçalhos

Há uma parte da página da loja que falta: as recomendações. Digamos que elas são baseadas em um cookie de região e a consulta é lenta o suficiente para que você queira armazená-la em cache por região. Mover "use cache" para o componente não funciona:

import { cookies } from 'next/headers';

async function Recommendations() {
  'use cache';
  const region = (await cookies()).get('region')?.value; // Erro
  const products = await getRecommendations(region);
  return <ProductGrid products={products} />;
}

Um escopo use cache não pode chamar cookies(), headers() ou ler searchParams, e isso falha em tempo de construção ou requisição. A razão é que uma entrada de cache é compartilhada entre requisições, enquanto esses valores são diferentes para cada requisição. Se você pudesse ler um cookie dentro do cache, a região do primeiro usuário seria incorporada em uma entrada que todos os outros receberiam depois. A regra impede que você vaze acidentalmente dados de um usuário para outro.

A correção é ler o valor da requisição em uma função de busca de dados não armazenada em cache e passá-lo para a função em cache como um argumento. Ele se torna parte da chave de cache, portanto, cada região tem sua própria entrada:

import { cookies } from 'next/headers';

async function Recommendations() {
  const products = await getRecommendations();
  return <ProductGrid products={products} />;
}

async function getRecommendations() {
  const region = (await cookies()).get('region')?.value ?? 'us';
  return getRegionRecommendations(region);
}

async function getRegionRecommendations(region: string) {
  'use cache';
  return db.recommendations.findMany({ where: { region } });
}

A leitura do cookie agora acontece em getRecommendations, que não está em cache e é executada em cada requisição, então Recommendations permanece dentro do limite de Suspense na página. A região é passada para getRegionRecommendations como um argumento, de modo que a consulta cara por trás dela seja armazenada em cache por região em vez de ser executada para cada visitante.

Se você não puder refatorar para passar os valores, existe a variante "use cache: private" que armazena em cache por usuário e pode ler as APIs de requisição. A maioria dos códigos não precisará dela.

O que você não precisa mais

Parte do que tornava o modelo antigo difícil era o número de APIs que controlavam o cache, cada uma com suas próprias regras. Os Componentes de Cache removem a maior parte dessa superfície. Aqui estão as APIs que você para de usar quando a flag está ativada:

Não é mais necessário	O que usar em vez disso
export const dynamic = 'force-dynamic'	Nada, dinâmico é o padrão
export const dynamic = 'force-static'	'use cache' com cacheLife('max')
export const revalidate = 3600	cacheLife('hours') em um escopo use cache
fetch(url, { next: { revalidate, tags } })	'use cache' com cacheLife e cacheTag
unstable_cache(fn, keys, { tags })	'use cache' com cacheTag e sem chaves manuais
unstable_noStore()	Nada, sem cache por padrão
experimental_ppr = true	Nada, PPR é integrado

As camadas antigas de fetch e unstable_cache ainda funcionam se você as mantiver no lugar, portanto, nada força uma reescrita. Uma diferença a ter em mente: esses caches mais antigos persistiam entre implantações, enquanto o use cache armazena entradas em memória por padrão, portanto, em serverless, eles são limitados a uma única instância. Para cache durável ou compartilhado, você configura um manipulador de cache ou usa "use cache: remote".

Como a flag altera o padrão em toda a sua aplicação de uma só vez, adotá-la em um projeto existente requer alguns cuidados. O Next.js oferece uma habilidade de agente que permite que um agente de codificação migre um aplicativo uma subárvore de cada vez. Os erros de desenvolvimento também são escritos para que um agente atue sobre eles, abordado em Next.js 16.3: AI Improvements.

Como isso torna a navegação instantânea

O shell da página da loja, o cabeçalho e o catálogo em cache, é o mesmo para todos os visitantes. Por ser compartilhado, o Next.js pode pré-buscá-lo e manter uma cópia no cliente. Quando um usuário clica em um link para a loja, o roteador renderiza esse shell sem uma ida e volta ao servidor, e as recomendações são transmitidas atrás de seu esqueleto, assim como em um carregamento inicial. O servidor ainda produz o HTML inicial para a primeira visita, portanto, a primeira pintura e o SEO permanecem inalterados.

Isso são as Navegações Instantâneas, em pré-visualização no Next.js 16.3. Junto com elas, um novo modo de Pré-busca Parcial altera o que o roteador busca: em vez de uma requisição de pré-busca por link, o Next.js pré-busca um shell reutilizável por rota e o armazena em cache no cliente. Esse shell é o mesmo que suas chamadas "use cache" pré-renderizam. O anúncio cobre o resto, incluindo o auxiliar de teste instant() para Playwright para capturar regressões e o Inspetor de Navegação para ver o que cada rota pré-busca.

Principais Conclusões

• Componentes de Cache invertem o padrão. Com cacheComponents: true, os dados são dinâmicos por padrão e você opta pelo cache com "use cache".
• Os dados aguardados são transmitidos, armazenados em cache ou bloqueados. Envolva-os em <Suspense>, armazene-os em cache com "use cache" ou opte pela exclusão da rota com export const instant = false. O Next.js sinaliza qualquer coisa indecisa em desenvolvimento.
• "use cache" funciona no nível do arquivo, componente ou função. O Next.js deriva a chave de cache da função e seus argumentos serializados, portanto, você nunca precisa escrever uma.
• cacheLife define o tempo de vida, cacheTag lida com a invalidação. Revalide com um temporizador usando um perfil ou limpe uma tag sob demanda com revalidateTag e updateTag.
• Escopos em cache não podem ler APIs específicas de requisição. Leia cookies(), headers() e searchParams fora do cache e passe os valores para dentro.

Conclusão

A página da loja começou como um componente assíncrono sobre o qual o Next.js não conseguia tomar uma decisão. Dividi-la em um catálogo em cache e recomendações transmitidas exigiu duas pequenas alterações, e cada necessidade posterior, seja um tempo de vida, invalidação sob demanda ou um cache por região, tinha uma API para usar. Os dados permanecem dinâmicos até que você os armazene em cache, e o Next.js sinaliza o que ainda precisa de uma decisão em desenvolvimento, para que você saiba o que é estático e o que é dinâmico em vez de descobrir em produção. O mesmo shell pré-renderizado que acelera o carregamento inicial é o que o cliente reutiliza para tornar a navegação instantânea.

Você pode ver tudo isso em um aplicativo real. O Next Beats é um player de música construído na Visualização do Next.js 16.3 com os Componentes de Cache ativados, e o código-fonte está no GitHub. Se você está no Next.js 16, tente migrar um de seus próprios aplicativos em um branch, usando a habilidade de adoção para trabalhar através dele uma subárvore de cada vez e veja como ele é renderizado sob o novo modelo.

Fontes:

• Documentação do Next.js > Cache Components
• Documentação do Next.js > use cache
• Documentação do Next.js > cacheComponents
• Documentação do Next.js > cacheLife
• Documentação do Next.js > cacheTag
• Documentação do Next.js > updateTag
• Next.js 16.3: Instant Navigations
• Next.js 16.3: AI Improvements
• Next.js Blog > Our Journey with Caching

---

Perguntas Frequentes (FAQ) sobre Componentes de Cache no Next.js 16

Respostas concisas para as dúvidas mais comuns sobre o novo modelo de cache, diretivas e práticas recomendadas.

---