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

Route Segment Config

このページで説明されているオプションは、dynamicIOフラグがオンの場合無効化され、将来的には廃止される予定です。

ルートセグメントオプションを使用すると、Page、Layout、またはRoute Handlerの動作を以下の変数を直接エクスポートすることで設定できます：

オプション型デフォルト
experimental_pprboolean
dynamic'auto' | 'force-dynamic' | 'error' | 'force-static''auto'
dynamicParamsbooleantrue
revalidatefalse | 0 | numberfalse
fetchCache'auto' | 'default-cache' | 'only-cache' | 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store''auto'
runtime'nodejs' | 'edge''nodejs'
preferredRegion'auto' | 'global' | 'home' | string | string[]'auto'
maxDurationnumberデプロイプラットフォームによる

オプション​

experimental_ppr​

Layout や Page に対してPartial Prerendering (PPR)を有効にします。

layout.tsx | page.tsx 
export const experimental_ppr = true
// true | false

dynamic​

Layout や Page の動的な動作を完全にスタティックまたは完全にダイナミックに変更します。

layout.tsx | page.tsx | route.ts
export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

Good to know: appディレクトリの新しいモデルは、pagesディレクトリのページレベルでのgetServerSidePropsとgetStaticPropsのバイナリの全か無のモデルよりも、fetchリクエストレベルでの細粒度のキャッシュ制御を優先します。dynamicオプションは、利便性のために以前のモデルに戻る方法であり、簡単な移行パスを提供します。

  • 'auto' (デフォルト)：可能な限りキャッシュしながら、どのコンポーネントも動的な動作を採用できるようにします。

  • 'force-dynamic'：動的レンダリングを強制し、ルートがリクエスト時に各ユーザーのためにレンダリングされるようにします。このオプションは次のように同等です：

    • pagesディレクトリのgetServerSideProps()。
    • LayoutやPageのすべてのfetch()リクエストのオプションを{ cache: 'no-store', next: { revalidate: 0 } }に設定する。
    • セグメント設定をexport const fetchCache = 'force-no-store'に設定する。

  • 'error'：すべてのコンポーネントが動的APIや非キャッシュデータを使用した場合にエラーを引き起こすことで、レイアウトやページのデータを静的にレンダリングし、キャッシュすることを強制します。このオプションは次のように同等です：

    • pagesディレクトリのgetStaticProps()。
    • LayoutやPageのすべてのfetch()リクエストのオプションを{ cache: 'force-cache' }に設定する。
    • セグメント設定をfetchCache = 'only-cache', dynamicParams = falseに設定する。
    • dynamic = 'error'は、dynamicParamsのデフォルトをtrueからfalseに変更します。手動でdynamicParams = trueを設定することで、generateStaticParamsで生成されない動的パラメータのページを動的にレンダリングできるようにできます。

  • 'force-static'：cookies、headers()およびuseSearchParams()が空の値を返すように強制し、レイアウトやページのデータを静的にレンダリングし、キャッシュします。

Good to know:

dynamicParams​

動的セグメントがgenerateStaticParamsで生成されなかった際の処理を制御します。

layout.tsx | page.tsx
export const dynamicParams = true // true | false,
layout.js | page.js | route.js
export const dynamicParams = true // true | false,
  • true (デフォルト)：generateStaticParamsに含まれていない動的セグメントは、オンデマンドで生成されます。
  • false：generateStaticParamsに含まれていない動的セグメントは404を返します。

Good to know:

  • このオプションは、pagesディレクトリのgetStaticPathsのfallback: true | false | blockingオプションを置き換えるものです。
  • 初回に訪問されたパスをすべて静的にレンダリングするには、generateStaticParamsで空の配列を返すか、export const dynamic = 'force-static'を利用する必要があります。
  • dynamicParams = trueの場合、セグメントはSuspenseを使ったストリーミングを使用します。
  • dynamic = 'error'およびdynamic = 'force-static'が使用されている場合、dynamicParamsのデフォルトをfalseに変更します。

revalidate​

レイアウトやページのデフォルトの再生成時間を設定します。このオプションは、個々のfetchリクエストで設定されたrevalidateの値を上書きしません。

layout.tsx | page.tsx | route.ts
export const revalidate = false
// false | 0 | number
  • false (デフォルト)：cacheオプションを設けたfetchリクエストをキャッシュする(動的APIが使用される前)。無期限にキャッシュするに等しい。個々のfetchリクエストは、キャッシュされることを回避するためにcache: 'no-store'またはrevalidate: 0を使用してルートを動的にレンダリングしたり、ルートのデフォルトより低い数を設定して、ルートの再検証頻度を増やすことができます。
  • 0：すべての動的APIやキャッシュされていないデータフェッチが発見されていなくても、常に動的にレンダリングされるようにレイアウトやページを確保します。このオプションにより、cacheオプションが設定されていないfetchリクエストのデフォルトを'no-store'に変更します。ただし、cache: 'force-cache'を利用するfetchリクエストや revalidateを使用する場合はそのままにします。
  • number：レイアウトやページのデフォルトの再形成頻度をn秒に設定します。

Good to know:

  • revalidateの値は、静的に解析可能でなければなりません。例えば、revalidate = 600は有効ですが、revalidate = 60 * 10は無効です。
  • runtime = 'edge'を使用している場合、revalidateの値は利用できません。
  • 開発環境では、ページは常にオンデマンドでレンダリングされ、キャッシュされることはありません。これにより、再検証期間が経過するのを待つことなく、即座に変更を確認することができます。

