Route Segment Config

Good to know:

The options outlined on this page are disabled if the cacheComponents flag is on, and will eventually be deprecated in the future.
Route Segment options only take effect in Server Component Pages, Layouts, or Route Handlers.
generateStaticParams cannot be used inside a 'use client' file.

The Route Segment options allows you to configure the behavior of a Page, Layout, or Route Handler by directly exporting the following variables:

Option	Type	Default
`dynamic`	`'auto' \| 'force-dynamic' \| 'error' \| 'force-static'`	`'auto'`
`dynamicParams`	`boolean`	`true`
`revalidate`	`false \| 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`	Set by deployment platform

Options

`dynamic`

Change the dynamic behavior of a layout or page to fully static or fully dynamic.

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

Good to know: The new model in the app directory favors granular caching control at the fetch request level over the binary all-or-nothing model of getServerSideProps and getStaticProps at the page-level in the pages directory. The dynamic option is a way to opt back in to the previous model as a convenience and provides a simpler migration path.

'auto' (default): The default option to cache as much as possible without preventing any components from opting into dynamic behavior.
'force-dynamic': Force dynamic rendering, which will result in routes being rendered for each user at request time. This option is equivalent to:
- Setting the option of every fetch() request in a layout or page to { cache: 'no-store', next: { revalidate: 0 } }.
- Setting the segment config to export const fetchCache = 'force-no-store'
'error': Force static rendering and cache the data of a layout or page by causing an error if any components use Dynamic APIs or uncached data. This option is equivalent to:
- getStaticProps() in the pages directory.
- Setting the option of every fetch() request in a layout or page to { cache: 'force-cache' }.
- Setting the segment config to fetchCache = 'only-cache'.
'force-static': Force static rendering and cache the data of a layout or page by forcing cookies, headers() and useSearchParams() to return empty values. It is possible to revalidate, revalidatePath, or revalidateTag, in pages or layouts rendered with force-static.

Good to know:

Instructions on how to migrate from getServerSideProps and getStaticProps to dynamic: 'force-dynamic' and dynamic: 'error' can be found in the upgrade guide.

`dynamicParams`

Control what happens when a dynamic segment is visited that was not generated with generateStaticParams.

export const dynamicParams = true // true | false

true (default): Dynamic segments not included in generateStaticParams are generated on demand.
false: Dynamic segments not included in generateStaticParams will return a 404.

Good to know:

This option replaces the fallback: true | false | blocking option of getStaticPaths in the pages directory.
To statically render all paths the first time they're visited, you'll need to return an empty array in generateStaticParams or utilize export const dynamic = 'force-static'.
When dynamicParams = true, the segment uses Streaming Server Rendering.

`revalidate`

Set the default revalidation time for a layout or page. This option does not override the revalidate value set by individual fetch requests.

export const revalidate = false
// false | 0 | number

false (default): The default heuristic to cache any fetch requests that set their cache option to 'force-cache' or are discovered before a Dynamic API is used. Semantically equivalent to revalidate: Infinity which effectively means the resource should be cached indefinitely. It is still possible for individual fetch requests to use cache: 'no-store' or revalidate: 0 to avoid being cached and make the route dynamically rendered. Or set revalidate to a positive number lower than the route default to increase the revalidation frequency of a route.
0: Ensure a layout or page is always dynamically rendered even if no Dynamic APIs or uncached data fetches are discovered. This option changes the default of fetch requests that do not set a cache option to 'no-store' but leaves fetch requests that opt into 'force-cache' or use a positive revalidate as is.
number: (in seconds) Set the default revalidation frequency of a layout or page to n seconds.

Good to know:

The revalidate value needs to be statically analyzable. For example revalidate = 600 is valid, but revalidate = 60 * 10 is not.
The revalidate value is not available when using runtime = 'edge'.
In Development, Pages are always rendered on-demand and are never cached. This allows you to see changes immediately without waiting for a revalidation period to pass.

Revalidation Frequency

