How it works
Default model. During next build, Next.js renders each route's Server Component tree. A request-time API called during that render signals that the output depends on the request, and the route is marked dynamic: no HTML is stored, and every request renders it again. A fetch is judged by position: the docs' fetchCache: 'auto' rule fetches a request with no cache option once at build if it is reached before any request-time API, and on every request if reached after one. Nothing else is tracked. Clocks, random numbers, file reads and database drivers simply run at build time. In the experiment above, /fetch-default showed fetch 1 on every request (the build's call), while /fetch-nostore's counter rose by one per request.
The decision covers the whole route because the output is one HTML document plus one RSC payload, prerendered or not. Layouts count: a dynamic layout makes all its child routes dynamic.
Cache Components model. The same build render now treats three kinds of work as "not known at build time": request data (cookies(), headers(), searchParams, params with no generateStaticParams value, connection()), uncached I/O (fetch and other async work outside use cache), and unstable values (Date.now(), Math.random(), crypto.randomUUID()). Each must be handled where it appears:
- inside
<Suspense>: the nearest boundary's fallback is prerendered and the subtree is rendered per request, streamed into the same response;
- inside
use cache: the function or component runs at build time and its result is cached and placed in the shell;
- after
await connection() (for the unstable values), inside <Suspense>.
Unhandled work fails the build with a message naming the route and the fixes. Two kinds of message appeared in 16.4.5, one for request data or uncached I/O and one for unstable values:
Error: Route "/cookies": Next.js encountered uncached or runtime data during prerendering.
`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.
Ways to fix this:
- [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
- [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)
- [block] Set `export const instant = false` to allow a blocking route
Error: Route "/now": Next.js encountered the unstable value `Date.now()` while prerendering.
After moving each read into <Suspense> or use cache, the same build printed:
├ ƒ /blocking
├ /blog/[slug]
│ ├ ◐ /blog/[slug]
│ ├ ○ /blog/a
│ └ ○ /blog/b
├ ◐ /cookies
└ ○ /usecache 15m 1y
○ (Static) prerendered as static content
◐ (Partial Prerender) prerendered as static HTML with dynamic server-streamed content
ƒ (Dynamic) server-rendered on demand
/blocking reads cookies() with export const instant = false; /usecache fetches inside a use cache function and gets the default profile's 15-minute revalidation.
Edge cases
- Suspense alone isn't a dynamic marker. The docs say a boundary around purely synchronous work still completes during prerendering; only what's inside it decides.
- Sync database drivers.
better-sqlite3 or node:sqlite queries complete at build time in both models. Call connection() first if the data must be per request.
- Module-scope reads (
await readFile at the top of the module) run once and are not treated as uncached data under Cache Components.
performance.now() is not guarded; the docs treat it as telemetry.
Real-world scenario
A marketing site on the default model reads a locale cookie in the root layout. Every page turns ƒ, the CDN gets private, no-store, and time to first byte rises on every page. Fixes, by model: move locale into the URL ([locale] with generateStaticParams) so pages stay ●; or enable Cache Components and read the cookie inside a <Suspense> boundary, so only that part streams.
Trade-offs
The default model is easy to reason about at the route level but coarse: one personalised widget costs the whole page its static HTML. Cache Components gives a static shell to nearly every route, at the price of explicitness: every uncached read needs a boundary or a cache decision, and segment configs (dynamic, revalidate, dynamicParams) are replaced by use cache, cacheLife and instant. The docs say Cache Components will be enabled everywhere in the next major release, with the option removed.