Route Segment Config

Route Segment オプションは、以下の変数を直接エクスポートすることで、ページ、レイアウト、または ルートハンドラ の動作を設定できます。

オプション	タイプ	デフォルト
dynamic	'auto' | 'force-dynamic' | 'error' | 'force-static'	'auto'
dynamicParams	boolean	true
revalidate	false | 'force-cache' | 0 | number	false
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'
maxDuration	number	デプロイプラットフォームによる

layout.tsx | page.tsx | route.ts

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

Good to know：

• 現在、設定オプションの値は静的に解析可能である必要があります。たとえば、revalidate = 600は有効ですが、revalidate = 60 * 10は無効です。

Options

dynamic

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

layout.tsx / page.tsx / route.ts

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

Good to know: appディレクトリは、pagesディレクトリのページレベルでのgetServerSidePropsとgetStaticPropsの全てか無かの二項対立モデルよりも、フェッチリクエストレベルでのきめ細かいキャッシュ制御を優先します。dynamicオプションは便宜上pagesディレクトリのモデルに戻る方法であり、よりシンプルな移行手段を提供します。

• auto（デフォルト）：デフォルトのオプションでは、コンポーネントの動的な動作を妨げることなく、可能な限りキャッシュします
• force-dynamic： 動的なレンダリングを強制します。その結果、リクエスト時にそれぞれのユーザーに対してルートがレンダリングされます。このオプションはpagesディレクトリにおけるgetServerSideProps() と同等です。
• error：静的レンダリングを強制し、動的関数やキャッシュされていないデータを使用しているコンポーネントがある場合、エラーを発生させてレイアウトやページのデータをキャッシュします。このオプションは以下と同じです
  • pagesディレクトリにおけるgetStaticProps()
  • レイアウトまたはページ内のすべてのfetch()リクエストのオプションを{ cache: 'force-cache' }にする
  • Segment 設定をfetchCache = 'only-cache', dynamicParams = falseにする
  • dynamic = 'error'はdynamicParamsのデフォルトをtrueからfalseに変更します。generateStaticParamsで生成されなかった動的パラメータは、手動でdynamicParams = trueを設定することで、動的にページをレンダリングするように戻すことができます
• force-static： cookies()、headers()、useSearchParams()が空の値を返すように強制することで、静的レンダリングを強制し、レイアウトやページのデータをキャッシュします

Good to know:

• getServerSidePropsとgetStaticPropsからdynamic: 'force-dynamic'とdynamic: 'error'への移行方法はアップグレードガイドに記載されています。

dynamicParams

generateStaticParamsで生成されなかった動的な Segment にアクセスしたときの動作を制御します。

layout.tsx | page.tsx

export const dynamicParams = true // true | false,

• true（デフォルト）：generateStaticParamsに含まれない動的な Segment がオンデマンドで生成されます
• false：generateStaticParamsに含まれていない動的 Segment は404を返します

Good to know:

• このオプションは、pagesディレクトリのgetStaticPathsのfallback: true | false | blockingオプションを置き換えます
• dynamicParams = trueの場合、Segment はストリーミング・サーバーレンダリングを使用します
• dynamic = 'error'とdynamic = 'force-static'を使用すると、dynamicParamsのデフォルトがfalseに変更されます

revalidate

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

layout.tsx | page.tsx | route.ts

export const revalidate = false
// false | 'force-cache' | 0 | number

• false: （デフォルト）キャッシュオプションを'force-cache'に設定したfetchリクエスト、あるいは動的関数が使われる前に発見されたfetchリクエストをキャッシュするためのデフォルトのヒューリスティック。意味的にはrevalidate: Infinityと同じで、リソースを無期限にキャッシュすることを意味します。個々のfetchリクエストで cache: 'no-store'またはrevalidate: 0を使用してキャッシュを回避し、ルートを動的にレンダリングできます。あるいはrevalidateをルートのデフォルトより低い正の数値に設定することで、ルートの再検証頻度を増やすことができます。
• 0: 動的関数やキャッシュされていないデータフェッチが検出されなくても、レイアウトやページが常に動的にレンダリングされます。このオプションは、キャッシュオプションを設定しないfetchリクエストのデフォルトを'no-store'に変更しますが、'force-cache'を選ぶか、正のrevalidateを使うfetchリクエストはそのままにします。

