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

Route Segment Config

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

ルートセグメントオプションを使用すると、次の変数を直接エクスポートすることで、PageLayout、またはルートハンドラーの動作を設定できます:

オプションタイプデフォルト
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

レイアウトまたはページのために部分的プレレンダリング (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':動的レンダリングを強制し、各ユーザーに対してリクエスト時にルートがレンダリングされます。このオプションは次の操作と同等です:

    • pagesディレクトリのgetServerSideProps()
    • レイアウトまたはページ内のすべてのfetch()リクエストに{ cache: 'no-store', next: { revalidate: 0 } }のオプションを設定する。
    • セグメント設定をexport const fetchCache = 'force-no-store'に設定する。
  • 'error':動的APIやキャッシュされていないデータを使用するコンポーネントがエラーを引き起こした場合、レイアウトやページのデータを静的にレンダリングし、キャッシュします。このオプションは次の操作と同等です:

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

Good to know:

dynamicParams

generateStaticParamsで生成されなかった動的セグメントが訪問されたときに何が起こるかを制御します。

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

Good to know:

  • このオプションは、pagesディレクトリ内のgetStaticPathsfallback: true | false | blockingオプションを置き換えます。
  • 最初に訪問されたすべてのパスを静的にレンダリングするには、generateStaticParamsで空の配列を返すか、export const dynamic = 'force-static'を利用する必要があります。
  • dynamicParams = trueの場合、セグメントはストリーミングサーバーレンダリングを使用します。
  • 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オプションを'force-cache'に設定するfetchリクエストまたは動的APIが使用される前に発見されたfetchリクエストをキャッシュするためのデフォルトのヒューリスティックです。これは意味的にrevalidate: Infinityと同等であり、リソースが無期限にキャッシュされることを意味します。ただし、個々のfetchリクエストがcache: 'no-store'revalidate: 0を使用してキャッシュされないようにし、ルートを動的にレンダリングすることも可能です。または、ルートのデフォルトより低い正の数を持つrevalidateを設定して、ルートの再検証頻度を上げることもできます。
  • 0:動的APIやキャッシュされていないデータのフェッチが見つからなかった場合でも、レイアウトやページが常に動的にレンダリングされるようにします。このオプションは、fetchリクエストがcacheオプションを設定していない場合でもデフォルトを'no-store'に変更しますが、force-cacheにオプトインするか、正のrevalidateを使用するfetchリクエストはそのままです。
  • number:(秒単位) レイアウトまたはページのデフォルトの再検証頻度をn秒に設定します。

Good to know:

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

再検証頻度

  • 単一路線の各レイアウトとページの最小の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' (デフォルト):動的APIの前にfetchリクエストをキャッシュし、彼らが提供するcacheオプションで動的APIの後のfetchリクエストをキャッシュしないデフォルトオプション。
  • 'default-cache'fetchに任意のcacheオプションを渡すことを許可しますが、オプションが提供されていない場合はcacheオプションを'force-cache'に設定します。これにより、動的APIの後のfetchリクエストも静的に考慮されます。
  • 'only-cache'fetchリクエストがcache: 'force-cache'を使用しない場合、デフォルトをcache: 'force-cache'に変更し、エラーが発生するようにすることで、すべてのfetchリクエストがキャッシュにオプトインすることを保証します。
  • 'force-cache'fetchリクエストのcacheオプションをすべて'force-cache'に設定することで、すべてのfetchリクエストがキャッシュにオプトインすることを保証します。
  • 'default-no-store'fetchに任意のcacheオプションを渡すことを許可しますが、オプションが提供されていない場合はcacheオプションを'no-store'に設定します。これにより、動的APIの前のfetchリクエストも動的に考慮されます。
  • 'only-no-store'fetchリクエストがcache: 'no-store'を使用しない場合、デフォルトをcache: 'no-store'に変更し、エラーが発生するようにすることで、すべてのfetchリクエストがキャッシュからオプトアウトすることを保証します。
  • 'force-no-store'fetchリクエストのcacheオプションをすべて'no-store'に設定することで、すべてのfetchリクエストがキャッシュからオプトアウトすることを保証します。これにより、fetchリクエストが'force-cache'オプションを提供しても、すべてのリクエストを毎回再フェッチすることが強制されます。

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

  • 単一路線の各レイアウトとページに設定されたオプションは、互いに互換性がある必要があります。
    • 'only-cache''force-cache'の両方が提供された場合、'force-cache'が優先されます。'only-no-store''force-no-store'の両方が提供された場合、'force-no-store'が優先されます。強制オプションは、単一のセグメントで'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 レイアウトはallリージョンをデフォルトとしています。

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" は廃止されました。コードモードが利用可能です。