再検証頻度​

  • 単一ルートの各レイアウトおよびページにまたがる最も低いrevalidateが、エンタイルートの再検証頻度を決定します。これにより、子ページが親レイアウトと同じ頻度で再検証されます。
  • 個別の fetch リクエストは、ルートのデフォルトの revalidateより低い revalidate を設定して、エンタイルートの再検証頻度を増やすことができます。これにより、特定の基準に基づいてより頻繁な再検証に動的にオプトインすることが可能です。

fetchCache​

これはデフォルトの動作を特に上書きする必要がある場合にのみ使用するべき高度なオプションです。

デフォルトでは、Next.js は動的APIが使用される前に到達可能なfetch()リクエストをキャッシュし、動的APIが使用された後に発見されたfetchリクエストをキャッシュしません。

fetchCache は、レイアウトやページ内のすべてのfetchリクエストのデフォルトの cache オプションをオーバーライドするためのものです。

layout.tsx | page.tsx | route.ts
export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'
  • 'auto' (デフォルト)：fetchリクエストを、提供された cache オプションで動的APIの前にキャッシュし、動的APIの後にfetchリクエストをキャッシュしないデフォルトオプション。
  • 'default-cache'：fetchに任意の cache オプションを渡すことを許可しますが、オプションが提供されない場合、cache オプションを 'force-cache' に設定します。これにより、動的APIの後にあってもfetchリクエストが静的であるとみなされます。
  • 'only-cache'：あらゆる fetch リクエストがキャッシュされるように、何もオプションが提供されていない場合、デフォルトを cache: 'force-cache' に変更し、cache: 'no-store' を使用するfetchリクエストがある場合はエラーを引き起こします。
  • 'force-cache'：あらゆる fetch リクエストがキャッシュされるように、すべてのfetchリクエストの cache オプションを 'force-cache' に設定します。
  • 'default-no-store'：fetchに任意の cache オプションを渡すことを許可しますが、オプションが提供されない場合、cache オプションを 'no-store' に設定します。これにより、動的APIの前にあってもfetchリクエストが動的であると進化されます。
  • 'only-no-store'：あらゆる fetch リクエストがキャッシュされないことを確実にし、何もオプションが提供されていない場合、デフォルトを cache: 'no-store' に変更し、cache: 'force-cache' を使用するfetchリクエストがある場合はエラーを引き起こします。
  • 'force-no-store'：あらゆる fetch リクエストがキャッシュされないことを確実にし、すべてのfetchリクエストの cache オプションを 'no-store' に設定します。これにより、fetchリクエストが 'force-cache' オプションを提供している場合でも、毎回新しく取得されるように強制されます。

クロスルートセグメントの動作​

  • 単一のルートの各レイアウトおよびページにまたがるすべてのオプションが互いに互換性がある必要があります。
    • 'only-cache'と'force-cache'の両方が提供されている場合、'force-cache'が優先されます。'only-no-store'と'force-no-store'の両方が提供されている場合、'force-no-store'が優先されます。forceオプションはルート全体の動作を変更するので、単一のセグメントが'force-'を持つ場合、'only-'によって引き起こされるエラーを防ぐことができます。
    • 'only-*'と'force-*'のオプションの意図は、ルート全体が完全に静的または完全に動的であることを保証することです。これにより、次のことが許可されていません：
      • 単一のルートでの'only-cache'と'only-no-store'の組み合わせは許可されていません。
      • 単一のルートでの'force-cache'と'force-no-store'の組み合わせは許可されていません。
    • 親が'auto'や'*-cache'を提供する場合、子が'default-no-store'を提供することはできません。これは、同じfetchが異なる動作をする可能性があるためです。
  • 一般的には、共有された親レイアウトを'auto'に保ち、子セグメントが分岐する場合にオプションをカスタマイズすることを推奨します。

runtime​

アプリケーションをレンダリングする際には Node.js ランタイム、ミドルウェアには Edge ランタイムを使用することをお勧めします。

layout.tsx | page.tsx | route.ts
export const runtime = 'nodejs'
// 'nodejs' | 'edge'
  • 'nodejs' (デフォルト)
  • 'edge'

さまざまなランタイムについての詳細を学びましょう。

preferredRegion​

layout.tsx | page.tsx | route.ts
export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

preferredRegionのサポート、および対応するリージョンのサポートは、デプロイメントプラットフォームによります。

Good to know:

  • preferredRegionが指定されていない場合、最も近い親レイアウトのオプションを継承します。
  • root レイアウトはすべてのリージョンをデフォルトにします。

maxDuration​

デフォルトでは、Next.js はサーバー側のロジックの実行時間（ページのレンダリングや API の処理）を制限しません。デプロイメントプラットフォームは、Next.js のビルド出力から maxDurationを使用して特定の実行制限を追加できます。例：Vercel。

注意：この設定には Next.js 13.4.10以降が必要です。

layout.tsx | page.tsx | route.ts
export const maxDuration = 5

Good to know:

  • Server Actionsを使用する場合、ページレベルで maxDurationを設定して、ページ上で使用されるすべての Server Actions のデフォルトタイムアウトを変更します。

generateStaticParams​

generateStaticParams関数は、動的ルートセグメントと組み合わせて使用することで、ビルド時にオンデマンドではなく事前に生成されるルートセグメントパラメータのリストを定義できます。

詳細については、API リファレンスを参照してください。

バージョン履歴​

バージョン
v15.0.0-RCexport const runtime = "experimental-edge"が廃止されました。codemodが利用可能です。