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

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' (default): 可能な限りキャッシュするデフォルトオプションで、動的な動作にオプトインするコンポーネントを妨げません。

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

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

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

    • pagesディレクトリのgetStaticProps()。
    • レイアウトまたはページ内のすべてのfetch()リクエストのオプションを{ cache: 'force-cache' }に設定します。
    • segment configを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 (default): 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 (default): 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' (default): 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' (default)
  • 'edge'

異なるランタイムについて詳しく学びましょう。

preferredRegion​

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

preferredRegionのサポートとサポートされているリージョンは、デプロイプラットフォームに依存します。

Good to know:

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

maxDuration​

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

Note: この設定には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が利用可能です。