メインコンテンツまでスキップ

cacheLife

cacheLife関数は、関数やコンポーネントのキャッシュの有効期間を設定するために使用されます。これはuse cacheディレクティブと共に、関数やコンポーネントのスコープ内で使用されるべきです。

使用法​

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

next.config.ts
import type { NextConfig } from 'next'

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

export default nextConfig

次に、関数やコンポーネントのスコープ内でcacheLife関数をインポートして呼び出します：

app/page.tsx
'use cache'
import { unstable_cacheLife as 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ディレクティブを使用する際には、キャッシュの動作を明示的に定義するために、常にキャッシュプロファイルを追加することをお勧めします。

プロファイルstalerevalidateexpire説明
default5分15分1年頻繁な更新が不要なコンテンツに適したデフォルトプロファイル
seconds01秒1秒ほぼリアルタイムの更新が必要な急速に変化するコンテンツ向け
minutes5分1分1時間1時間以内に頻繁に更新されるコンテンツ向け
hours5分1時間1日毎日更新されるが、少し古くても問題ないコンテンツ向け
days5分1日1週間週に1回更新されるが、1日古くても問題ないコンテンツ向け
weeks5分1週間30日月に1回更新されるが、1週間古くても問題ないコンテンツ向け
max5分30日1年更新がほとんど不要な非常に安定したコンテンツ向け

キャッシュプロファイルを参照するために使用される文字列値には固有の意味はありません；代わりに、それらはセマンティックラベルとして機能します。これにより、コードベース内でキャッシュされたコンテンツをより理解しやすく管理できます。

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

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

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

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

プロパティ値説明要件
stalenumberクライアントがサーバーを確認せずに値をキャッシュする期間。任意
revalidatenumberサーバーでキャッシュを更新する頻度；再検証中に古い値が提供されることがあります。任意
expirenumber動的フェッチに切り替える前に値が古くなるまでの最大期間；revalidateより長くなければなりません。任意 - revalidateより長くなければなりません

"stale"プロパティは、クライアントサイドのrouterキャッシュを特に制御する点で、staleTimes設定とは異なります。staleTimesは動的データと静的データのすべてのインスタンスに影響を与えるグローバル設定ですが、cacheLife設定は関数やルートごとに"stale"時間を定義することができます。

Good to know: "stale"プロパティはCache-control: max-ageヘッダーを設定しません。代わりに、クライアントサイドのrouterキャッシュを制御します。

例​

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

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

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: 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日後にキャッシュを期限切れにします。このプロファイルは、アプリケーション全体でその名前で参照できます：

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

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

デフォルトのキャッシュプロファイルの上書き​

デフォルトのキャッシュプロファイルは、キャッシュ可能な出力の新鮮さや古さを考えるための便利な方法を提供しますが、アプリケーションのキャッシュ戦略により適合する異なる名前付きプロファイルを好むかもしれません。

デフォルトの名前付きキャッシュプロファイルを上書きするには、デフォルトと同じ名前で新しい設定を作成します。

以下の例は、デフォルトの「days」キャッシュプロファイルを上書きする方法を示しています：

next.config.ts
const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1時間
        revalidate: 900, // 15分
        expire: 86400, // 1日
      },
    },
  },
}

module.exports = nextConfig

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

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

app/page.tsx
'use cache'
import { unstable_cacheLife as 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のネストされた使用​

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

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

app/components/parent.tsx
// 親コンポーネント
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'

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

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

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

app/components/child.tsx
// 子コンポーネント
import { unstable_cacheLife as cacheLife } from 'next/cache'

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

  // このコンポーネントのキャッシュは、より短い「hours」プロファイルを尊重します
}