diff --git a/docs/01-app/02-guides/incremental-static-regeneration.mdx b/docs/01-app/02-guides/incremental-static-regeneration.mdx index d4b71160a4d91..f087455c48bd1 100644 --- a/docs/01-app/02-guides/incremental-static-regeneration.mdx +++ b/docs/01-app/02-guides/incremental-static-regeneration.mdx @@ -97,7 +97,7 @@ Here's how this example works: 3. After 60 seconds has passed, the next request will still return the cached (now stale) page 4. The cache is invalidated and a new version of the page begins generating in the background 5. Once generated successfully, the next request will return the updated page and cache it for subsequent requests -6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [dynamicParams](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) value. However, if the post does not exist, then 404 is returned. +6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [dynamicParams](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) value. However, if the post does not exist, then 404 is returned. @@ -207,7 +207,7 @@ Here's how this example works: ### Route segment config - [`revalidate`](/docs/app/guides/caching-without-cache-components#route-segment-config-revalidate) -- [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) +- [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) ### Functions diff --git a/docs/01-app/02-guides/migrating/app-router-migration.mdx b/docs/01-app/02-guides/migrating/app-router-migration.mdx index 227ca52f0dabe..84245269e8763 100644 --- a/docs/01-app/02-guides/migrating/app-router-migration.mdx +++ b/docs/01-app/02-guides/migrating/app-router-migration.mdx @@ -824,7 +824,7 @@ export default function Post({ post }) { } ``` -In the `app` directory the [`config.dynamicParams` property](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) controls how params outside of [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) are handled: +In the `app` directory the [`config.dynamicParams` property](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) controls how params outside of [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) are handled: - **`true`**: (default) Dynamic segments not included in `generateStaticParams` are generated on demand. - **`false`**: Dynamic segments not included in `generateStaticParams` will return a 404. @@ -851,7 +851,7 @@ export default async function Post({ params }) { } ``` -With [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) set to `true` (the default), when a route segment is requested that hasn't been generated, it will be server-rendered and cached. +With [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) set to `true` (the default), when a route segment is requested that hasn't been generated, it will be server-rendered and cached. #### Incremental Static Regeneration (`getStaticProps` with `revalidate`) diff --git a/docs/01-app/02-guides/upgrading/codemods.mdx b/docs/01-app/02-guides/upgrading/codemods.mdx index cb2015aa3c747..de15d24178096 100644 --- a/docs/01-app/02-guides/upgrading/codemods.mdx +++ b/docs/01-app/02-guides/upgrading/codemods.mdx @@ -217,7 +217,7 @@ export default eslintConfig npx @next/codemod@latest app-dir-runtime-config-experimental-edge . ``` -This codemod transforms [Route Segment Config `runtime`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#runtime) value `experimental-edge` to `edge`. +This codemod transforms [Route Segment Config `runtime`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/runtime) value `experimental-edge` to `edge`. For example: diff --git a/docs/01-app/02-guides/upgrading/version-15.mdx b/docs/01-app/02-guides/upgrading/version-15.mdx index e55486dffab3c..b87c792c2509a 100644 --- a/docs/01-app/02-guides/upgrading/version-15.mdx +++ b/docs/01-app/02-guides/upgrading/version-15.mdx @@ -476,7 +476,7 @@ export async function GET(request, segmentData) { ## `runtime` configuration (Breaking change) -The `runtime` [segment configuration](/docs/app/api-reference/file-conventions/route-segment-config#runtime) previously supported a value of `experimental-edge` in addition to `edge`. Both configurations refer to the same thing, and to simplify the options, we will now error if `experimental-edge` is used. To fix this, update your `runtime` configuration to `edge`. A [codemod](/docs/app/guides/upgrading/codemods#app-dir-runtime-config-experimental-edge) is available to automatically do this. +The `runtime` [segment configuration](/docs/app/api-reference/file-conventions/route-segment-config/runtime) previously supported a value of `experimental-edge` in addition to `edge`. Both configurations refer to the same thing, and to simplify the options, we will now error if `experimental-edge` is used. To fix this, update your `runtime` configuration to `edge`. A [codemod](/docs/app/guides/upgrading/codemods#app-dir-runtime-config-experimental-edge) is available to automatically do this. diff --git a/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/dynamicParams.mdx b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/dynamicParams.mdx new file mode 100644 index 0000000000000..4fc959699e8aa --- /dev/null +++ b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/dynamicParams.mdx @@ -0,0 +1,22 @@ +--- +title: dynamicParams +description: API reference for the dynamicParams route segment config option. +--- + +The `dynamicParams` option allows you to 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 route segments not included in `generateStaticParams` are generated at request time. +- **`false`**: Dynamic route 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. +> - `dynamicParams` is not available when [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled. diff --git a/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/index.mdx b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/index.mdx new file mode 100644 index 0000000000000..d9c308413df0b --- /dev/null +++ b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/index.mdx @@ -0,0 +1,21 @@ +--- +title: Route Segment Config +description: Learn about how to configure options for Next.js route segments. +--- + +The Route Segment Config options allow you to configure the behavior of a [Page](/docs/app/api-reference/file-conventions/page), [Layout](/docs/app/api-reference/file-conventions/layout), or [Route Handler](/docs/app/api-reference/file-conventions/route) by directly exporting the following variables: + +| Option | Type | Default | +| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------- | +| [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) | `boolean` | `true` | +| [`runtime`](/docs/app/api-reference/file-conventions/route-segment-config/runtime) | `'nodejs' \| 'edge'` | `'nodejs'` | +| [`preferredRegion`](/docs/app/api-reference/file-conventions/route-segment-config/preferredRegion) | `'auto' \| 'global' \| 'home' \| string \| string[]` | `'auto'` | +| [`maxDuration`](/docs/app/api-reference/file-conventions/route-segment-config/maxDuration) | `number` | Set by deployment platform | + +## Version History + +| Version | | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `v16.0.0` | `dynamic`, `dynamicParams`, `revalidate`, and `fetchCache` removed when [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled. See [Caching and Revalidating (Previous Model)](/docs/app/guides/caching-without-cache-components#route-segment-config). | +| `v16.0.0` | `export const experimental_ppr = true` removed. A [codemod](/docs/app/guides/upgrading/codemods#remove-experimental_ppr-route-segment-config-from-app-router-pages-and-layouts) is available. | +| `v15.0.0-RC` | `export const runtime = "experimental-edge"` deprecated. A [codemod](/docs/app/guides/upgrading/codemods#transform-app-router-route-segment-config-runtime-value-from-experimental-edge-to-edge) is available. | diff --git a/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/maxDuration.mdx b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/maxDuration.mdx new file mode 100644 index 0000000000000..b0ee647368028 --- /dev/null +++ b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/maxDuration.mdx @@ -0,0 +1,24 @@ +--- +title: maxDuration +description: API reference for the maxDuration route segment config option. +--- + +The `maxDuration` option allows you to set the maximum execution time (in seconds) for server-side logic in a route segment. Deployment platforms can use `maxDuration` from the Next.js build output to add specific execution limits. + +```tsx filename="layout.tsx | page.tsx | route.ts" switcher +export const maxDuration = 5 +``` + +```js filename="layout.js | page.js | route.js" switcher +export const maxDuration = 5 +``` + +## Server Actions + +If using [Server Actions](/docs/app/getting-started/mutating-data), set the `maxDuration` at the page level to change the default timeout of all Server Actions used on the page. + +## Version History + +| Version | Changes | +| ---------- | ------------------------- | +| `v13.4.10` | `maxDuration` introduced. | diff --git a/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/preferredRegion.mdx b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/preferredRegion.mdx new file mode 100644 index 0000000000000..e307a6558b748 --- /dev/null +++ b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/preferredRegion.mdx @@ -0,0 +1,33 @@ +--- +title: preferredRegion +description: API reference for the preferredRegion route segment config option. +--- + +The `preferredRegion` option allows you to specify the preferred deployment region for a route segment. This value is passed to your deployment platform. + +```tsx filename="layout.tsx | page.tsx | route.ts" switcher +export const preferredRegion = // string || string[] +``` + +```js filename="layout.js | page.js | route.js" switcher +export const preferredRegion = // string || string[] +``` + +- **`string`**: Deploy the route to a specific region. Available region codes are platform-specific. For example, `'iad1'`. +- **`string[]`**: Deploy the route to multiple specific regions. The route is deployed to **all** listed regions, not a single one chosen from the list. For example, `['iad1', 'sfo1']`. + +> **Good to know**: +> +> - If a `preferredRegion` is not specified, it will inherit the option of the nearest parent layout. The root layout defaults to `'auto'`. +> - A child segment's value overrides the parent, values are not merged. +> - Next.js passes the region values through to the deployment platform. The exact behavior and available region codes are platform-specific. Refer to your deployment platform's documentation for supported values. + +## Vercel + +If deploying Next.js on Vercel, regions are only supported if `export const runtime = 'edge'` is set. The following options can be passed: + +- **`'auto'`** (default): Uses the default region. +- **`'global'`**: Prefer deploying the route to all availableregions. +- **`'home'`**: Prefer deploying the route to the home region. + +If an unsupported value is passed, an error will be thrown. diff --git a/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/runtime.mdx b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/runtime.mdx new file mode 100644 index 0000000000000..7634c9240d69c --- /dev/null +++ b/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/runtime.mdx @@ -0,0 +1,24 @@ +--- +title: runtime +description: API reference for the runtime route segment config option. +--- + +The `runtime` option allows you to select the JavaScript runtime used for rendering your route. + +```tsx filename="layout.tsx | page.tsx | route.ts" switcher +export const runtime = 'nodejs' +// 'nodejs' | 'edge' +``` + +```js filename="layout.js | page.js | route.js" switcher +export const runtime = 'nodejs' +// 'nodejs' | 'edge' +``` + +- **`'nodejs'`** (default) +- **`'edge'`** + +> **Good to know**: +> +> - Using `runtime: 'edge'` is **not supported** for Cache Components. +> - This option cannot be used in [Proxy](/docs/app/api-reference/file-conventions/proxy). diff --git a/docs/01-app/03-api-reference/03-file-conventions/proxy.mdx b/docs/01-app/03-api-reference/03-file-conventions/proxy.mdx index 3794e5eeb656d..9044b7670866c 100644 --- a/docs/01-app/03-api-reference/03-file-conventions/proxy.mdx +++ b/docs/01-app/03-api-reference/03-file-conventions/proxy.mdx @@ -216,7 +216,7 @@ Proxy will be invoked for **every route in your project**. Given this, it's cruc ## Runtime -Proxy defaults to using the Node.js runtime. The [`runtime`](/docs/app/api-reference/file-conventions/route-segment-config#runtime) config option is not available in Proxy files. Setting the `runtime` config option in Proxy will throw an error. +Proxy defaults to using the Node.js runtime. The [`runtime`](/docs/app/api-reference/file-conventions/route-segment-config/runtime) config option is not available in Proxy files. Setting the `runtime` config option in Proxy will throw an error. ## Advanced Proxy flags diff --git a/docs/01-app/03-api-reference/03-file-conventions/route-segment-config.mdx b/docs/01-app/03-api-reference/03-file-conventions/route-segment-config.mdx deleted file mode 100644 index da15133921666..0000000000000 --- a/docs/01-app/03-api-reference/03-file-conventions/route-segment-config.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Route Segment Config -description: Learn about how to configure options for Next.js route segments. ---- - -> **Good to know**: -> -> - The `dynamic`, `revalidate`, and `fetchCache` options are not available when [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled. See [Caching and Revalidating (Previous Model)](/docs/app/guides/caching-without-cache-components#route-segment-config) for their documentation. -> - 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 allow you to configure the behavior of a [Page](/docs/app/api-reference/file-conventions/page), [Layout](/docs/app/api-reference/file-conventions/layout), or [Route Handler](/docs/app/api-reference/file-conventions/route) by directly exporting the following variables: - -| Option | Type | Default | -| ------------------------------------- | ---------------------------------------------------- | -------------------------- | -| [`dynamicParams`](#dynamicparams) | `boolean` | `true` | -| [`runtime`](#runtime) | `'nodejs' \| 'edge'` | `'nodejs'` | -| [`preferredRegion`](#preferredregion) | `'auto' \| 'global' \| 'home' \| string \| string[]` | `'auto'` | -| [`maxDuration`](#maxduration) | `number` | Set by deployment platform | - -## Options - -### `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. -> - To statically render all paths the first time they're visited, you'll need to return an empty array in `generateStaticParams` or use `export const dynamic = 'force-static'`. -> - When `dynamicParams = true`, the segment uses [Streaming Server Rendering](/docs/app/getting-started/linking-and-navigating#streaming). - -### `runtime` - -Use the Node.js runtime for rendering your application. This option cannot be used in [Proxy](/docs/app/api-reference/file-conventions/proxy). - -> **Good to know**: Using `runtime: 'edge'` is **not supported** for Cache Components. - -```tsx filename="layout.tsx | page.tsx | route.ts" switcher -export const runtime = 'nodejs' -// 'nodejs' | 'edge' -``` - -```js filename="layout.js | page.js | route.js" switcher -export const runtime = 'nodejs' -// 'nodejs' | 'edge' -``` - -- **`'nodejs'`** (default) -- **`'edge'`** - -### `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. - -### `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. - -```tsx filename="layout.tsx | page.tsx | route.ts" switcher -export const maxDuration = 5 -``` - -```js filename="layout.js | page.js | route.js" switcher -export const maxDuration = 5 -``` - -> **Good to know**: -> -> - If using [Server Actions](/docs/app/getting-started/mutating-data), 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](/docs/app/api-reference/file-conventions/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. - -## Version History - -| Version | | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `v16.0.0` | `export const experimental_ppr = true` removed. A [codemod](/docs/app/guides/upgrading/codemods#remove-experimental_ppr-route-segment-config-from-app-router-pages-and-layouts) is available. | -| `v15.0.0-RC` | `export const runtime = "experimental-edge"` deprecated. A [codemod](/docs/app/guides/upgrading/codemods#transform-app-router-route-segment-config-runtime-value-from-experimental-edge-to-edge) is available. | diff --git a/docs/01-app/03-api-reference/04-functions/after.mdx b/docs/01-app/03-api-reference/04-functions/after.mdx index 6a24bd607c1fc..5f8e2833cc87f 100644 --- a/docs/01-app/03-api-reference/04-functions/after.mdx +++ b/docs/01-app/03-api-reference/04-functions/after.mdx @@ -47,7 +47,7 @@ export default function Layout({ children }) { ### Duration -`after` will run for the platform's default or configured max duration of your route. If your platform supports it, you can configure the timeout limit using the [`maxDuration`](/docs/app/api-reference/file-conventions/route-segment-config#maxduration) route segment config. +`after` will run for the platform's default or configured max duration of your route. If your platform supports it, you can configure the timeout limit using the [`maxDuration`](/docs/app/api-reference/file-conventions/route-segment-config/maxDuration) route segment config. ## Good to know diff --git a/docs/01-app/03-api-reference/04-functions/generate-static-params.mdx b/docs/01-app/03-api-reference/04-functions/generate-static-params.mdx index 8c6b12d66412f..f186811b20784 100644 --- a/docs/01-app/03-api-reference/04-functions/generate-static-params.mdx +++ b/docs/01-app/03-api-reference/04-functions/generate-static-params.mdx @@ -53,7 +53,7 @@ export default async function Page({ params }) { > **Good to know**: > -> - You can use the [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) segment config option to control what happens when a dynamic segment is visited that was not generated with `generateStaticParams`. +> - You can use the [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) segment config option to control what happens when a dynamic segment is visited that was not generated with `generateStaticParams`. > - You must return [an empty array from `generateStaticParams`](#all-paths-at-build-time) or utilize [`export const dynamic = 'force-static'`](/docs/app/guides/caching-without-cache-components#dynamic) in order to revalidate (ISR) [paths at runtime](#all-paths-at-runtime). > - During `next dev`, `generateStaticParams` will be called when you navigate to a route. > - During `next build`, `generateStaticParams` runs before the corresponding Layouts or Pages are generated. @@ -257,7 +257,7 @@ export async function generateStaticParams() { } ``` -Then, by using the [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) segment config option, you can control what happens when a dynamic segment is visited that was not generated with `generateStaticParams`. +Then, by using the [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) segment config option, you can control what happens when a dynamic segment is visited that was not generated with `generateStaticParams`. ```tsx filename="app/blog/[slug]/page.tsx" switcher // All posts besides the top 10 will be a 404