cacheLife

cacheLife関数は、関数またはコンポーネントのキャッシュ有効期限を設定するために使用されます。use cacheディレクティブと共に使用し、関数またはコンポーネントのスコープ内で呼び出す必要があります。

使用方法

cacheLifeを使用するには、next.config.jsファイルでcacheComponentsフラグを有効にします。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
}
 
export default nextConfig

次に、関数またはコンポーネントのスコープ内からcacheLife関数をインポートして呼び出します。

'use cache'
import { cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

リファレンス

デフォルトキャッシュプロファイル

Next.jsは様々な時間スケールでモデル化された名前付きキャッシュプロファイルのセットを提供します。use cacheディレクティブと共にcacheLife関数でキャッシュプロファイルを指定しない場合、Next.jsは自動的にdefaultキャッシュプロファイルを適用します。

ただし、use cacheディレクティブを使用する際は、常にキャッシュプロファイルを追加して、キャッシュ動作を明示的に定義することをお勧めします。

キャッシュプロファイルの参照に使用される文字列値には本質的な意味はなく、セマンティックラベルとして機能します。これにより、コードベース内でキャッシュされたコンテンツをより良く理解して管理できます。

補足： staleTimesとexpireTimeの設定オプションを更新すると、defaultキャッシュプロファイルのstaleとexpireプロパティも更新されます。

カスタムキャッシュプロファイル

next.config.tsファイルのcacheLifeオプションに追加することで、カスタムキャッシュプロファイルを設定できます。

キャッシュプロファイルは以下のプロパティを含むオブジェクトです。

"stale"プロパティはstaleTimes設定とは異なり、クライアント側のルーターキャッシュを特別に制御します。staleTimesは動的と静的の両方のすべてのインスタンスに影響する全体的な設定ですが、cacheLife設定では関数またはルート単位で"stale"時間を定義できます。

クライアントルーターキャッシュの"stale"時間

"stale"プロパティはCache-control: max-ageヘッダーを設定しません。代わりに、クライアント側のルーターキャッシュを制御します。サーバーはこの値をx-nextjs-stale-timeレスポンスヘッダー（秒単位）経由でクライアントに送信し、クライアントルーターはこれを使用してルートをキャッシュする期間を決定します。その後、リバリデーションが必要になります。

クライアントは最小stale時間として30秒を適用します。これにより、プリフェッチされたデータはユーザーがプリフェッチ後にリンクをクリックするのに十分な時間、使用可能な状態を保ちます。この最小値がない場合、非常に短いstale時間により、プリフェッチされたデータが使用できる状態になる前に期限切れになり、プリフェッチが効果がなくなります。

この最小値は時間ベースの有効期限にのみ適用されます。Server ActionからrevalidateTag、revalidatePath、updateTag、またはrefreshを呼び出す場合、クライアントキャッシュ全体が即座にクリアされ、stale時間はバイパスされます。

例

再利用可能なキャッシュプロファイルの定義

next.config.tsファイルでキャッシュプロファイルを定義することで、再利用可能なキャッシュプロファイルを作成できます。ユースケースに適した名前を選択して、stale、revalidate、expireプロパティの値を設定します。必要に応じて複数のカスタムキャッシュプロファイルを作成できます。各プロファイルは、cacheLife関数に文字列値として渡される名前で参照できます。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {
    biweekly: {
      stale: 60 * 60 * 24 * 14, // 14日
      revalidate: 60 * 60 * 24, // 1日
      expire: 60 * 60 * 24 * 14, // 14日
    },
  },
}
 
module.exports = nextConfig

上記の例では14日間キャッシュし、毎日の更新をチェックし、14日後にキャッシュを有効期限切れにします。その後、このプロファイルをアプリケーション全体で名前で参照できます。

'use cache'
import { cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

デフォルトキャッシュプロファイルのオーバーライド

デフォルトキャッシュプロファイルはキャッシュ可能な出力がどの程度新鮮または古い可能性があるかを考える上で有用な方法を提供しますが、アプリケーションのキャッシング戦略により適した異なる名前付きプロファイルを使用したい場合があります。

デフォルトと同じ名前を持つ新しい設定を作成することで、デフォルトの名前付きキャッシュプロファイルをオーバーライドできます。

以下の例は、デフォルトの"days"キャッシュプロファイルをオーバーライドする方法を示しています。

const nextConfig = {
  cacheComponents: true,
  cacheLife: {
    days: {
      stale: 3600, // 1時間
      revalidate: 900, // 15分
      expire: 86400, // 1日
    },
  },
}
 
module.exports = nextConfig

キャッシュプロファイルのインライン定義

特定のユースケースでは、cacheLife関数にオブジェクトを渡すことで、カスタムキャッシュプロファイルを設定できます。

'use cache'
import { cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife({
    stale: 3600, // 1時間
    revalidate: 900, // 15分
    expire: 86400, // 1日
  })
 
  return <div>Page</div>
}

このインラインキャッシュプロファイルは、それが作成された関数またはファイルにのみ適用されます。アプリケーション全体で同じプロファイルを再利用したい場合は、next.config.tsファイルのcacheLifeプロパティに設定を追加できます。

use cacheとcacheLifeのネストされた使用

同じルートまたはコンポーネントツリー内で複数のキャッシング動作を定義する場合、内部キャッシュが独自のcacheLifeプロファイルを指定していれば、外部キャッシュはそれに従います。これは外部キャッシュが定義された明示的なcacheLifeプロファイルを持たない場合にのみ適用されます。

例えば、キャッシュプロファイルを指定せずにuse cacheディレクティブをページに追加する場合、デフォルトキャッシュプロファイルが暗黙的に適用されます（cacheLife("default")）。ページにインポートされたコンポーネントも、独自のキャッシュプロファイルを持つuse cacheディレクティブを使用する場合、外部と内部のキャッシュプロファイルが比較され、プロファイルで設定された最短の期間が適用されます。

// 親コンポーネント
import { cacheLife } from 'next/cache'
import { ChildComponent } from './child'
 
export async function ParentComponent() {
  'use cache'
  cacheLife('days')
 
  return (
    <div>
      <ChildComponent />
    </div>
  )
}

別のファイルでは、インポートされた子コンポーネントを定義しました。

// 子コンポーネント
import { cacheLife } from 'next/cache'
 
export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>
 
  // このコンポーネントのキャッシュは、より短い'hours'プロファイルを尊重します
}