uso de cache

La directiva use cache le permite marcar una ruta, componente React o función como almacenable en caché. Puede usarse al inicio de un archivo para indicar que todas las exportaciones del archivo deben almacenarse en caché, o en línea al inicio de una función o componente para almacenar en caché el valor de retorno.

Uso

use cache es actualmente una característica experimental. Para habilitarla, agregue la opción useCache a su archivo next.config.ts:

import type { NextConfig } from 'next'

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

export default nextConfig

Nota importante: use cache también puede habilitarse con la opción dynamicIO.

Luego, agregue use cache a nivel de archivo, componente o función:

// Nivel de archivo
'use cache'

export default async function Page() {
  // ...
}

// Nivel de componente
export async function MyComponent() {
  'use cache'
  return <></>
}

// Nivel de función
export async function getData() {
  'use cache'
  const data = await fetch('/api/data')
  return data
}

Cómo funciona use cache

Claves de caché

La clave de una entrada de caché se genera utilizando una versión serializada de sus entradas, que incluye:

• ID de compilación (generado para cada compilación)
• ID de función (un identificador único seguro para la función)
• Los argumentos serializables de la función (o props).

Los argumentos pasados a la función almacenada en caché, así como cualquier valor que lea del ámbito padre, se convierten automáticamente en parte de la clave. Esto significa que se reutilizará la misma entrada de caché siempre que sus entradas sean las mismas.

Argumentos no serializables

Cualquier argumento, prop o valor cerrado no serializable se convertirá en referencias dentro de la función almacenada en caché, y solo se podrán pasar a través, no inspeccionar ni modificar. Estos valores no serializables se completarán en el momento de la solicitud y no formarán parte de la clave de caché.

Por ejemplo, una función almacenada en caché puede tomar JSX como prop children y devolver <div>{children}</div>, pero no podrá inspeccionar el objeto children real. Esto le permite anidar contenido no almacenado en caché dentro de un componente almacenado en caché.

function CachedComponent({ children }: { children: ReactNode }) {
  'use cache'
  return <div>{children}</div>
}

Valores de retorno

El valor de retorno de la función almacenable en caché debe ser serializable. Esto garantiza que los datos almacenados en caché puedan almacenarse y recuperarse correctamente.

use cache en tiempo de compilación

Cuando se usa al inicio de un layout o page, el segmento de ruta se prerrenderizará, permitiendo que luego sea revalidado.

Esto significa que use cache no puede usarse con APIs de tiempo de solicitud como cookies o headers.

use cache en tiempo de ejecución

En el servidor, las entradas de caché de componentes o funciones individuales se almacenarán en memoria.

Luego, en el cliente, cualquier contenido devuelto desde la caché del servidor se almacenará en la memoria del navegador durante la duración de la sesión o hasta que se revalide.

Durante la revalidación

Por defecto, use cache tiene un período de revalidación del lado del servidor de 15 minutos. Si bien este período puede ser útil para contenido que no requiere actualizaciones frecuentes, puede usar las APIs cacheLife y cacheTag para configurar cuándo se deben revalidar las entradas de caché individuales.

• cacheLife: Configura el tiempo de vida de la entrada de caché.
• cacheTag: Crea etiquetas para revalidación bajo demanda.

Ambas APIs se integran en las capas de caché del cliente y del servidor, lo que significa que puede configurar su semántica de caché en un solo lugar y que se aplique en todas partes.

Consulte las documentaciones de las APIs cacheLife y cacheTag para obtener más información.

Ejemplos

Almacenamiento en caché de una ruta completa con use cache

Para prerrenderizar una ruta completa, agregue use cache al inicio de ambos archivos layout y page. Cada uno de estos segmentos se trata como un punto de entrada independiente en su aplicación y se almacenará en caché de forma independiente.

'use cache'

export default function Layout({ children }: { children: ReactNode }) {
  return <div>{children}</div>
}

Cualquier componente importado y anidado en el archivo page heredará el comportamiento de caché de page.

'use cache'

async function Users() {
  const users = await fetch('/api/users')
  // recorrer usuarios
}

export default function Page() {
  return (
    <main>
      <Users />
    </main>
  )
}

Nota importante:

• Si use cache se agrega solo al layout o al page, solo ese segmento de ruta y los componentes importados en él se almacenarán en caché.
• Si alguno de los hijos anidados en la ruta usa APIs dinámicas, entonces la ruta optará por no prerrenderizarse.

Almacenamiento en caché de la salida de un componente con use cache

Puede usar use cache a nivel de componente para almacenar en caché cualquier solicitud o cálculo realizado dentro de ese componente. La entrada de caché se reutilizará siempre que las props serializadas produzcan el mismo valor en cada instancia.

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }
  return //...
}

interface BookingsProps {
  type: string
}

Almacenamiento en caché de la salida de una función con use cache

Dado que puede agregar use cache a cualquier función asíncrona, no está limitado a almacenar en caché solo componentes o rutas. Es posible que desee almacenar en caché una solicitud de red, una consulta de base de datos o un cálculo lento.

export async function getData() {
  'use cache'

  const data = await fetch('/api/data')
  return data
}

Entrelazado

Si necesita pasar argumentos no serializables a una función almacenable en caché, puede pasarlos como children. Esto significa que la referencia children puede cambiar sin afectar la entrada de caché.

export default async function Page() {
  const uncachedData = await getData()
  return (
    <CacheComponent>
      <DynamicComponent data={uncachedData} />
    </CacheComponent>
  )
}

async function CacheComponent({ children }: { children: ReactNode }) {
  'use cache'
  const cachedData = await fetch('/api/cached-data')
  return (
    <div>
      <PrerenderedComponent data={cachedData} />
      {children}
    </div>
  )
}

También puede pasar Acciones de Servidor a través de componentes almacenados en caché a Componentes de Cliente sin invocarlos dentro de la función almacenable en caché.

import ClientComponent from './ClientComponent'

export default async function Page() {
  const performUpdate = async () => {
    'use server'
    // Realizar alguna actualización del lado del servidor
    await db.update(...)
  }

  return <CacheComponent performUpdate={performUpdate} />
}

async function CachedComponent({
  performUpdate,
}: {
  performUpdate: () => Promise<void>
}) {
  'use cache'
  // No llame a performUpdate aquí
  return <ClientComponent action={performUpdate} />
}

Soporte de plataforma

Aprenda cómo configurar el almacenamiento en caché al autoalojar Next.js.

Historial de versiones