Unverified Commit 368c154a authored by Joseph's avatar Joseph Committed by GitHub

docs: correction to dynamicParams migration (#96624)

`dynamicParams` is not supported in Cache Components
parent 62e294e8
...@@ -552,11 +552,11 @@ export default async function Page() { ...@@ -552,11 +552,11 @@ export default async function Page() {
## `generateStaticParams` and `dynamicParams` ## `generateStaticParams` and `dynamicParams`
Two behaviors change for [dynamic routes](/docs/app/api-reference/file-conventions/dynamic-routes) when Cache Components is enabled. Cache Components changes how [dynamic routes](/docs/app/api-reference/file-conventions/dynamic-routes) handle params.
### `generateStaticParams` must return at least one param ### `generateStaticParams` must return at least one param
**Returning an empty array now errors.** Without Cache Components, returning `[]` defers every path to the first runtime visit. With Cache Components, [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) must return at least one param so Next.js can prerender the route and validate it produces a non-empty [App Shell](/docs/app/glossary#app-shell). An empty array raises [`empty-generate-static-params`](/docs/messages/empty-generate-static-params). **Returning an empty array now errors.** Without Cache Components, returning `[]` defers every path to the first runtime visit. With Cache Components, [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) must return at least one param so Next.js can prerender the route and validate it produces a non-empty [static shell](/docs/app/glossary#static-shell). An empty array raises [`empty-generate-static-params`](/docs/messages/empty-generate-static-params).
```tsx filename="app/blog/[slug]/page.tsx" switcher ```tsx filename="app/blog/[slug]/page.tsx" switcher
// Before - defer all paths to runtime // Before - defer all paths to runtime
...@@ -588,13 +588,17 @@ export async function generateStaticParams() { ...@@ -588,13 +588,17 @@ export async function generateStaticParams() {
} }
``` ```
Paths you don't return are still served. Next.js serves the App Shell instantly, then upgrades it in the background once the params are known. See [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) for the full prerender-a-subset workflow. Paths you don't return are still served. Next.js prerenders a static shell for the unknown params and streams the rest at request time. See [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) for the full prerender-a-subset workflow.
### `dynamicParams` no longer blocks the first visit ### `dynamicParams` is not supported
**`dynamicParams: true` (the default) now serves an App Shell instead of blocking.** Previously, visiting a param not returned by `generateStaticParams` blocked the response while the page rendered. With Cache Components, Next.js serves the App Shell instantly, then upgrades it in the background with the now-known params. `dynamicParams: false` is unchanged: unspecified paths still 404. **Delete the export.** With Cache Components enabled, `export const dynamicParams` fails the build with `Route segment config "dynamicParams" is not compatible with nextConfig.cacheComponents`.
To produce the App Shell, pass the `params` promise into a [`<Suspense>`](/docs/app/api-reference/file-conventions/loading) boundary instead of awaiting it at the top of the component, so unknown params can still prerender. Params not returned by `generateStaticParams` are rendered on request. If you used `dynamicParams: false` to reject them, call [`notFound()`](/docs/app/api-reference/functions/not-found) in the page when the param doesn't resolve to real data.
### Await `params` inside `<Suspense>`
To produce the static shell, pass the `params` promise into a [`<Suspense>`](/docs/app/api-reference/file-conventions/loading) boundary instead of awaiting it at the top of the component, so unknown params can still prerender.
```tsx filename="app/blog/[slug]/page.tsx" switcher ```tsx filename="app/blog/[slug]/page.tsx" switcher
// Before - awaiting params at the top blocks the shell // Before - awaiting params at the top blocks the shell
...@@ -652,7 +656,7 @@ async function Post({ params }) { ...@@ -652,7 +656,7 @@ async function Post({ params }) {
} }
``` ```
The same applies to client hooks that read the route. When the route's pathname is fully known, they resolve during prerendering and need no boundary. When it depends on dynamic params not yet known, they suspend, wherever the component sits. A nav or breadcrumb in a shared layout, for instance, suspends while Next.js generates the App Shell for any route below it that has dynamic params. Wrap the component that reads the hook in `<Suspense>` (push the read down to the smallest leaf so the rest stays prerendered), or the build fails: The same applies to client hooks that read the route. When the route's pathname is fully known, they resolve during prerendering and need no boundary. When it depends on dynamic params not yet known, they suspend, wherever the component sits. A nav or breadcrumb in a shared layout, for instance, suspends while Next.js generates the static shell for any route below it that has dynamic params. Wrap the component that reads the hook in `<Suspense>` (push the read down to the smallest leaf so the rest stays prerendered), or the build fails:
- [`usePathname`](/docs/app/api-reference/functions/use-pathname) - [`usePathname`](/docs/app/api-reference/functions/use-pathname)
- [`useParams`](/docs/app/api-reference/functions/use-params) - [`useParams`](/docs/app/api-reference/functions/use-params)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment