cacheLife

La función cacheLife se utiliza para establecer el tiempo de vida en caché de una función o componente. Debe usarse junto con la directiva use cache y dentro del ámbito de la función o componente.

Uso

Para usar cacheLife, habilite la bandera dynamicIO en su archivo next.config.js:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
  },
}

export default nextConfig

Luego, importe e invoque la función cacheLife dentro del ámbito de la función o componente:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

Referencia

Perfiles de caché predeterminados

Next.js proporciona un conjunto de perfiles de caché modelados en varias escalas de tiempo. Si no especifica un perfil de caché en la función cacheLife junto con la directiva use cache, Next.js aplicará automáticamente el perfil de caché default.

Sin embargo, recomendamos siempre agregar un perfil de caché cuando use la directiva use cache para definir explícitamente el comportamiento del almacenamiento en caché.

Los valores de cadena utilizados para hacer referencia a los perfiles de caché no tienen un significado inherente; en su lugar, sirven como etiquetas semánticas. Esto le permite comprender y administrar mejor su contenido en caché dentro de su base de código.

Nota importante: Actualizar las opciones de configuración staleTimes y expireTime también actualiza las propiedades stale y expire del perfil de caché default.

Perfiles de caché personalizados

Puede configurar perfiles de caché personalizados agregándolos a la opción cacheLife en su archivo next.config.ts.

Los perfiles de caché son objetos que contienen las siguientes propiedades:

La propiedad "stale" difiere de la configuración staleTimes en que controla específicamente el almacenamiento en caché del enrutador del lado del cliente. Mientras que staleTimes es una configuración global que afecta a todas las instancias de datos dinámicos y estáticos, la configuración cacheLife le permite definir tiempos "stale" por función o por ruta.

Nota importante: La propiedad "stale" no establece el encabezado Cache-control: max-age. En su lugar, controla la caché del enrutador del lado del cliente.

Ejemplos

Definición de perfiles de caché reutilizables

Puede crear un perfil de caché reutilizable definiéndolo en su archivo next.config.ts. Elija un nombre que se adapte a su caso de uso y establezca valores para las propiedades stale, revalidate y expire. Puede crear tantos perfiles de caché personalizados como necesite. Cada perfil puede ser referenciado por su nombre como un valor de cadena pasado a la función cacheLife.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 días
        revalidate: 60 * 60 * 24, // 1 día
        expire: 60 * 60 * 24 * 14, // 14 días
      },
    },
  },
}

module.exports = nextConfig

El ejemplo anterior almacena en caché durante 14 días, verifica actualizaciones diariamente y expira la caché después de 14 días. Luego puede hacer referencia a este perfil en toda su aplicación por su nombre:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

Sobrescribir los perfiles de caché predeterminados

Si bien los perfiles de caché predeterminados proporcionan una forma útil de pensar qué tan actualizado o desactualizado puede estar cualquier parte del contenido almacenable en caché, es posible que prefiera diferentes perfiles con nombre para que se alineen mejor con las estrategias de almacenamiento en caché de sus aplicaciones.

Puede sobrescribir los perfiles de caché con nombre predeterminados creando una nueva configuración con el mismo nombre que los predeterminados.

El siguiente ejemplo muestra cómo sobrescribir el perfil de caché predeterminado "days":

const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1 hora
        revalidate: 900, // 15 minutos
        expire: 86400, // 1 día
      },
    },
  },
}

module.exports = nextConfig

Definición de perfiles de caché en línea

Para casos de uso específicos, puede establecer un perfil de caché personalizado pasando un objeto a la función cacheLife:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife({
    stale: 3600, // 1 hora
    revalidate: 900, // 15 minutos
    expire: 86400, // 1 día
  })

  return <div>Page</div>
}

Este perfil de caché en línea solo se aplicará a la función o archivo en el que se creó. Si desea reutilizar el mismo perfil en toda su aplicación, puede agregar la configuración a la propiedad cacheLife de su archivo next.config.ts.

Uso anidado de use cache y cacheLife

Al definir múltiples comportamientos de caché en la misma ruta o árbol de componentes, si las cachés internas especifican su propio perfil cacheLife, la caché externa respetará la duración de caché más corta entre ellas. Esto aplica solo si la caché externa no tiene su propio perfil cacheLife definido explícitamente.

Por ejemplo, si agrega la directiva use cache a su página, sin especificar un perfil de caché, se aplicará implícitamente el perfil de caché predeterminado (cacheLife(”default”)). Si un componente importado en la página también usa la directiva use cache con su propio perfil de caché, se comparan los perfiles de caché externo e interno, y se aplicará la duración más corta establecida en los perfiles.

// Componente padre
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'

export async function ParentComponent() {
  'use cache'
  cacheLife('days')

  return (
    <div>
      <ChildComponent />
    </div>
  )
}

Y en un archivo separado, definimos el componente Child que fue importado:

// Componente hijo
import { unstable_cacheLife as cacheLife } from 'next/cache'

export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>

  // La caché de este componente respetará el perfil más corto 'hours'
}