Next.js: Cache Components & use cache

// app/dashboard/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function getUserData() {
  'use cache'
  cacheTag('user-data')
  cacheLife({ stale: 300, revalidate: 600 })

  const user = await db.user.findUnique({ where: { id: 1 } })  // Executa apenas uma vez
  return user
}

export default async function DashboardPage() {
  const user = await getUserData()  // A primeira chamada executa uma consulta ao banco de dados
  // Chamadas subsequentes retornarão o resultado em cache diretamente.

  return (
    <div>
      <UserAvatar user={user} />
      <UserGreeting user={user} />
      <UserStats user={user} />
      <UserNotifications user={user} />
    </div>
  )
}

// app/cache-demo/actions.ts
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

export async function getExpensiveData(id: string) {
  'use cache'
  cacheTag('expensive', `id-${id}`)         // Etiquetagem
  cacheLife({ stale: 60, revalidate: 300 }) // Retorna stale em 60 segundos, Tenta novamente em 300 segundos

  // Todas as operações dentro desta função são cacheadas.
  const result = await db.query(...)
  return result
}

Renderiza a interface do componente getExpensiveData.

// app/cache-basic/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function getServerTime() {
  'use cache'
  cacheTag('server-time')
  cacheLife({ stale: 10, revalidate: 30 })

  // Simula operação demorada
  await new Promise(resolve => setTimeout(resolve, 1000))
  return { time: new Date().toISOString(), server: process.env.HOSTNAME ?? 'local' }
}

export default async function CacheBasicPage() {
  const [t1, t2, t3] = await Promise.all([
    getServerTime(),
    getServerTime(),
    getServerTime(),
  ])

  return (
    <div>
      <h1>use cache — Básico</h1>
      <p>Chamada 1: {t1.time}</p>
      <p>Chamada 2: {t2.time}</p>
      <p>Chamada 3: {t3.time}</p>
      <p><em>Todas as três chamadas retornaram o mesmo resultado em cache (sem computação duplicada)</em></p>
    </div>
  )
}

Chamada 1: 2026-07-06T10:00:00.000Z
Chamada 2: 2026-07-06T10:00:00.000Z ← Mesmo timestamp (cache hit)
Chamada 3: 2026-07-06T10:00:00.000Z ← Mesmo timestamp (cache hit)

Chamada 1: 2026-07-06T10:00:00.000Z
Chamada 2: 2026-07-06T10:00:00.000Z  ← Milissegundos de sobreposição de cache
Chamada 3: 2026-07-06T10:00:00.000Z

// app/products/[id]/page.tsx
import { unstable_cacheTag as cacheTag } from 'next/cache'

export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await getProduct(params.id)
  return <ProductView product={product} />
}

async function getProduct(id: string) {
  'use cache'
  cacheTag('products', `product-${id}`)  // Tags dinâmicas baseadas em parâmetros
  return fetch(`https://api.example.com/products/${id}`).then(r => r.json())
}

Obtém dados e renderiza o resultado.

// app/cache-strategy/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function getUserProfile(userId: number) {
  'use cache'
  cacheTag('users', `user-${userId}`)
  cacheLife({ stale: 120, revalidate: 600 })  // 2 minutos stale, 10 minutos revalidate
  return fetch(`https://jsonplaceholder.typicode.com/users/${userId}`).then(r => r.json())
}

async function getUserPosts(userId: number) {
  'use cache'
  cacheTag('posts', `user-posts-${userId}`)
  cacheLife({ stale: 60, revalidate: 300 })
  return fetch(`https://jsonplaceholder.typicode.com/users/${userId}/posts`).then(r => r.json())
}

export default async function CacheStrategyPage() {
  const [profile, posts] = await Promise.all([
    getUserProfile(1),
    getUserPosts(1),
  ])

  return (
    <div>
      <h1>{profile.name}</h1>
      <p>Email: {profile.email}</p>
      <h2>Posts ({posts.length})</h2>
      <ul>{posts.map((p: any) => <li key={p.id}>{p.title}</li>)}</ul>
    </div>
  )
}

Obtém dados no lado do servidor e renderiza uma lista de itens a partir dos dados.

O componente renderiza a UI descrita no navegador.

// app/cache-invalidation/page.tsx
import { unstable_cacheTag as cacheTag, revalidateTag } from 'next/cache'

async function getTaskList() {
  'use cache'
  cacheTag('tasks')
  return fetch('https://jsonplaceholder.typicode.com/todos?_limit=5').then(r => r.json())
}

export default async function CacheInvalidationPage() {
  const tasks = await getTaskList()
  return (
    <div>
      <h1>Lista de Tarefas</h1>
      <ul>{tasks.map((t: any) => <li key={t.id}>{t.title}</li>)}</ul>
      <form action={async () => {
        'use server'
        revalidateTag('tasks')  // Clique no botão para atualizar o cache da lista de tarefas imediatamente
      }}>
        <button type="submit">Atualizar Tarefas</button>
      </form>
    </div>
  )
}

Um formulário com campos de entrada e um botão de envio.
Ao enviar, a server action processa os dados e invalida as tags de cache relevantes.
Texto visível: Lista de Tarefas

A página renderiza conforme descrito acima, com a UI atualizando de acordo com o comportamento descrito.

// app/cache-combo/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

// 1. fetch cache: Chamar API Externa
async function getExternalPosts() {
  return fetch('https://jsonplaceholder.typicode.com/posts', {
    next: { tags: ['external-posts'], revalidate: 300 }
  }).then(r => r.json())
}

