cacheLife (next.config.js)

Core Idea

The cacheLife config object in next.config.js defines custom, named cache profiles (stale/revalidate/expire) that the cacheLife() function consumes inside use cache scopes.

Key Concepts

• cacheLife config object: maps a profile name (e.g. blog) to { stale, revalidate, expire }, set alongside cacheComponents: true.
• Built-in profile override: you can redefine default, seconds, minutes, hours, days, weeks, or max by declaring a profile with the same name.
• stale: how long the client caches a value without checking the server (optional).
• revalidate: how often the server refreshes the cache; stale values may serve while revalidating (optional).
• expire: max duration a value can stay stale before switching to dynamic (optional, must be > revalidate).

Code Examples

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {
    blog: {
      stale: 3600, // 1 hour
      revalidate: 900, // 15 minutes
      expire: 86400, // 1 day
    },
  },
}

export default nextConfig

• O que demonstra: definir um profile customizado blog no next.config.ts.

import { cacheLife } from 'next/cache'

export async function getCachedData() {
  'use cache'
  cacheLife('blog')
  const res = await fetch('https://api.example.com/data')
  const data = await res.json()
  return data
}

• O que demonstra: consumir o profile blog dentro de uma função com use cache.

Reference Tables

Property	Value	Description	Requirement
stale	number	duração que o cliente cacheia sem checar o servidor	Optional
revalidate	number	frequência de refresh do cache no servidor	Optional
expire	number	duração máxima de valor stale antes de virar dinâmico	Optional, deve ser maior que revalidate

Anti-patterns

• Definir expire menor ou igual a revalidate: viola o requisito documentado (expire deve ser maior).

Key Takeaways

1. Requer cacheComponents: true habilitado para funcionar.
2. Profiles ficam disponíveis via cacheLife('nome') dentro de 'use cache'.
3. Redefinir um nome built-in (default, seconds, etc.) sobrescreve o comportamento padrão dele globalmente.

Connects To

• use cache: diretiva onde cacheLife() é chamado.
• cacheComponents: pré-requisito pra esta config funcionar.
• cacheHandlers: outra config de cache relacionada, controla storage em vez de duração.