Unverified Commit f8657de1 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: clarify ISR with Suspense params (#98210)

## Summary

- warn that awaiting params inside Suspense without Partial Prefetching
prevents unlisted paths from using ISR
- clarify that route data may still be cached even though the
URL-specific route renders on each request
- link the migration warning to the ISR with Cache Components guide

## Why

This follows up on #98209. The migration eval showed that an agent can
preserve generateStaticParams but move params beneath Suspense while
Partial Prefetching is disabled. That produces a fallback shell, but
unlisted paths do not use ISR.

Context:
https://github.com/vercel/next.js/discussions/98177#discussioncomment-18252316

## Testing

- git diff --check
- Prettier check for both changed guides
- commit hooks: Prettier and ESLint
parent 59b76e42
......@@ -21,7 +21,16 @@ For a visit to a URL whose params were included in `generateStaticParams`, Next.
If you have used [ISR](/docs/app/guides/incremental-static-regeneration) or [`fallback: true`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-true) in the Pages Router, this is the Cache Components equivalent.
Enable both [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) and [Partial Prefetching](/docs/app/api-reference/config/next-config-js/partialPrefetching). Cache Components produces the App Shell, while Partial Prefetching upgrades it to a full route once the params are known.
Enable both [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) and [Partial Prefetching](/docs/app/api-reference/config/next-config-js/partialPrefetching).
Cache Components prerenders a static shell that can include fallback UI. For paths not returned by `generateStaticParams`, Next.js can render the path on demand and store the completed result in the ISR cache.
Partial Prefetching determines whether the fallback is served before the URL-specific render completes:
- **With Partial Prefetching:** You can await `params` inside `<Suspense>`. Next.js can immediately serve the fallback for an unlisted path, render the URL-specific content, and store the completed result in the ISR cache.
- **Without Partial Prefetching:** The first request for an unlisted path must wait for the URL-specific render to complete. Await `params` outside any `<Suspense>` boundary, including one created by [`loading.tsx`](/docs/app/api-reference/file-conventions/loading), so Next.js creates an ISR entry for that URL.
> **Good to know:** Without Partial Prefetching, awaiting `params` inside `<Suspense>` causes Next.js to keep serving the shared fallback instead of creating a URL-specific ISR entry. Data fetched by the route can still be cached independently.
```ts filename="next.config.ts" highlight={4-5}
import type { NextConfig } from 'next'
......@@ -211,7 +220,8 @@ Instead, use [`generateStaticParams`](/docs/app/api-reference/functions/generate
If you are migrating from the Pages Router:
- `fallback: true` in `getStaticPaths` is now the default behavior with `cacheComponents`. Visitors get a `<Suspense>` fallback instantly and content streams in.
- `fallback: true` in `getStaticPaths` maps to Cache Components with Partial Prefetching. Visitors get a `<Suspense>` fallback instantly, and Next.js stores the completed route for subsequent visits.
- [`fallback: 'blocking'`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-blocking) maps to Cache Components without Partial Prefetching. Await `params` outside `<Suspense>` so the first request waits for the completed route, which Next.js then stores for subsequent visits.
- `router.isFallback` is not needed. The prerendering step generates a static shell, and you can grow it further with `'use cache'`.
- `getStaticProps` with `revalidate` maps to `'use cache'` with [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
- `getStaticPaths` maps to [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params).
......
......@@ -569,7 +569,7 @@ Cache Components changes how [dynamic routes](/docs/app/api-reference/file-conve
**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).
Keep `generateStaticParams` and return at least one real param. Removing the export opts the route out of ISR, so Next.js renders it on every request, even when it uses `use cache` for data. Read [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) to learn how `generateStaticParams` prerenders dynamic routes and upgrades unlisted paths after their first visit.
Keep `generateStaticParams` and return at least one real param. Removing the export opts the route out of ISR, so Next.js renders it on every request, even when it uses `use cache` for data. Read [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) to learn how `generateStaticParams` prerenders dynamic routes and how unlisted paths behave.
```tsx filename="app/blog/[slug]/page.tsx" switcher
// Before - defer all paths to runtime
......@@ -601,7 +601,9 @@ export async function generateStaticParams() {
}
```
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.
Paths you don't return are still served at request time.
> **Good to know:** When you use `generateStaticParams` without Partial Prefetching, await `params` outside `<Suspense>` to preserve ISR for unlisted paths. To serve a fallback while an unlisted path renders, enable [Partial Prefetching](/docs/app/api-reference/config/next-config-js/partialPrefetching) and await `params` inside `<Suspense>`. See [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) for details.
### `dynamicParams` is not supported
......@@ -613,7 +615,7 @@ Params not returned by `generateStaticParams` are rendered on request. If you us
### 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.
For routes that don't use `generateStaticParams`, 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. This lets Next.js prerender a static shell while the params remain unknown. For routes that use `generateStaticParams`, follow the ISR guidance above.
```tsx filename="app/blog/[slug]/page.tsx" switcher
// Before - awaiting params at the top blocks the shell
......@@ -671,7 +673,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 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:
Client hooks that read the route follow the same Suspense pattern. When the route's pathname is fully known, they resolve during prerendering and need no boundary. When the pathname depends on dynamic params not yet known, the hooks 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)
- [`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