Static vs Dynamic Detection

~20 min · dynamic functions, force-static, force-dynamic

Level 0Curious

0 XP0/68 lessons0/11 achievements

0/120 XP to next level120 XP to go0% complete

The detector reads your code

Next.js decides per route whether to render at build time (static) or per request (dynamic). It doesn't ask you — it watches which APIs you call:

API	Effect
`cookies()`	Forces dynamic
`headers()`	Forces dynamic
`searchParams`	Forces dynamic
`connection()`	Explicit opt-in to dynamic
`fetch()` without cache	Treated as dynamic data point

Override when you must

Sometimes the detector picks the wrong default for what you actually want. export const dynamic = 'force-static' errors if the route uses a dynamic API; 'force-dynamic' guarantees per-request rendering even when nothing dynamic is in the code.

Why this matters for cost

A route that's static can be served from CDN with no compute cost per request. A dynamic route runs your code every time. Pick on purpose.

Code

Static: cached fetch only·tsx

export default async function AboutPage() {
  const res = await fetch('https://api.example.com/about', {
    cache: 'force-cache',
  });
  return <article>{(await res.json()).text}</article>;
}
// Rendered once at build, served as static HTML.

Dynamic via cookies()·tsx

import { cookies } from 'next/headers';

export default async function Dashboard() {
  const session = (await cookies()).get('session');
  const data = await fetchUserData(session?.value);
  return <DashboardView data={data} />;
}
// Per-request render.

Force one mode at the route level·tsx

export const dynamic = 'force-static';   // errors if you use cookies()/headers()
export const dynamic = 'force-dynamic';  // per-request even without dynamic APIs
export const dynamic = 'auto';           // default — let the detector decide

External links

Static and dynamic rendering

Exercise

Add a feature flag check (using cookies()) to a previously-static page. Confirm in build output (next build) that the route flipped from ○ Static to ƒ Dynamic, and discuss whether that's the trade you wanted.