Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 72 ยท Data Fetching and Caching

Static vs Dynamic Rendering

Learn what makes a Next.js route static or dynamic: cookies, headers, searchParams, connection(), force-dynamic, and how to read the build output symbols.

Every route in a Next.js app ends up in one of two worlds. A static route is rendered once, usually during next build, and the finished HTML is reused for every visitor. A dynamic route is rendered again for each request, so it can use information that only exists when a visitor arrives: their cookies, their headers, the query string they typed.

You rarely choose between these worlds with a switch. Next.js decides for you by watching what your components do while they render. Use one request-specific function and the whole route becomes dynamic; avoid them and it stays static. This lesson teaches the rules, shows how to read the build report that tells you what Next.js decided, and explains the mistake that quietly makes a whole site slower. It builds on the layers described in Caching in Next.js: the Big Picture.

Static and dynamic in one picture

Two kinds of routes

Static Rendered once, before any visitor arrives.
Dynamic Rendered again for every request.

Next.js picks one per route by watching your code.

1 / 3

Static is the cheaper and faster default. Dynamic is the tool you reach for when the page genuinely depends on who is asking.

What makes a route dynamic

Next.js calls functions that read the incoming request request-time APIs (you will also see them called dynamic APIs). A static build has no request, so there is nothing to read. If a component tries, Next.js learns the route needs a real request and renders it on demand instead.

You use What it reads Effect
await cookies() from next/headers The request's cookies Route is dynamic
await headers() from next/headers The request's headers Route is dynamic
searchParams page prop (a promise) The query string Page is dynamic
await connection() from next/server Nothing, it only waits for a real request Route is dynamic
draftMode() Preview mode state Route is dynamic while a preview is on

Notice that params is not on the list by itself. A dynamic segment such as [slug] can be fully static if you list the values ahead of time with generateStaticParams, which you will meet in Static Generation and generateStaticParams.

TSX
// app/dashboard/page.tsx
import { cookies } from 'next/headers';

export default async function Dashboard() {
  const cookieStore = await cookies(); // needs a request: dynamic route
  const theme = cookieStore.get('theme')?.value ?? 'light';
  return <main data-theme={theme}>Welcome back</main>;
}
TSX
// app/search/page.tsx
export default async function Search({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>;
}) {
  const { q } = await searchParams; // reading the query string: dynamic page
  return <h1>Results for {q ?? 'nothing yet'}</h1>;
}

Since Next.js 15, cookies(), headers(), params and searchParams are all asynchronous. That is deliberate: awaiting is the moment Next.js notices you need the request.

Opting in on purpose

Sometimes a route reads nothing from the request but still must not be prerendered, for example a page that shows the current time or calls an API that changes on every call. Call connection() first to say so:

TSX
import { connection } from 'next/server';

export default async function Clock() {
  await connection(); // wait for a real request before rendering the rest
  return <p>{new Date().toISOString()}</p>;
}

Route segment config

In the classic model you can also force a route's mode with exports in the page or layout file:

TSX
export const dynamic = 'force-dynamic'; // always render on request
// 'force-static' renders once and returns empty cookies and headers
// 'error' fails the build if anything dynamic is found
// 'auto' is the default: let Next.js decide

force-dynamic is a blunt tool. It is useful while debugging, but if you reach for it often, the cleaner fix is usually to cache the slow part (see Revalidating Data) instead of giving up on static output for the whole route.

Version note. The dynamic, revalidate and fetchCache exports belong to the classic caching model. When you turn on Cache Components (cacheComponents: true in next.config.ts), they are not supported, and the rules change to "everything is dynamic unless you cache it". The use cache Directive and Cache Components explains that model, and Partial Prerendering shows how a single route can be both static and dynamic.

What about fetch and databases?

In Next.js 15 and later, a fetch call is not cached by default. During next build, a route that only uses fetch and no request-time API is still prerendered: the request runs once at build time and the result goes into the HTML. If the same route also uses cookies() or another request-time API, Next.js fetches on every request. A direct database or ORM call behaves the same way: it simply runs while the route renders, so for a static route it runs at build time.

