cefdb27662
* Changes all `Note` → `Good to know` * Consistently puts the colon on the outside of bold text * Documents singe and multi-line styles in contribution guide --------- Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
204 lines
14 KiB
Text
204 lines
14 KiB
Text
---
|
|
title: Route Segment Config
|
|
description: Learn about how to configure options for Next.js route segments.
|
|
---
|
|
|
|
The Route Segment options allows you configure the behavior of a [Page](/docs/app/building-your-application/routing/pages-and-layouts), [Layout](/docs/app/building-your-application/routing/pages-and-layouts), or [Route Handler](/docs/app/building-your-application/routing/router-handlers) by directly exporting the following variables:
|
|
|
|
| Option | Type | Default |
|
|
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- |
|
|
| [`dynamic`](#dynamic) | `'auto' \| 'force-dynamic' \| 'error' \| 'force-static'` | `'auto'` |
|
|
| [`dynamicParams`](#dynamicparams) | `boolean` | `true` |
|
|
| [`revalidate`](#revalidate) | `false \| 'force-cache' \| 0 \| number` | `false` |
|
|
| [`fetchCache`](#fetchcache) | `'auto' \| 'default-cache' \| 'only-cache' \| 'force-cache' \| 'force-no-store' \| 'default-no-store' \| 'only-no-store'` | `'auto'` |
|
|
| [`runtime`](#runtime) | `'nodejs' \| 'edge'` | `'nodejs'` |
|
|
| [`preferredRegion`](#preferredregion) | `'auto' \| 'global' \| 'home' \| string \| string[]` | `'auto'` |
|
|
|
|
```tsx filename="layout.tsx / page.tsx / route.ts" switcher
|
|
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 default function MyComponent() {}
|
|
```
|
|
|
|
```jsx filename="layout.js / page.js / route.js" switcher
|
|
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 default function MyComponent() {}
|
|
```
|
|
|
|
> **Good to know**:
|
|
>
|
|
> - The values of the config options currently need be statically analyzable. For example `revalidate = 600` is valid, but `revalidate = 60 * 10` is not.
|
|
|
|
## Options
|
|
|
|
### `dynamic`
|
|
|
|
Change the dynamic behavior of a layout or page to fully static or fully dynamic.
|
|
|
|
```tsx filename="layout.tsx / page.tsx / route.ts" switcher
|
|
export const dynamic = 'auto'
|
|
// 'auto' | 'force-dynamic' | 'error' | 'force-static'
|
|
```
|
|
|
|
```js filename="layout.js / page.js / route.js" switcher
|
|
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 and dynamic data fetching of a layout or page by disabling all caching of `fetch` requests and always revalidating. This option is equivalent to:
|
|
|
|
- `getServerSideProps()` in the `pages` directory.
|
|
- 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 static data fetching of a layout or page by causing an error if any components use [dynamic functions](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions) or [dynamic fetches](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-data-fetching). 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', dynamicParams = false`.
|
|
- `dynamic = 'error'` changes the default of `dynamicParams` from `true` to `false`. You can opt back into dynamically rendering pages for dynamic params not generated by `generateStaticParams` by manually setting `dynamicParams = true`.
|
|
- **`'force-static'`**: Force static rendering and static data fetching of a layout or page by forcing [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers) and [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) to return empty values.
|
|
|
|
> **Good to know**:
|
|
>
|
|
> - Instructions on [how to migrate](/docs/app/building-your-application/upgrading/app-router-migration#step-6-migrating-data-fetching-methods) from `getServerSideProps` and `getStaticProps` to `dynamic: 'force-dynamic'` and `dynamic: 'error'` can be found in the [upgrade guide](/docs/app/building-your-application/upgrading/app-router-migration#step-6-migrating-data-fetching-methods).
|
|
|
|
### `dynamicParams`
|
|
|
|
Control what happens when a dynamic segment is visited that was not generated with [generateStaticParams](/docs/app/api-reference/functions/generate-static-params).
|
|
|
|
```tsx filename="layout.tsx / page.tsx" switcher
|
|
export const dynamicParams = true // true | false,
|
|
```
|
|
|
|
```js filename="layout.js / page.js / route.js" switcher
|
|
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.
|
|
> - When `dynamicParams = true`, the segment uses [Streaming Server Rendering](/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense).
|
|
> - If the `dynamic = 'error'` and `dynamic = 'force-static'` are used, it'll change the default of `dynamicParams` to `false`.
|
|
|
|
### `revalidate`
|
|
|
|
Set the default revalidation time for a layout or page. This option does not override the `revalidate` value set by individual `fetch` requests.
|
|
|
|
```tsx filename="layout.tsx / page.tsx / route.ts" switcher
|
|
export const revalidate = false
|
|
// false | 'force-cache' | 0 | number
|
|
```
|
|
|
|
```js filename="layout.js / page.js / route.js" switcher
|
|
export const revalidate = false
|
|
// false | 'force-cache' | 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 function](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions) 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](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-rendering) even if no dynamic functions or dynamic 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.
|
|
|
|
#### 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`
|
|
|
|
<details>
|
|
<summary>This is an advanced option that should only be used if you specifically need to override the default behavior.</summary>
|
|
|
|
By default, Next.js **will cache** any `fetch()` requests that are reachable **before** any [dynamic functions](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions) are used and **will not cache** `fetch` requests that are discovered **after** dynamic functions are used.
|
|
|
|
`fetchCache` allows you to override the default `cache` option of all `fetch` requests in a layout or page.
|
|
|
|
```tsx filename="layout.tsx / page.tsx / route.ts" switcher
|
|
export const fetchCache = 'auto'
|
|
// 'auto' | 'default-cache' | 'only-cache'
|
|
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'
|
|
```
|
|
|
|
```js filename="layout.js / page.js / route.js" switcher
|
|
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 functions with the `cache` option they provide and not cache `fetch` requests after dynamic functions.
|
|
- **`'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 functions 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 functions 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.
|
|
|
|
</details>
|
|
|
|
### `runtime`
|
|
|
|
```tsx filename="layout.tsx / page.tsx / route.ts" switcher
|
|
export const runtime = 'nodejs'
|
|
// 'edge' | 'nodejs'
|
|
```
|
|
|
|
```js filename="layout.js / page.js / route.js" switcher
|
|
export const runtime = 'nodejs'
|
|
// 'edge' | 'nodejs'
|
|
```
|
|
|
|
- **`nodejs`** (default)
|
|
- **`edge`**
|
|
|
|
Learn more about the [Edge and Node.js runtimes](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
|
|
|
|
### `preferredRegion`
|
|
|
|
```tsx filename="layout.tsx / page.tsx / route.ts" switcher
|
|
export const preferredRegion = 'auto'
|
|
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']
|
|
```
|
|
|
|
```js filename="layout.js / page.js / route.js" switcher
|
|
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.
|
|
|
|
### `generateStaticParams`
|
|
|
|
The `generateStaticParams` function can be used in combination with [dynamic route segments](/docs/app/building-your-application/routing/dynamic-routes) 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](/docs/app/api-reference/functions/generate-static-params) for more details.
|