cacheLife

La fonction cacheLife permet de définir la durée de vie du cache pour une fonction ou un composant. Elle doit être utilisée conjointement avec la directive use cache, et dans la portée de la fonction ou du composant.

Utilisation

Pour utiliser cacheLife, activez le flag dynamicIO dans votre fichier next.config.js :

import type { NextConfig } from 'next'

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

export default nextConfig

Ensuite, importez et invoquez la fonction cacheLife dans la portée de la fonction ou du composant :

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

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

Référence

Profils de cache par défaut

Next.js fournit un ensemble de profils de cache prédéfinis basés sur différentes échelles de temps. Si vous ne spécifiez pas de profil de cache dans la fonction cacheLife avec la directive use cache, Next.js appliquera automatiquement le profil default.

Cependant, nous recommandons de toujours ajouter un profil de cache lors de l'utilisation de la directive use cache pour définir explicitement le comportement de mise en cache.

Les valeurs textuelles utilisées pour référencer les profils de cache n'ont pas de signification intrinsèque ; elles servent plutôt d'étiquettes sémantiques. Cela vous permet de mieux comprendre et gérer votre contenu mis en cache dans votre base de code.

Bon à savoir : La mise à jour des options de configuration staleTimes et expireTime met également à jour les propriétés stale et expire du profil de cache default.

Profils de cache personnalisés

Vous pouvez configurer des profils de cache personnalisés en les ajoutant à l'option cacheLife dans votre fichier next.config.ts.

Les profils de cache sont des objets contenant les propriétés suivantes :

La propriété "stale" diffère du paramètre staleTimes en ce qu'elle contrôle spécifiquement la mise en cache côté client du routeur. Alors que staleTimes est un paramètre global affectant toutes les instances de données dynamiques et statiques, la configuration cacheLife vous permet de définir des temps "stale" par fonction ou par route.

Bon à savoir : La propriété "stale" ne définit pas l'en-tête Cache-control: max-age. Elle contrôle plutôt le cache du routeur côté client.

Exemples

Définition de profils de cache réutilisables

Vous pouvez créer des profils de cache réutilisables en les définissant dans votre fichier next.config.ts. Choisissez un nom adapté à votre cas d'utilisation et définissez des valeurs pour les propriétés stale, revalidate et expire. Vous pouvez créer autant de profils de cache personnalisés que nécessaire. Chaque profil peut être référencé par son nom sous forme de chaîne de caractères passée à la fonction cacheLife.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 jours
        revalidate: 60 * 60 * 24, // 1 jour
        expire: 60 * 60 * 24 * 14, // 14 jours
      },
    },
  },
}

module.exports = nextConfig

L'exemple ci-dessus met en cache pendant 14 jours, vérifie les mises à jour quotidiennement et expire le cache après 14 jours. Vous pouvez ensuite référencer ce profil dans toute votre application par son nom :

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

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

Surcharge des profils de cache par défaut

Bien que les profils de cache par défaut fournissent un moyen utile de penser à la fraîcheur ou à l'obsolescence de toute partie du contenu pouvant être mise en cache, vous pouvez préférer des profils nommés différents pour mieux correspondre à vos stratégies de mise en cache.

Vous pouvez remplacer les profils de cache nommés par défaut en créant une nouvelle configuration portant le même nom que les profils par défaut.

L'exemple ci-dessous montre comment remplacer le profil de cache par défaut "days" :

const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1 heure
        revalidate: 900, // 15 minutes
        expire: 86400, // 1 jour
      },
    },
  },
}

module.exports = nextConfig

Définition de profils de cache en ligne

Pour des cas d'utilisation spécifiques, vous pouvez définir un profil de cache personnalisé en passant un objet à la fonction cacheLife :

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

export default async function Page() {
  cacheLife({
    stale: 3600, // 1 heure
    revalidate: 900, // 15 minutes
    expire: 86400, // 1 jour
  })

  return <div>Page</div>
}

Ce profil de cache en ligne ne sera appliqué qu'à la fonction ou au fichier dans lequel il a été créé. Si vous souhaitez réutiliser le même profil dans toute votre application, vous pouvez ajouter la configuration à la propriété cacheLife de votre fichier next.config.ts.

Utilisation imbriquée de use cache et cacheLife

Lorsque vous définissez plusieurs comportements de mise en cache dans la même route ou arborescence de composants, si les caches internes spécifient leur propre profil cacheLife, le cache externe respectera la durée de cache la plus courte parmi eux. Cela s'applique uniquement si le cache externe n'a pas son propre profil cacheLife explicitement défini.

Par exemple, si vous ajoutez la directive use cache à votre page sans spécifier de profil de cache, le profil de cache par défaut sera appliqué implicitement (cacheLife(”default”)). Si un composant importé dans la page utilise également la directive use cache avec son propre profil de cache, les profils de cache externe et interne sont comparés, et la durée la plus courte définie dans les profils sera appliquée.

// Composant parent
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'

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

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

Et dans un fichier séparé, nous avons défini le composant enfant qui a été importé :

// Composant enfant
import { unstable_cacheLife as cacheLife } from 'next/cache'

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

  // Le cache de ce composant respectera le profil 'hours' plus court
}