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

Route Segment Config

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

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

OptionTypeDefault
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デプロイプラットフォームによって設定

Options​

experimental_ppr​

Partial Prerendering (PPR)をレイアウトまたはページで有効にします。

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

dynamic​

レイアウトまたはページの動的な動作を完全に静的または完全に動的に変更します。

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'：動的レンダリングを強制し、リクエスト時に各ユーザーのためにルートがレンダリングされるようにします。このオプションは以下と同等です：

    • レイアウトまたはページ内のすべてのfetch()リクエストのオプションを{ cache: 'no-store', next: { revalidate: 0 } }に設定します。
    • セグメント設定をexport const fetchCache = 'force-no-store'に設定します。

  • 'error'：静的レンダリングを強制し、Dynamic APIsやキャッシュされていないデータを使用するコンポーネントがある場合にエラーを発生させることで、レイアウトまたはページのデータをキャッシュします。このオプションは以下と同等です：

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

  • '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の場合、セグメントはStreaming Server Renderingを使用します。
  • dynamic = 'error'とdynamic = 'force-static'が使用される場合、dynamicParamsのデフォルトをfalseに変更します。

revalidate​

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

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

Good to know:

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

Revalidation Frequency​

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

fetchCache​

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

デフォルトでは、Next.jsは、Dynamic APIsが使用される前に到達可能なfetch()リクエストをキャッシュし、Dynamic APIsが使用された後に発見された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' (デフォルト)：Dynamic APIsの前にfetchリクエストをキャッシュし、提供されたcacheオプションを使用し、Dynamic APIsの後にfetchリクエストをキャッシュしないデフォルトオプションです。
  • 'default-cache'：fetchに任意のcacheオプションを渡すことを許可しますが、オプションが提供されない場合はcacheオプションを'force-cache'に設定します。これにより、Dynamic APIsの後の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'に設定します。これにより、Dynamic APIsの前のfetchリクエストも動的と見なされます。
  • 'only-no-store'：すべてのfetchリクエストがキャッシュをオプトアウトすることを保証し、オプションが提供されない場合はデフォルトをcache: 'no-store'に変更し、cache: 'force-cache'を使用するfetchリクエストがある場合はエラーを発生させます。
  • 'force-no-store'：すべてのfetchリクエストがキャッシュをオプトアウトすることを保証し、すべてのfetchリクエストのcacheオプションを'no-store'に設定します。これにより、すべてのfetchリクエストがリクエストごとに再フェッチされることを強制し、'force-cache'オプションを提供しても再フェッチされます。

Cross-route segment behavior​

  • 単一のルートの各レイアウトとページに設定されたオプションは互換性がある必要があります。
    • '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'を提供することはできません。これは、同じフェッチが異なる動作をする可能性があるためです。
  • 共有される親レイアウトを'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関数は、dynamic route segmentsと組み合わせて使用することで、ビルド時に静的に生成されるルートセグメントパラメータのリストを定義し、リクエスト時にオンデマンドで生成されるのではなく、ビルド時に静的に生成されるようにします。

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

バージョン履歴​

Version
v15.0.0-RCexport const runtime = "experimental-edge"は廃止されました。codemodが利用可能です。