The lowest revalidate across each layout and page of a single route will determine the revalidation frequency of the entire route. This ensures that child pages are revalidated as frequently as their parent layouts.
Individual fetch requests can set a lower revalidate than the route's default revalidate to increase the revalidation frequency of the entire route. This allows you to dynamically opt-in to more frequent revalidation for certain routes based on some criteria.

`fetchCache`

This is an advanced option that should only be used if you specifically need to override the default behavior.

By default, Next.js will cache any fetch() requests that are reachable before any Dynamic APIs are used and will not cache fetch requests that are discovered after Dynamic APIs are used.

fetchCache allows you to override the default cache option of all fetch requests in a layout or page.

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

'auto' (default): The default option to cache fetch requests before Dynamic APIs with the cache option they provide and not cache fetch requests after Dynamic APIs.
'default-cache': Allow any cache option to be passed to fetch but if no option is provided then set the cache option to 'force-cache'. This means that even fetch requests after Dynamic APIs are considered static.
'only-cache': Ensure all fetch requests opt into caching by changing the default to cache: 'force-cache' if no option is provided and causing an error if any fetch requests use cache: 'no-store'.
'force-cache': Ensure all fetch requests opt into caching by setting the cache option of all fetch requests to 'force-cache'.
'default-no-store': Allow any cache option to be passed to fetch but if no option is provided then set the cache option to 'no-store'. This means that even fetch requests before Dynamic APIs are considered dynamic.
'only-no-store': Ensure all fetch requests opt out of caching by changing the default to cache: 'no-store' if no option is provided and causing an error if any fetch requests use cache: 'force-cache'
'force-no-store': Ensure all fetch requests opt out of caching by setting the cache option of all fetch requests to 'no-store'. This forces all fetch requests to be re-fetched every request even if they provide a 'force-cache' option.

Cross-route segment behavior

Any options set across each layout and page of a single route need to be compatible with each other.
- If both the 'only-cache' and 'force-cache' are provided, then 'force-cache' wins. If both 'only-no-store' and 'force-no-store' are provided, then 'force-no-store' wins. The force option changes the behavior across the route so a single segment with 'force-*' would prevent any errors caused by 'only-*'.
- The intention of the 'only-*' and 'force-*' options is to guarantee the whole route is either fully static or fully dynamic. This means:
  - A combination of 'only-cache' and 'only-no-store' in a single route is not allowed.
  - A combination of 'force-cache' and 'force-no-store' in a single route is not allowed.
- A parent cannot provide 'default-no-store' if a child provides 'auto' or '*-cache' since that could make the same fetch have different behavior.
It is generally recommended to leave shared parent layouts as 'auto' and customize the options where child segments diverge.

`runtime`

We recommend using the Node.js runtime for rendering your application. This option cannot be used in Proxy.

Good to know: Using runtime: 'edge' is not supported for Cache Components.

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

'nodejs' (default)
'edge'

`preferredRegion`

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

Support for preferredRegion, and regions supported, is dependent on your deployment platform.

Good to know:

If a preferredRegion is not specified, it will inherit the option of the nearest parent layout.
The root layout defaults to all regions.

`maxDuration`

By default, Next.js does not limit the execution of server-side logic (rendering a page or handling an API). Deployment platforms can use maxDuration from the Next.js build output to add specific execution limits.

Note: This setting requires Next.js 13.4.10 or higher.

export const maxDuration = 5

Good to know:

If using Server Actions, set the maxDuration at the page level to change the default timeout of all Server Actions used on the page.

`generateStaticParams`

The generateStaticParams function can be used in combination with dynamic route segments to define the list of route segment parameters that will be statically generated at build time instead of on-demand at request time.

See the API reference for more details.

Version History

Version
`v16.0.0`	`export const experimental_ppr = true` removed. A codemod is available.
`v15.0.0-RC`	`export const runtime = "experimental-edge"` deprecated. A codemod is available.

Route Segment Config

On this page