• number:（秒単位）レイアウトまたはページのデフォルトの再検証頻度をn秒に設定します。

Good to know:

• revalidateオプションは、Node.js ランタイムを使用している場合にのみ使用できます。つまり、runtime = 'edge'でrevalidateオプションを使用しても動作しません。

再検証の頻度

• 1 つのルートの各レイアウトとページでもっとも低いrevalidate値が、ルート全体の再検証頻度になります。これは子ページが親レイアウトと同じ頻度で再検証されることを保証します。
• 個々のfetchリクエストは、ルート全体の再バリデーション頻度を上げるために、ルートのデフォルトのrevalidateよりも低い値を設定できます。これにより、いくつかの基準に基づいて、特定のルートに対してより頻繁な再検証を動的にオプトインできます。

fetchCache

注意

これは上級用のオプションです。デフォルトの振る舞いを明示的に上書きしたい場合にのみ使用してください。

デフォルトでは、Next.js は動的関数が使用される前に到達可能なすべてのfetch()リクエストをキャッシュし、動的関数が使用された後に発見された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リクエストをキャッシュし、動的関数の後のfetchリクエストはキャッシュしないデフォルトのオプションです
• 'default-cache'：どのようなcacheオプションでもfetchへ渡せるようにしますが、オプションが提供されない場合は、cacheオプションを'force-cache'に設定します。これは、動的関数の後のfetchリクエストも静的とみなすことを意味します
• 'only-cache'：オプションがない場合はデフォルトをcache: 'force-cache'に変更し、cache: 'no-store'のfetchリクエストがあった場合はエラーにします
• 'force-cache'：すべてのfetchリクエストのcacheオプションを'force-cache'に設定することで、すべてのfetchリクエストがキャッシュを利用するようにします
• 'default-no-store'：どのようなcaceheオプションでもfetchへ渡せるようにしますが、オプションが与えられない場合はcacheオプションを'no-store'にします。これは、動的関数の前のfetchリクエストも動的とみなすことを意味します
• 'only-no-store'：オプションがない場合はデフォルトをcache: 'no-store'に変更し、cache: 'force-cache'のfetchリクエストがあった場合はエラーにします
• 'force-no-store'：すべてのfetchリクエストのcacheオプションを'no-store'に設定し、すべてのfetchリクエストがキャッシュを使わないようにします。これにより、すべてのfetchリクエストは、たとえ'force-cache'オプションが指定されていても、リクエスト毎に再フェッチされます

ルートをまたぐ Segment の挙動

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

runtime

layout.tsx / page.tsx / route.ts

export const runtime = 'nodejs'
// 'edge' | 'nodejs'

• nodejs（デフォルト）
• edge

Edge および Node.js ランタイムの詳細については、こちらを参照してください。

preferredRegion

layout.tsx / page.tsx / route.ts

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

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

Good to know:

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

maxDuration

デプロイメント・プラットフォームによっては、関数のデフォルト実行時間を長く設定できる場合があります。この設定により、プランの制限内でより長い実行時間を選択できます。注: この設定には、Next.js 13.4.10以降が必要です。

layout.tsx / page.tsx / route.ts

export const maxDuration = 5

Good to know:

• maxDurationが指定されていない場合、デフォルト値はデプロイメント・プラットフォームとプランに依存します。

generateStaticParams

generateStaticParams関数を動的なルート Segmentと組み合わせることで、リクエスト時に生成されるのではなく、ビルド時に静的に生成されるルート Segment のパラメータのリストを定義できます。

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