Capítulo 43 de 59

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:

  1. 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.
  2. Previsibilidade reduzida: Requisições POST e 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, GET handlers 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 via cacheTag seja 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:

  1. 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`)`).
  2. 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.
  3. 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.