That surprises people. A page that "loads fresh data" can be frozen at build time because nothing in it touched the request. If you want fresh data per request, either read a request-time API, call connection(), or revalidate on a schedule.

How Next.js actually notices

You can picture the mechanism as a trap door. During a build, Next.js renders each route with a context that has no request. A request-time function does not return an empty value. It throws a special error. Next.js catches that error, records "this route needs a request", and moves on. The first live example re-creates exactly that idea.

Node.js Prerendering with a trap door

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Real Next.js does more (it records which API was used, supports partial prerendering and handles errors you could mistake for dynamic usage), but the core idea is the same. You never wrote the word "dynamic" anywhere. Using the API was the declaration.

Reading the build output

next build ends with a report listing every route with a symbol. Here is an illustrative example for the routes above:

TEXT
Route (app)
โ”Œ โ—‹ /
โ”œ โ—‹ /about
โ”œ โ— /blog/[slug]
โ”œ ฦ’ /dashboard
โ”” ฦ’ /search

โ—‹  (Static)   prerendered as static content
โ—  (SSG)      prerendered as static HTML (uses generateStaticParams)
ฦ’  (Dynamic)  server-rendered on demand

With Cache Components turned on you will also see โ— (Partial Prerender): a static shell with dynamic parts streamed in. Make a habit of reading this report before you deploy. If your marketing homepage shows ฦ’, something in it, perhaps a layout, is reading the request.

The layout trap

A dynamic API in a layout makes every page below that layout dynamic, because the layout renders for each of them. The classic case is a root layout that reads a cookie to pick a theme. It looks harmless, and it silently turns the entire site dynamic. The second live example shows the effect.

Node.js One cookie read, every page dynamic

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The fix is to push request reading down to the smallest place that needs it. Read the cookie in the one component that needs it, or move the preference to the browser: a small Client Component can apply the theme after load, so the layout stays static. Later lessons show how Suspense and Cache Components let a single dynamic component live inside an otherwise static page.

Client-side reading and Suspense

useSearchParams() in a Client Component reads the query string in the browser. On a statically prerendered page, Next.js asks you to wrap that component in a Suspense boundary. Without it, the whole page would have to wait for client-side data, so the build fails with a "missing Suspense boundary" message. Wrapping the small component fixes it and keeps the rest of the page static. Search Params and Navigation Hooks covers the hook itself.

Quick checklist

  • Open the build report and check the symbol of every important route.
  • If a route is ฦ’ and should not be, look for cookies(), headers(), searchParams and connection() in the page and its layouts.
  • Keep personalization in small leaf components or in the browser.
  • Reserve force-dynamic for debugging and for pages that truly must not be stored.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these makes a route dynamic?

    cookies() needs a real request, so Next.js cannot prerender the route. A segment listed in generateStaticParams can still be static.
  2. 2. A root layout calls await headers(). What happens to the pages below it?

    A layout renders as part of every page beneath it, so a request-time API there makes all of those pages dynamic.
  3. 3. In the build report, what does the ฦ’ symbol mean?

    ฦ’ marks a dynamic route that is server-rendered on demand. โ—‹ is static and โ— is static HTML produced through generateStaticParams.
  4. 4. Why does a page that only uses fetch (and no request-time API) often show data frozen at build time?

    Uncached fetch is not what makes a route dynamic. If no request-time API is used, the route is prerendered and the fetched result becomes part of the HTML.

Summary

  • A static route is rendered once and shared; a dynamic route is rendered for each request.
  • Next.js decides by watching your code: cookies(), headers(), the searchParams prop and connection() all need a real request and make the route dynamic.
  • A request-time API in a layout makes every page beneath it dynamic, so read the request in the smallest component possible.
  • fetch and database calls do not make a route dynamic on their own; in a static route they run at build time.
  • The build report marks routes โ—‹ static, โ— SSG and ฦ’ dynamic (โ— with Cache Components): read it before every deploy.
  • export const dynamic = 'force-dynamic' is a blunt override from the classic model and is not supported with Cache Components.

Next: Data Access Layers and ORMs