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 time in the client router cache

「stale」プロパティはCache-control: max-ageヘッダーを設定しません。代わりに、クライアントサイドのルーターキャッシュを制御します。サーバーはこの値をx-nextjs-stale-timeレスポンスヘッダー（秒）を介してクライアントに送信し、クライアントルーターは再検証が必要になるまでキャッシュするルートの時間を決定するためにこれを使用します。

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

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

例

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

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 days
      revalidate: 60 * 60 * 24, // 1 day
      expire: 60 * 60 * 24 * 14, // 14 days
    },
  },
}
 
module.exports = nextConfig

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

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

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

デフォルトのキャッシュプロファイルは、キャッシュ可能な出力のどの部分がどれだけ新鮮またはstaleであるかを考えるのに役立ちますが、アプリケーションのキャッシュ戦略によりよく一致する名前付きプロファイルを好む場合があります。

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

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

const nextConfig = {
  cacheComponents: true,
  cacheLife: {
    days: {
      stale: 3600, // 1 hour
      revalidate: 900, // 15 minutes
      expire: 86400, // 1 day
    },
  },
}
 
module.exports = nextConfig

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

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

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

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

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

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

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

// Parent component
import { cacheLife } from 'next/cache'
import { ChildComponent } from './child'
 
export async function ParentComponent() {
  'use cache'
  cacheLife('days')
 
  return (
    <div>
      <ChildComponent />
    </div>
  )
}

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

// Child component
import { cacheLife } from 'next/cache'
 
export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>
 
  // This component's cache will respect the shorter 'hours' profile
}