// 2. use cache: Dados processados
async function getProcessedPosts() {
  'use cache'
  cacheTag('processed-posts')
  cacheLife({ stale: 60, revalidate: 600 })

  const raw = await getExternalPosts()  // Dependência do fetch cache
  return (raw as any[]).map((p: any) => ({
    id: p.id,
    title: p.title.toUpperCase(),
    summary: p.body.slice(0, 100),
  }))
}

export default async function CacheComboPage() {
  const posts = await getProcessedPosts()

  return (
    <div>
      <h1>Posts Processados ({posts.length})</h1>
      <ul>{posts.map((p: any) => (
        <li key={p.id}><strong>{p.title}</strong><p>{p.summary}</p></li>
      ))}</ul>
    </div>
  )
}

Obtém dados no lado do servidor e renderiza uma lista de itens a partir dos dados.

// app/cache-system/page.tsx — Uma Arquitetura de Cache Completa
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

// ======== Camada de Dados (Cache Explícito com use cache) ========
type User = { id: number; name: string; email: string }
type Post = { id: number; title: string; body: string }

async function getUsers(): Promise<User[]> {
  'use cache'
  cacheTag('users')
  cacheLife({ stale: 120, revalidate: 600 })
  return fetch('https://jsonplaceholder.typicode.com/users').then(r => r.json())
}

async function getUserPosts(userId: number): Promise<Post[]> {
  'use cache'
  cacheTag('posts', `user-posts-${userId}`)
  cacheLife({ stale: 60, revalidate: 300 })
  return fetch(`https://jsonplaceholder.typicode.com/users/${userId}/posts`).then(r => r.json())
}

async function getStats(users: User[]) {
  'use cache'
  cacheTag('stats')
  cacheLife({ stale: 300, revalidate: 1800 })
  return {
    totalUsers: users.length,
    avgNameLength: users.reduce((s, u) => s + u.name.length, 0) / users.length,
  }
}

// ======== Componentes da Página ========
export default async function CacheSystemPage() {
  const users = await getUsers()
  const stats = await getStats(users)

  return (
    <div style={{ maxWidth: 900, margin: '0 auto', padding: 24 }}>
      <h1>Gerenciamento de Usuários</h1>
      <StatsCard stats={stats} />
      <div style={{ display: 'grid', gap: 16, marginTop: 24 }}>
        {users.map(user => (
          <UserCard key={user.id} user={user} />
        ))}
      </div>
    </div>
  )
}

// ======== Componente filho (Cache Independente) ========
async function UserCard({ user }: { user: User }) {
  const posts = await getUserPosts(user.id)
  return (
    <div style={{ border: '1px solid #ddd', borderRadius: 8, padding: 16 }}>
      <h2>{user.name}</h2>
      <p style={{ color: '#666' }}>{user.email}</p>
      <details>
        <summary>Posts ({posts.length})</summary>
        <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
      </details>
    </div>
  )
}

function StatsCard({ stats }: { stats: { totalUsers: number; avgNameLength: number } }) {
  return (
    <div style={{ background: '#f0f4ff', borderRadius: 8, padding: 16, display: 'flex', gap: 32 }}>
      <div><strong>Total de Usuários</strong><p style={{ fontSize: 24 }}>{stats.totalUsers}</p></div>
      <div><strong>Tamanho Médio do Nome</strong><p style={{ fontSize: 24 }}>{stats.avgNameLength.toFixed(1)}</p></div>
    </div>
  )
}

// ======== Tarefas Administrativas ========
// app/cache-system/actions.ts
'use server'
import { revalidateTag } from 'next/cache'

export async function refreshUserData() {
  revalidateTag('users')        // Atualiza a lista de usuários
}

export async function refreshPosts(userId: number) {
  revalidateTag(`user-posts-${userId}`)  // Atualiza os posts de um usuário específico
}

export async function refreshAll() {
  revalidateTag('users')
  revalidateTag('posts')
  revalidateTag('stats')
}

// app/cache-system/admin-button.tsx
'use client'
export function AdminControls() {
  return (
    <div style={{ display: 'flex', gap: 8, margin: '16px 0' }}>
      <form action={async () => {
        const { refreshUserData } = await import('./actions')
        await refreshUserData()
      }}>
        <button type="submit">Atualizar Usuários</button>
      </form>
      <form action={async () => {
        const { refreshAll } = await import('./actions')
        await refreshAll()
      }}>
        <button type="submit">Atualizar Tudo</button>
      </form>
    </div>
  )
}

Um formulário com campos de entrada e um botão de envio.
Ao enviar, a server action processa os dados e invalida as tags de cache relevantes.
Texto visível: Gerenciamento de Usuários

// app/cache-verify/page.tsx — Verificar se houve cache hit
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

let callCount = 0

async function getUniqueId() {
  'use cache'
  cacheTag('unique-id')
  cacheLife({ revalidate: 30 })
  callCount++
  return { id: crypto.randomUUID(), calls: callCount }
}

export default async function CacheVerifyPage() {
  const [a, b, c] = await Promise.all([
    getUniqueId(),
    getUniqueId(),
    getUniqueId(),
  ])

  return (
    <div>
      <h1>Verificação de Cache</h1>
      <p>Resultado A: {a.id} (chamada #{a.calls})</p>
      <p>Resultado B: {b.id} (chamada #{b.calls})</p>
      <p>Resultado C: {c.id} (chamada #{c.calls})</p>
      <p><strong>Mesmo ID + calls = 1 → cache hit</strong></p>
    </div>
  )
}

Conteúdo: Verificação de Cache | Mesmo ID + calls = 1 → cache hit

Resultado A: 550e8400-e29b-41d4-a716-446655440000 (chamada #1)
Resultado B: 550e8400-e29b-41d4-a716-446655440000 (chamada #1)  ← Cache Hit
Resultado C: 550e8400-e29b-41d4-a716-446655440000 (chamada #1)  ← Cache Hit