Cache no Next.js 15: use cache, cacheLife e Invalidação com Supabase
Guia Definitivo de Cache no Next.js 15: use cache, cacheLife e Invalidação com Supabase
O gerenciamento de cache sempre foi um dos tópicos mais debatidos e desafiadores no ecossistema Next.js. Enquanto o Next.js 14 adotava um comportamento agressivo de cache por padrão nas requisições fetch — o que frequentemente surpreendia desenvolvedores com dados desatualizados ou comportamentos difíceis de depurar —, o Next.js 15 introduziu uma revolução arquitetural completa.
O novo paradigma é baseado no princípio de Cache Explícito (Opt-in), liderado pela diretiva "use cache", pelos perfis temporais cacheLife e pela marcação granular com cacheTag.
Neste guia técnico, você compreenderá a fundo como projetar arquiteturas de alta performance e baixo custo de banco de dados, integrando o novo motor de cache da Vercel com a invalidação reativa do Supabase PostgreSQL.
1. A Evolução do Caching: Do Next.js 14 ao Next.js 15
No Next.js 14 e versões anteriores, o modelo de cache era acoplado principalmente ao wrapper global de requisições fetch (next: { revalidate: 60 }) ou à função utilitária unstable_cache.
Essa abordagem apresentava duas limitações críticas:
- Acoplamento a requisições de rede: Se o dado vinha de um ORM, de um SDK (como
@supabase/supabase-js) ou de um cálculo matemático pesado em CPU, não era possível aplicar cache diretamente sem recorrer a abstrações complexas. - Previsibilidade reduzida: Requisições
POSTe rotas dinâmicas alternavam entre comportamentos estáticos e dinâmicos de forma implícita.
O Novo Paradigma no Next.js 15
- Padrão Dinâmico (Uncached by Default): Consultas
fetch,GEThandlers e componentes agora são dinâmicos por padrão, a menos que você declare explicitamente que deseja armazená-los em cache. - Cache em Nível de Função e Componente: A diretiva
"use cache"pode ser aplicada no topo de um arquivo, dentro de um componente Server Component ou no corpo de uma função assíncrona que executa consultas no banco de dados. - Ciclo de Vida Triplo (Stale-While-Revalidate): O tempo de vida do cache agora é definido em três camadas matemáticas: Stale Time (tempo fresco no cliente), Revalidate Time (tempo de regeneração no servidor) e Expire Time (tempo máximo de expiração na CDN).
2. A Diretiva "use cache" na Prática
Para habilitar as novas APIs de cache no Next.js 15, certifique-se de ativar a flag experimental no next.config.ts:
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
experimental: {
useCache: true,
},
};
export default nextConfig;
Aplicando Cache em Consultas do Supabase
Agora é possível armazenar em cache os resultados de consultas diretas ao banco de dados Supabase sem depender do fetch tradicional:
// src/services/catalogService.ts
import { createClient } from "@supabase/supabase-js";
import { cacheLife, cacheTag } from "next/cache";
// Instancia do client anonimo para leitura publica
const supabase = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);
export async function getFeaturedProducts(tenantId: string) {
"use cache";
// Define o perfil de duracao do cache
cacheLife("hours");
// Atribui tags para invalidacao sob demanda
cacheTag("products", `tenant-${tenantId}-products`);
const { data, error } = await supabase
.from("products")
.select("id, name, price, thumbnail_url, stock")
.eq("tenant_id", tenantId)
.eq("is_featured", true)
.order("created_at", { ascending: false });
if (error) {
throw new Error(`Falha ao carregar catalogo: ${error.message}`);
}
return data;
}
3. Dominando cacheLife: Perfis Predefinidos e Customizados
A função cacheLife() substitui a antiga sintaxe numérica de revalidação por uma semântica declarativa muito mais robusta.
Perfis Nativos do Next.js 15:
cacheLife("seconds"): Ideal para dados voláteis de alta frequência (ex: placares, cotações de moedas).cacheLife("minutes"): Adequado para feeds de novidades e métricas operacionais agregadas.cacheLife("hours"): Perfeito para catálogos de e-commerce, posts de blog e listas de produtos.cacheLife("days"): Recomendado para tabelas de preços, landing pages institucionais e documentações técnicas.cacheLife("weeks"): Para recursos quase estáticos que mudam raramente.cacheLife("max"): Cache perpétuo mantido na borda global até que uma invalidação explícita viacacheTagseja disparada.
Criando Perfis Customizados no next.config.ts
Se o seu sistema corporativo possui regras específicas de expiração, você pode definir perfis personalizados:
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
experimental: {
useCache: true,
cacheLife: {
// Perfil customizado para cotacoes de frete e catalogo B2B
b2bCatalog: {
stale: 300, // 5 minutos: servido do cache local do navegador
revalidate: 3600, // 1 hora: a Vercel refaz a pagina em background
expire: 86400, // 24 horas: expira completamente na CDN global
},
},
},
};
export default nextConfig;
E no seu código de serviço:
// src/services/pricingService.ts
import { cacheLife } from "next/cache";
export async function getB2BPricingTable(orgId: string) {
"use cache";
cacheLife("b2bCatalog");
// Executa consulta pesada com calculo de impostos
return fetchTaxAdjustedPrices(orgId);
}
4. Invalidação Cirúrgica com cacheTag e revalidateTag
O grande poder do modelo híbrido Vercel + Supabase surge quando você combina o cache de longa duração na Edge da Vercel com invalidação instantânea acionada pelo PostgreSQL.
Como Funciona o cacheTag:
Dentro de qualquer função ou componente "use cache", você pode associar múltiplas tags conceituais (ex: categoria, ID do usuário, ID da organização ou SKU do produto).
// src/components/ProductCard.tsx
import { cacheLife, cacheTag } from "next/cache";
interface ProductCardProps {
productId: string;
}
export async function ProductCard({ productId }: ProductCardProps) {
"use cache";
cacheLife("days");
cacheTag("products", `product-${productId}`);
const product = await getProductById(productId);
return (
<article className="border rounded-lg p-4 shadow-sm bg-card">
<h3 className="text-lg font-bold">{product.name}</h3>
<p className="text-xl font-semibold text-primary">R$ {product.price}</p>
</article>
);
}
O Route Handler de Revalidação na Vercel
Crie um Route Handler seguro dedicado a receber o webhook disparado pelo Supabase:
// app/api/revalidate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { revalidateTag } from "next/cache";
export async function POST(request: NextRequest) {
const authHeader = request.headers.get("authorization");
// 1. Valida o token secreto compartilhado
if (authHeader !== `Bearer ${process.env.REVALIDATION_SECRET_TOKEN}`) {
return NextResponse.json(
{ error: "Token de autorizacao invalido" },
{ status: 401 }
);
}
const payload = await request.json().catch(() => null);
const tag = payload?.tag;
if (!tag) {
return NextResponse.json(
{ error: "Tag de revalidacao ausente no payload" },
{ status: 400 }
);
}
// 2. Invalida cirurgicamente todos os caches associados a essa tag
revalidateTag(tag);
return NextResponse.json({
revalidated: true,
tag,
timestamp: Date.now(),
});
}
5. Automação Reativa: Database Triggers no Supabase Postgres
Para fechar o elo de ouro da arquitetura, o banco de dados Supabase avisa a Vercel no momento exato em que um registro é alterado ou excluído.
Utilizando a extensão pg_net nativa do Supabase, você cria um trigger assíncrono que não bloqueia as transações SQL:
-- 1. Cria a funcao SQL que despacha o webhook HTTP para a Vercel
CREATE OR REPLACE FUNCTION notify_vercel_revalidation()
RETURNS trigger AS $$
DECLARE
revalidation_secret text := 'SEU_TOKEN_SECRETO_AQUI';
vercel_url text := 'https://seu-dominio.com.br/api/revalidate';
payload jsonb;
BEGIN
-- Monta a tag especifica do produto alterado
payload := jsonb_build_object('tag', 'product-' || NEW.id::text);
-- Dispara requisicao POST assincrona sem onerar a transacao
PERFORM net.http_post(
url := vercel_url,
headers := jsonb_build_object(
'Content-Type', 'application/json',
'Authorization', 'Bearer ' || revalidation_secret
),
body := payload
);
-- Também invalida a tag coletiva da categoria
PERFORM net.http_post(
url := vercel_url,
headers := jsonb_build_object(
'Content-Type', 'application/json',
'Authorization', 'Bearer ' || revalidation_secret
),
body := jsonb_build_object('tag', 'products')
);
RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
-- 2. Conecta o Trigger na tabela de produtos
CREATE TRIGGER on_product_update_revalidate_cache
AFTER UPDATE OR DELETE ON products
FOR EACH ROW
EXECUTE FUNCTION notify_vercel_revalidation();
6. Matriz Comparativa: unstable_cache vs "use cache"
| Característica | Next.js 14 (unstable_cache) |
Next.js 15 ("use cache") |
|---|---|---|
| Escopo de Aplicação | Apenas funções avulsas | Funções, Componentes React e Arquivos |
| Definição Temporal | Número estático em segundos (revalidate: 3600) |
Semântico com cacheLife("hours") |
| Controle Stale-While-Revalidate | Rígido e binário | Flexível (Stale / Revalidate / Expire) |
| Marcação de Tags | Array de strings na inicialização | Função declarativa em tempo de execução cacheTag() |
| Integração com Compilador | Abstração externa | Otimizado nativamente pelo compilador Rust |
| Estabilidade | Experimental / Unstable | Padrão oficial e estratégico do framework |
7. Melhores Práticas e Diretrizes de Segurança
Para garantir a máxima confiabilidade em produção corporativa, siga estas regras arquiteturais:
- Nunca Cacheie Dados Privados sem Namespace de Usuário: Se uma consulta depende do
auth.uid(), incluir a tag genérica pode fazer com que o usuário A visualize os dados do usuário B. Sempre anexe o ID do usuário na tag (ex:cacheTag(\user-${userId}-settings`)`). - Separe Telas de Admin de Telas Públicas: Telas administrativas, dashboards financeiros e relatórios de auditoria devem continuar usando
export const dynamic = "force-dynamic"e consultas sob RLS, conforme documentado no manual de force-dynamic vs páginas públicas. - Monitore a Taxa de Cache Hit na Vercel: Utilize a aba de Analytics da Vercel para inspecionar os cabeçalhos
x-vercel-cache(HIT,STALE,MISS). Uma arquitetura saudável apresenta taxas de HIT superiores a 90% em rotas públicas.
Conclusão: Performance Extrema com Custo Reduzido
A transição para a diretiva "use cache" e os perfis cacheLife no Next.js 15 transforma a forma como construímos aplicações de alto tráfego.
Ao combinar a velocidade das respostas cacheadas na Edge da Vercel com a precisão dos Database Triggers do Supabase Postgres, sua aplicação entrega experiências instantâneas aos usuários finais enquanto mantém as consultas de banco de dados e os custos de infraestrutura no patamar mínimo absoluto.
Se a sua empresa busca modernizar a arquitetura de aplicações Next.js, otimizar custos com requisições de banco ou implementar esteiras de cache de alta performance, conheça minhas soluções de desenvolvimento corporativo ou agende uma análise técnica comigo.