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

use cache

use cacheディレクティブは、コンポーネントや関数をキャッシュするために指定します。ファイルの先頭で使用すると、そのファイル内のすべてのエクスポートがキャッシュ可能であることを示します。また、関数やコンポーネントの先頭でインラインで使用すると、Next.jsに対してその戻り値をキャッシュし、後続のリクエストで再利用することを通知します。これはNext.jsの実験的な機能であり、Reactのネイティブ機能であるuse clientやuse serverとは異なります。

使用法​

next.config.tsファイルでuseCacheフラグを使用して、use cacheディレクティブのサポートを有効にします：

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

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

export default nextConfig

さらに、dynamicIOフラグが設定されている場合も、use cacheディレクティブが有効になります。

その後、ファイル、コンポーネント、または関数レベルでuse cacheディレクティブを使用できます：

// ファイルレベル
'use cache'

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

// コンポーネントレベル
export async function MyComponent() {
  'use cache'
  return <></>
}

// 関数レベル
export async function getData() {
  'use cache'
  const data = await fetch('/api/data')
  return data
}

Good to know​

  • use cacheはNext.jsの実験的な機能であり、Reactのネイティブ機能であるuse clientやuse serverとは異なります。
  • キャッシュされた関数に渡されるシリアライズ可能な引数（またはprops）や、親スコープから読み取るシリアライズ可能な値は、JSONのような形式に変換され、自動的にキャッシュキーの一部になります。
  • シリアライズ不可能な引数、props、または閉じ込められた値は、キャッシュされた関数内で不透明な参照に変わり、通過させることはできますが、検査や変更はできません。これらのシリアライズ不可能な値はリクエスト時に埋め込まれ、キャッシュキーの一部にはなりません。
    • 例えば、キャッシュされた関数はJSXをchildren propとして受け取り、<div>{children}</div>を返すことができますが、実際のchildrenオブジェクトを内省することはできません。
  • キャッシュ可能な関数の戻り値もシリアライズ可能でなければなりません。これにより、キャッシュされたデータが正しく保存および取得されることが保証されます。
  • use cacheディレクティブを使用する関数は、副作用を持ってはいけません。例えば、状態の変更、DOMの直接操作、タイマーを設定してコードを定期的に実行することなどです。
  • Partial Prerenderingと一緒に使用する場合、use cacheを持つセグメントは静的HTMLシェルの一部としてプリレンダリングされます。
  • unstable_cacheがJSONデータのみをサポートするのとは異なり、use cacheはReactがレンダリングできる任意のシリアライズ可能なデータ、コンポーネントのレンダリング出力を含むデータをキャッシュできます。

例​

use cacheを使用したルート全体のキャッシュ​

ルート全体をプリレンダリングするには、layoutとpageファイルの両方の先頭にuse cacheを追加します。これらの各セグメントはアプリケーション内の個別のエントリーポイントとして扱われ、独立してキャッシュされます。

app/layout.tsx
'use cache'

export default function Layout({ children }: { children: ReactNode }) {
  return <div>{children}</div>
}
app/page.tsx
'use cache'

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

pageファイルにインポートされネストされたコンポーネントは、pageのキャッシュ動作を継承します。

app/page.tsx
'use cache'

async function Users() {
  const users = await fetch('/api/users')
  // ユーザーをループ処理
}

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

これは、以前export const dynamic = "force-static"オプションを使用していたアプリケーションに推奨され、ルート全体がプリレンダリングされることを保証します。

use cacheを使用したコンポーネント出力のキャッシュ​

コンポーネントレベルでuse cacheを使用して、そのコンポーネント内で行われるフェッチや計算をキャッシュできます。アプリケーション全体でコンポーネントを再利用する際、propsが同じ構造を維持する限り、同じキャッシュエントリを共有できます。

propsはシリアライズされ、キャッシュキーの一部を形成し、シリアライズされたpropsが各インスタンスで同じ値を生成する限り、キャッシュエントリが再利用されます。

app/components/bookings.tsx
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
}

use cacheを使用した関数出力のキャッシュ​

非同期関数にuse cacheを追加できるため、コンポーネントやルートだけでなく、ネットワークリクエストやデータベースクエリをキャッシュしたり、非常に遅い計算を行ったりすることもできます。この種の作業を含む関数にuse cacheを追加することで、キャッシュ可能になり、再利用時には同じキャッシュエントリを共有します。

app/actions.ts
export async function getData() {
  'use cache'

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

再検証​

デフォルトでは、Next.jsはuse cacheディレクティブを使用する際に**15分の再検証期間**を設定します。Next.jsはほぼ無限の有効期限を設定し、頻繁な更新が不要なコンテンツに適しています。

この再検証期間は、頻繁に変更されることを期待しないコンテンツに役立つかもしれませんが、cacheLifeとcacheTag APIを使用してキャッシュの動作を設定できます：

  • cacheLife: 時間ベースの再検証期間のためのものです。
  • cacheTag: キャッシュされたデータにタグを付けるためのものです。

これらのAPIはクライアントとサーバーのキャッシングレイヤー全体で統合されており、キャッシングのセマンティクスを1か所で設定し、どこでも適用されるようにできます。

詳細については、cacheLifeとcacheTagのドキュメントを参照してください。

無効化​

キャッシュされたデータを無効にするには、revalidateTag関数を使用します。

詳細については、revalidateTagのドキュメントを参照してください。

インターリービング​

キャッシュ可能な関数にシリアライズ不可能な引数を渡す必要がある場合は、それらをchildrenとして渡すことができます。これにより、childrenの参照が変わってもキャッシュエントリに影響を与えません。

app/page.tsx
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>
  )
}

キャッシュされたコンポーネントを通じてServer ActionsをClient Componentsに渡すこともできますが、キャッシュ可能な関数内でそれらを呼び出すことはありません。

app/page.tsx
import ClientComponent from './ClientComponent'

export default async function Page() {
  const performUpdate = async () => {
    'use server'
    // サーバーサイドの更新を実行
    await db.update(...)
  }

  return <CacheComponent performUpdate={performUpdate} />
}

async function CachedComponent({
  performUpdate,
}: {
  performUpdate: () => Promise<void>
}) {
  'use cache'
  // ここでperformUpdateを呼び出さない
  return <ClientComponent action={performUpdate} />
}
app/ClientComponent.tsx
'use client'

export default function ClientComponent({
  action,
}: {
  action: () => Promise<void>
}) {
  return <button onClick={action}>Update</button>
}