Per-request nondeterministic output
A Server Component needs a different random value for each request without reading cookies or headers.
Next.js 16+ · Function
connection
connection() makes rendering wait for a real incoming request before continuing. Use it when per-request output is needed but the component does not use request-time APIs such as cookies or headers.
- Since
- 15.0.0
How it works
Call connection() in an async Server Component when rendering must wait for an incoming request even though the code does not use request-time APIs. Everything after the await is excluded from prerendering and runs for each request; the returned promise is only used for synchronization.
Syntax
function connection(): Promise<void>Returns
Promise<void>
Key points
- It marks the remainder of a component's rendering as dependent on an incoming request.
- Use it for per-request output produced by ordinary code, including values from Math.random() or new Date().
- A synchronous database query placed after connection() is kept out of prerendering together with the component's output.
- Its API is intentionally parameterless.
- Await the result for its rendering effect; it does not provide a value.
Common mistakes
- Do not add connection() when request-time APIs already make the route dynamic; use it only when dynamic rendering is otherwise required.
- When Cache Components are enabled, prefer io() because it can also be cached and prefetched.
- Do not treat the resolved value as data; await the promise only to mark the following work as request-time.
Example: Request-time rendering
import { connection } from 'next/server'
export default async function Page() {
await connection()
const value = Math.random()
return <p>{value}</p>
}Waits for a real request before generating a per-request random value.
When to use it
Request-time synchronous data access
A synchronous database driver query should run during the request rather than during prerendering.
Runtime configuration
A runtime environment variable must be read per request instead of being captured during the build.
Interview questions
QWhat does connection() do?
connection() has no parameters and returns a Promise<void>. Awaiting it tells Next.js to wait for an incoming request, so work after the call is excluded from prerendering.
Follow-up: When is it unnecessary? It is unnecessary if the component already uses request-time APIs such as cookies or headers, because those APIs already require dynamic rendering.
QWhen should a Server Component call connection()?
Use it when output varies per request without using request-time APIs, such as output based on Math.random() or new Date(). Place it before the request-dependent operation.
Follow-up: What happens to the surrounding UI? The request-bound component can stream from the nearest Suspense boundary while the static shell remains prerendered.
QHow does connection() relate to unstable_noStore and Cache Components?
connection() replaced unstable_noStore and was introduced as a request-bound rendering API. It became stable in Next.js 15.0.0.
Follow-up: What should be preferred with Cache Components? Prefer io() for excluding content from the static shell because it can also be cached and prefetched.
Related
Request-time APIscookiesheadersunstable_noStoreio()Cache ComponentsSuspense