# Next.js from Zero - React Grows a Server
> What Next.js adds to React and why - file routing, server components, data fetching, caching - explained from the request up, so the framework stops feeling like magic conventions.
---
# Next.js from Zero - React Grows a Server
You know React. Then you open a Next.js project and the rules seem to have changed: components run
on a server now, some files are magically routes, `useState` throws an error in one file and works
fine in the next, and pages are somehow stale until you sprinkle the right incantation. None of it
is magic - all of it follows from one move: **Next.js puts a server in front of your React app**,
and everything the framework does is about deciding what happens on that server versus in the
browser.
This guide builds that model from the request up. By the end, "why is this a server component," "why
is this page cached," and "why did hydration fail" all have answers you can reason to, not memorize.
> βοΈ New to React itself? Read [React from Zero](../react-from-zero/_guide.md) first - this guide
> assumes components, props, state, and effects are already solid.
## How to read this
- **In a panic right now?** Jump to [Phase 7: When Next.js Breaks](07-when-it-breaks.md) and use the
cheat-card at the top.
- **Want it to finally make sense?** Read in order - the server/client split in Phase 3 is the hinge
the whole framework turns on.
## The phases
1. **[What Next.js Actually Is](01-what-nextjs-actually-is.md)** - what a plain React app can't do,
and what putting a server in front of it buys you.
2. **[Routing with Files](02-routing-with-files.md)** - folders become URLs; `page`, `layout`, and
dynamic segments.
3. **[Server and Client Components](03-server-and-client-components.md)** - the big split: what runs
where, and what `'use client'` really marks.
4. **[Data on the Server](04-data-on-the-server.md)** - async components, `loading.tsx`, streaming,
and error boundaries.
5. **[Mutations: Forms and Server Actions](05-mutations-and-server-actions.md)** - writing data
without hand-building an API layer.
6. **[Static, Dynamic, and the Cache](06-static-dynamic-and-the-cache.md)** - why your page is stale
(or slow), and how Next decides at build time.
7. **[When Next.js Breaks](07-when-it-breaks.md)** - hydration mismatches, hook errors, serialization
walls, and stale pages, decoded.
8. **[Where to Go Next](08-where-to-go-next.md)** - deployment, metadata, images, and what to ignore.
> Deliberately deferred to follow-up guides: authentication patterns, advanced caching internals,
> parallel/intercepting routes, middleware-heavy architectures, and testing. Core model first.
---
# What Next.js Actually Is
A plain React app (the Vite kind you built in React from Zero) has a specific shape, and that shape
has specific costs. Next.js exists because of those costs. Before touching the framework, look
squarely at what it's fixing - otherwise every Next convention feels like ceremony.
## What a plain React app actually ships
Build a Vite React app and look at what the server sends the browser:
```html
```
That's it. An empty div and a script tag. Everything the user sees is built *in their browser*,
after the JavaScript downloads, parses, and runs, and after that JavaScript fetches whatever data it
needs. This is a **single-page application** (SPA), and the sequence looks like:
```mermaid
sequenceDiagram
Browser->>Server: GET /products
Server-->>Browser: empty HTML + JS bundle
Browser->>Browser: run React, render shell
Browser->>API: fetch product data
API-->>Browser: JSON
Browser->>Browser: render actual content
```
Four steps before content appears, two of them network round-trips. The costs:
- **Slow first paint on slow devices and networks.** The user stares at a blank page (or a spinner)
while the bundle loads and the data fetch completes.
- **Search engines and link previews see an empty div.** Crawlers have gotten better at running
JavaScript, but "sometimes, eventually, partially" - and social-card scrapers mostly don't try.
For content that lives on being found, that's disqualifying.
- **Your data layer is public.** Every fetch happens in the browser, so every API endpoint, and the
tokens to call it, are visible to anyone who opens DevTools.
For an app behind a login (a dashboard, an editor), these costs are often fine, and a SPA is a
perfectly good architecture. For anything public - a store, a blog, a marketing site, this site -
they hurt.
## The move: render on the server first
Next.js's core move is old, and that's a compliment: like PHP or Rails, it runs your code on a
server and sends **finished HTML**. The difference from PHP is *what* runs: your same React
components. Next renders your component tree to HTML on the server, sends that, and the content is
on screen after one round-trip:
```mermaid
sequenceDiagram
Browser->>NextServer: GET /products
NextServer->>DB: query products
DB-->>NextServer: rows
NextServer-->>Browser: full HTML, content included
Browser->>Browser: hydrate: JS attaches to existing HTML
```
π **Terminology:** that last step is **hydration** - the browser downloads the component
JavaScript, React renders the tree in memory, and instead of creating DOM it *attaches* to the HTML
that's already there, wiring up event handlers. The page was readable before hydration; it becomes
*interactive* after. (Phase 7 covers what happens when the server HTML and the client render
disagree - the famous hydration mismatch.)
π‘ **Key point:** Next.js is a server wrapped around React. HTML is produced on the server - either
per-request or ahead of time at build (phase 6) - and the browser's JavaScript takes over from
there. Every Next feature in this guide is a consequence of having that server: file routing
(phase 2), components that run only server-side (phase 3), data fetching without a public API
(phase 4), form handling on the server (phase 5), caching (phase 6).
## Hello, actual project
```console
$ npx create-next-app@latest my-shop
β Would you like to use TypeScript? β¦ Yes
β Would you like to use ESLint? β¦ Yes
β Would you like to use App Router? (recommended) β¦ Yes
Creating a new Next.js app in ./my-shop
$ cd my-shop && npm run dev
β² Next.js
- Local: http://localhost:3000
β Ready
```
*What just happened:* the scaffold created an `app/` directory (your routes and components), a
`public/` directory (static files), and config. `npm run dev` started the Next server - note that
word: unlike Vite's static-file dev server, this is the actual server architecture you'll deploy,
running your components on Node.
The one file worth reading immediately is `app/page.tsx` - it's the component behind `/`, and it
looks like the React you already know. Two phases from now you'll understand exactly which parts of
it ran on the server before your browser saw anything.
β οΈ **Gotcha:** "App Router" in that prompt refers to the current routing system built on the `app/`
directory - the one this guide teaches. Older tutorials (and many codebases) use the previous
system, the "Pages Router" (`pages/` directory, `getServerSideProps`). The concepts rhyme but the
APIs are entirely different; if a tutorial mentions `getStaticProps`, it's teaching the old system.
## So do you need it?
An even-handed table, because "always use a framework" is tool-brain:
| Situation | Plain React (Vite SPA) | Next.js |
|---|---|---|
| Internal dashboard behind a login | β simpler, no server to run | overkill unless you want its DX |
| Public content site, store, blog | slow first paint, weak SEO | β this is the core case |
| You need server-side secrets in the data path | build a separate API | β built in |
| Team knows React, no ops appetite | β static hosting is trivial | needs a Node server or a platform |
| Embedded widget inside another site | β | wrong shape entirely |
## Recap
1. A SPA ships an empty div and builds everything in the browser: fine behind a login, costly for
public content (first paint, SEO, exposed data layer).
2. Next.js renders your React components to HTML on a server first; the browser hydrates that HTML
into an interactive app.
3. Everything Next adds - routing, server components, actions, caching - flows from having that
server in front.
4. App Router (`app/` directory) is the current system and what this guide teaches; `pages/` +
`getServerSideProps` is the older one you'll meet in legacy code.
```quiz
[
{
"q": "Why does a plain React SPA tend to show a blank page or spinner before content appears?",
"choices": [
"React is slower than other frameworks at rendering",
"The server sends an empty shell, so content waits for the JS bundle to load and the data fetch to finish",
"Browsers block rendering until all JavaScript is downloaded",
"The virtual DOM must be built twice on first load"
],
"answer": 1,
"why": [
"Rendering speed isn't the bottleneck - the network round-trips before rendering can even start are.",
null,
"Browsers happily render HTML while scripts load - but an empty div has nothing to render.",
"There's no double build in a SPA; that's a garbled version of hydration, which only exists with server rendering."
],
"explain": "The SPA sequence is: empty HTML, download JS, run React, fetch data, then render. Server rendering collapses that into one round-trip that already contains content."
},
{
"q": "What does hydration mean in a Next.js app?",
"choices": [
"The server refreshes stale cached pages in the background",
"Client JavaScript attaches React to the server-sent HTML, making it interactive",
"CSS is inlined into the HTML to avoid a second request",
"Data is streamed into the page as it loads"
],
"answer": 1,
"why": [
"Background refresh of cached pages is revalidation - a phase 6 topic, unrelated to hydration.",
null,
"CSS inlining is a build optimization; hydration is about behavior, not styling.",
"Streaming is real (phase 4) but it's about delivering HTML in pieces, not attaching interactivity."
],
"explain": "The HTML arrives readable but inert. Hydration is React rendering in memory and adopting that existing DOM, wiring up handlers - readable first, interactive after."
}
]
```
---
# Routing with Files
In a Vite SPA you'd install React Router and declare routes in code. Next.js replaced that
configuration with a convention: **the `app/` folder structure *is* the router**. Folders are URL
segments; special filenames say what each segment renders. Learn about six filenames and you can
read any Next project's URL space by looking at its file tree.
## Folders are URLs, page.tsx is the content
```text
app/
page.tsx β /
about/
page.tsx β /about
products/
page.tsx β /products
[id]/
page.tsx β /products/42, /products/tea-kettle, ...
```
A folder only becomes a *visitable* URL when it contains a `page.tsx` (or `.jsx`). A folder without
one is just organization. The component in `page.tsx` is what renders at that URL:
```tsx
// app/about/page.tsx
export default function AboutPage() {
return
About us
;
}
```
*What just happened:* the default export of `page.tsx` is an ordinary React component. Visit
`/about` and the Next server renders it (server-side first, per phase 1) into the layout stack
around it. No route table, no registration - the file's existence is the registration.
## Dynamic segments: [id]
Square brackets make a folder match *any* value in that position, and your page receives it:
```tsx
// app/products/[id]/page.tsx
export default async function ProductPage({ params }) {
const { id } = await params;
return
);
}
```
*What just happened:* the component is an `async` function, so it can `await` anything - a database
call, an ORM, `fetch` against an external API. React waits for the promise, then renders the result
into the HTML response. No effect, no loading state, no race conditions - there's exactly one run,
and it has the data before it returns.
π‘ **Key point:** the three-state fetch dance (`data`/`loading`/`error` in `useState`) is a *client*
pattern. On the server it dissolves: awaiting **is** loading, throwing **is** error, and both get
first-class UI files below. Reach for the client pattern only when the data must refresh *in the
browser* without navigation (live search, polling) - and then preferably via a library like TanStack
Query, per React from Zero phase 9.
Two components that need the same data? Fetch in both. Next deduplicates identical `fetch` calls
within a single render pass (and for non-fetch sources, React's `cache()` wraps a function with the
same per-render memoization), so you don't thread props through five layers just to share a query.
## loading.tsx: what renders while you await
A fair question about that `await`: the server can't send the finished page until the data
arrives, so what does the user stare at? Without help: the previous page, feeling frozen. The fix is
the `loading.tsx` special file from phase 2's table:
```tsx
// app/orders/loading.tsx
export default function OrdersLoading() {
return ;
}
```
*What just happened:* Next now responds **immediately** with the layout stack plus this skeleton,
keeps the connection open, and **streams** the real page content into place when the await
resolves. The user sees structure instantly and content moments later - no frozen click, no blank
page.
π **Terminology:** under the hood, `loading.tsx` wraps your page in a React **Suspense boundary** -
the mechanism that lets a tree say "this part isn't ready; show the fallback, swap in the content
when it resolves." The file is the convenient spelling; the mechanism is Suspense.
## Streaming the slow part, not the whole page
`loading.tsx` gates the *entire* page behind its slowest await. When one widget is slow and the rest
is fast, put the boundary around just the slow thing:
```tsx
import { Suspense } from 'react';
export default function Dashboard() {
return (
<>
{/* fast: renders in the first flush */}
}>
{/* slow query: streams in when ready */}
);
}
```
```mermaid
sequenceDiagram
Browser->>Server: GET /dashboard
Server-->>Browser: layout + QuickStats + ChartSkeleton
Server->>DB: slow revenue query
DB-->>Server: rows
Server-->>Browser: RevenueChart streamed into place
```
*What just happened:* one HTTP response, delivered in chunks. The fast content painted immediately;
the slow island arrived when its data did. This is the server-side answer to "spinner city" - each
slow region gets its own boundary instead of the whole page waiting on the slowest query.
β οΈ **Gotcha:** the await has to live *inside* the Suspense boundary to stream. If `Dashboard` itself
awaits the slow query and passes rows down to `RevenueChart`, the whole page waits - the boundary
can only cut off what suspends *within* it. Move the fetch into the component behind the fallback.
## error.tsx: when the await throws
Data code fails: the API times out, the row doesn't exist. The `error.tsx` file is the route
subtree's error boundary:
```tsx
// app/orders/error.tsx
'use client'; // error boundaries must be client components (they use state to recover)
export default function OrdersError({ error, reset }) {
return (
Couldn't load your orders.
);
}
```
*What just happened:* an uncaught throw anywhere under `/orders` renders this instead of the page -
the layout stack above it stays intact, so the site chrome survives the crash. `reset` re-renders
the failed subtree for a retry. The mandatory `'use client'` isn't an exception to phase 3 - error
recovery is interactivity, and interactivity is client work.
For the specific case of "this thing doesn't exist," throw the router's own signal instead:
```tsx
import { notFound } from 'next/navigation';
const product = await db.product(id);
if (!product) notFound(); // renders the nearest not-found.tsx with a 404 status
```
A real 404 status matters: it tells crawlers "don't index this," where a styled "not found" page
returning 200 tells them the opposite - the SEO lesson hiding inside an error-handling API.
## Recap
1. Server components fetch by awaiting - one run, data before render, no loading/error state
machinery.
2. Duplicate fetches within a render are deduplicated (`fetch` automatically, other sources via
`cache()`) - fetch where you need, don't prop-thread.
3. `loading.tsx` streams the page: instant skeleton, content swapped in when ready. It's Suspense
with a filename.
4. Wrap just the slow islands in `` - and put the await inside the boundary, or nothing
streams.
5. `error.tsx` catches throws per subtree (always `'use client'`); `notFound()` gives missing
resources a real 404.
```quiz
[
{
"q": "Why doesn't fetching in a server component need the data/loading/error useState pattern?",
"choices": [
"Next.js manages those three states automatically behind the scenes",
"The component runs once with await - it has the data before it renders, so there are no in-browser states to track",
"Server components are faster, so loading states never appear",
"The pattern still applies; it's only written in a different file"
],
"answer": 1,
"why": [
"Nothing is managed invisibly - the states genuinely don't exist, because there's no mounted component waiting for data.",
null,
"Speed isn't the reason - a slow query still takes time; that time is just handled by streaming (loading.tsx), not component state.",
"loading.tsx and error.tsx replace the pattern's UI, but the state machinery itself is gone, not relocated."
],
"explain": "The client pattern exists because browsers mount first and fetch after. A server component awaits first and renders once - loading UI comes from Suspense boundaries, errors from error.tsx."
},
{
"q": "A dashboard page awaits a slow query at the top and passes the result into a component wrapped in . The whole page still waits for the query. Why?",
"choices": [
"Suspense only works with the loading.tsx file, not inline",
"The await happens outside the boundary - the page suspends before Suspense can isolate anything",
"The fallback component was too heavy to stream",
"Streaming requires the Edge runtime"
],
"answer": 1,
"why": [
"Inline works exactly like loading.tsx - the file is sugar for the same boundary.",
null,
"Fallback weight affects paint time, not whether streaming happens at all.",
"Node streams these responses fine; no special runtime is involved."
],
"explain": "A boundary can only cut off work that suspends inside it. Move the fetch into the component behind the fallback, and the rest of the page flushes immediately."
}
]
```
---
# Mutations: Forms and Server Actions
Reading data was phase 4. Writing it - the form submit, the delete button, the "add to cart" - used
to require building an API route, fetching it from the client, and hand-managing the states in
between. Server actions collapse that: **you write a function, and the framework builds the
endpoint.** It's the feature that looks most like magic and is most worth de-mystifying, because
under the hood it's the plainest thing in Next: a POST request with a name on it.
## What a server action actually is
```tsx
// app/todos/actions.ts
'use server';
import { db } from '@/lib/db';
import { revalidatePath } from 'next/cache';
export async function addTodo(formData: FormData) {
const text = String(formData.get('text') ?? '').trim();
if (!text) return; // validate on the server - the only place it counts
await db.todos.insert({ text });
revalidatePath('/todos'); // more on this below
}
```
```tsx
// app/todos/page.tsx - a server component with a form
import { addTodo } from './actions';
export default async function TodosPage() {
const todos = await db.todos.list();
return (
<>
{todos.map(t =>
{t.text}
)}
);
}
```
*What just happened:* `'use server'` marks the file's exports as **server actions** - functions that
always execute on the server, no matter where they're called from. When you pass one to a form's
`action`, the framework registers a private endpoint for it; submitting the form POSTs the form data
there, runs your function server-side, and re-renders the page with the result. You wrote zero API
code, zero fetch code, and the database call never left the server.
π **Terminology:** this is the one legal way a *function* crosses the server/client boundary from
phase 3 - because what actually crosses is not the function but a **reference** to it, which the
framework resolves back to server code when invoked.
β οΈ **Gotcha:** `'use server'` does not mean "server component" - components are server-rendered *by
default* and need no directive. It means "callable-from-anywhere function that runs on the server."
Two directives, two meanings: `'use client'` marks a bundle boundary; `'use server'` marks remote
callability. And because every server action **is a public HTTP endpoint** (anyone can POST to it),
validation and auth checks belong *inside the action*, every time - the form is a convenience, not a
gate.
## Why this beats the fetch-an-API version
The old shape - `onSubmit` handler, `fetch('/api/todos', ...)`, JSON parsing, then manually
re-fetching the list - had four moving parts to keep aligned. The action version has one function.
And the `
);
}
```
*What just happened:* the hook gives you the action's last return value (`state`), a wrapped action
for the form, and a `pending` boolean during the round-trip. The action itself changes shape
slightly: it receives `(prevState, formData)` and returns the new state - which is how server-side
validation messages travel back to the form without you building a response channel.
## Route handlers: when you actually want an API
Server actions serve *your own UI*. Sometimes you need a real HTTP endpoint - a webhook receiver, a
JSON API for a mobile app, an RSS feed. That's `route.ts` from phase 2's table:
```tsx
// app/api/todos/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
const todos = await db.todos.list();
return NextResponse.json(todos);
}
```
One folder exposes `GET`/`POST`/`PUT`/`DELETE` by exporting functions with those names. The
decision line: **consumed by your own components β server action; consumed by anything else β
route handler.** (A folder can't have both `route.ts` and `page.tsx` - a URL is either a page or an
endpoint.)
## Recap
1. A server action is a `'use server'` function the framework exposes as a private POST endpoint -
forms call it via `action={fn}`, no API layer written.
2. It's still a public endpoint: validate and authorize inside the action, always.
3. Writes end with `revalidatePath`/`revalidateTag`, or cached pages keep showing pre-mutation data.
4. `useActionState` supplies pending state and carries server validation messages back to the form.
5. Route handlers (`route.ts`) are for external consumers; actions are for your own UI.
```quiz
[
{
"q": "A server action skips validation because \"the form already validates in the browser.\" What's wrong with that reasoning?",
"choices": [
"Browser validation doesn't run for controlled inputs",
"The action is an HTTP endpoint anyone can POST to directly, bypassing your form entirely",
"Server actions can't read FormData without validating it first",
"Nothing - client validation is sufficient when using form action={}"
],
"answer": 1,
"why": [
"Browser validation runs fine on any input - but it runs in a place the attacker controls.",
null,
"FormData reads happily without validation - that's precisely the danger.",
"Client validation is UX, not security, in every architecture - actions included."
],
"explain": "The form is one caller of the endpoint, not the only possible one. curl can invoke your action with anything - the server-side check is the real one."
},
{
"q": "After an action inserts a row, the page still lists the old data until a hard refresh. What's missing?",
"choices": [
"An await on the database insert",
"A revalidatePath (or revalidateTag) call marking the cached page stale",
"A useEffect to re-fetch after submit",
"The form needs method=\"POST\""
],
"answer": 1,
"why": [
"A missing await would be a race, fixed by luck on fast databases - but the hard-refresh recovery points at caching, not timing.",
null,
"Re-fetching client-side patches the symptom for one visitor; the cached server render stays wrong for everyone else.",
"Actions POST already - the method is handled by the framework."
],
"explain": "Next serves the cached render until told otherwise. Mutations must declare what they invalidated: revalidatePath('/todos') makes the next request re-render fresh."
}
]
```
---
# Static, Dynamic, and the Cache
Here's the Next.js behavior that generates the most confused bug reports: you deploy, you update the
database, and the page *still shows old data* - not for one user, for everyone, indefinitely. Or the
mirror image: a page you expected to be instant hits the server on every request. Both trace to one
decision the framework makes per route, mostly silently: **render at build time, or render per
request?** This phase makes that decision visible.
## The two rendering times
**Static rendering** happens **once, at build time** (`next build`). The result - finished HTML -
is saved and served to every visitor, as fast as a file can be served, with your server doing no
per-request work. The page is identical for everyone and as fresh as the last build.
**Dynamic rendering** happens **per request**. Every visit runs your components (phase 4's awaits
included), so the page can be personalized and is always current - at the cost of doing the work
every time.
π‘ **Key point:** Next's default is **static wherever possible** - it's the better deal whenever
it's legal. A route becomes dynamic when your code does something that *can't* be known at build
time. The build output tells you what happened to each route:
```console
$ npm run build
Route (app)
β β / # β = static: prerendered at build
β β /about
β Ζ /dashboard # Ζ = dynamic: rendered per request
β β /products/[id]
```
Reading this legend after every build is the habit that catches caching surprises before users do.
## What flips a route to dynamic
A route goes dynamic when it reads something that only exists at request time:
- **`cookies()` or `headers()`** - who's asking can't be known at build.
- **`searchParams`** on a page - `/products?sort=price` differs per URL.
- **An uncached data read** - a `fetch` opted out of caching, or the route/segment marked
`export const dynamic = 'force-dynamic'`.
That's the mechanism behind the surprise: add an innocuous `cookies()` call for a theme preference
and your fully-static page quietly becomes render-on-every-request. The build legend flips from β
to Ζ and the framework considers that your answer.
## Dynamic segments want a guest list
What about `/products/[id]` - static or dynamic? At build time Next can't know the ids. You can
tell it:
```tsx
// app/products/[id]/page.tsx
export async function generateStaticParams() {
const products = await db.products.list();
return products.map(p => ({ id: String(p.id) }));
}
```
*What just happened:* at build, Next calls this, gets the list of ids, and prerenders every one of
those product pages as static HTML. Without it, the route renders on demand. The middle way is both:
prerender the top 100 products, render rarer ids on first request, cache the result.
## Revalidation: static pages that refresh themselves
Static's weakness is staleness: content changed, build didn't. The blunt fix - redeploy on every
content change - doesn't survive contact with a CMS. The real fix is **revalidation**: static, with
an expiry.
```tsx
// re-render this page in the background at most every hour
export const revalidate = 3600;
```
*What just happened:* the page is served statically as usual. Once the copy is older than 3600
seconds, the *next* visitor still gets the cached copy instantly - but triggers a background
re-render, and everyone after gets the fresh one. Old name for this: ISR, incremental static
regeneration. Practical meaning: "static speed, at most an hour stale."
The event-driven version you already met in phase 5 beats the timer version when you control the
writes: `revalidatePath`/`revalidateTag` from a server action (or a CMS webhook hitting a route
handler) refresh the page *at the moment the data changes*, no polling interval to tune.
For per-fetch control, the options ride on `fetch` itself:
```tsx
await fetch(url, { cache: 'force-cache' }); // cache indefinitely (until revalidated)
await fetch(url, { next: { revalidate: 300 } }); // this data: at most 5 minutes stale
await fetch(url, { next: { tags: ['products'] } }); // invalidatable via revalidateTag
```
## The decision, as a picture
```mermaid
flowchart TD
Q{Reads cookies, headers,\nsearchParams, or uncached data?}
Q -->|yes| DYN[Ζ dynamic: rendered per request]
Q -->|no| STAT[β static: prerendered at build]
STAT --> R{revalidate set?}
R -->|yes| ISR[refreshes in background after expiry]
R -->|no| FROZEN[fresh as of the last build]
```
β οΈ **Gotcha:** the classic false diagnosis. Page shows stale data β developer adds
`force-dynamic` β page is correct now but renders on every request forever. The stale page was
*telling you* it was static without a revalidation story; the proportionate fix was `revalidate` or
a `revalidatePath` at the write site - keeping static speed *and* freshness. Reach for
`force-dynamic` when the page is genuinely per-visitor (a dashboard), not as a cache-buster.
β οΈ **Gotcha:** in development (`npm run dev`) every route renders per-request so you always see
fresh code and data. The static/stale behavior only exists in the built app - which is why "works
in dev, stale in prod" is this phase's signature bug report. Test caching behavior with
`npm run build && npm start`, never with the dev server.
## Recap
1. Static = rendered once at build, served as a file; dynamic = rendered per request. Default is
static wherever legal.
2. `cookies()`, `headers()`, `searchParams`, and uncached reads flip a route dynamic - check the
β/Ζ legend after builds.
3. `generateStaticParams` prerenders dynamic segments' known values.
4. `revalidate = N` gives static pages an expiry; `revalidatePath`/`revalidateTag` refresh them the
moment data changes.
5. Stale page β reach for `force-dynamic` - that trades the caching away instead of fixing its
freshness.
```quiz
[
{
"q": "A product page shows updated prices in dev but week-old prices in production. What's the most likely explanation?",
"choices": [
"The production database is behind the development one",
"The route is static: it was prerendered at the last build and has no revalidation configured",
"The CDN is ignoring cache headers",
"generateStaticParams returned the wrong ids"
],
"answer": 1,
"why": [
"Possible, but the works-in-dev/stale-in-prod signature points at rendering time: dev renders per request, the build doesn't.",
null,
"A CDN issue wouldn't respect the dev/prod split this cleanly - and Next's own cache sits before any CDN.",
"Wrong ids would 404 or miss pages, not serve old prices on existing ones."
],
"explain": "Dev renders every request; the built app serves what the build produced. A static page without revalidate stays as fresh as the last deploy - add revalidate or revalidate on write."
},
{
"q": "Adding a cookies() call for a theme preference made a landing page render on every request. Why?",
"choices": [
"Reading cookies is slow, so Next disables caching to compensate",
"Cookie values only exist per request, so the page can no longer be rendered once at build",
"cookies() is only allowed in client components",
"The theme value changes too often to cache"
],
"answer": 1,
"why": [
"It's not a performance heuristic - it's a logical impossibility: there is no cookie at build time.",
null,
"cookies() is server-only - it's legal here; the cost is the rendering mode, not an error.",
"Even a never-changing cookie has this effect; what matters is when the value becomes knowable."
],
"explain": "Static rendering happens at build, where no request - and no cookie - exists. Reading request-time data forces per-request rendering. Consider reading the theme client-side to keep the page static."
},
{
"q": "A marketing page's content updates in the CMS a few times a week. The team wants static-file speed. Best setup?",
"choices": [
"export const dynamic = 'force-dynamic' so it's always fresh",
"Static with revalidation - a revalidate interval, or a CMS webhook calling revalidatePath",
"A client component that fetches the content in useEffect",
"Rebuild and redeploy the site on a nightly schedule"
],
"answer": 1,
"why": [
"Always-fresh at the price of rendering every request - the exact overcorrection this phase warns about for content that changes twice a week.",
null,
"That reintroduces the SPA waterfall and hides content from crawlers - everything phase 1 left behind.",
"It works, but couples freshness to deploy cadence and re-renders everything for one page's change - revalidation does it surgically."
],
"explain": "Static with an expiry (or event-driven revalidation from the CMS webhook) is the built-for-this answer: file-serving speed, freshness within minutes of a change."
}
]
```
---
# When Next.js Breaks
Every classic Next.js error is the server/client split from phase 3 poking through the floor. That's
genuinely good news: one mental model explains all five of the messages below, so this phase is
shorter than it looks - it's the same lesson wearing five costumes.
## The cheat-card
| Symptom / message | Almost always means | Fix |
|---|---|---|
| **"Hydration failed" / "text content does not match"** | Server HTML β first client render | Find the nondeterminism: dates, random, locale, browser-only branches; render them after mount |
| **"useState/useEffect only works in a Client Component"** | Hook in a server component | `'use client'` on the *smallest* interactive subtree - not the page |
| **"window is not defined"** | Browser API running during server render | Move into `useEffect`; or `next/dynamic` with `ssr: false` |
| **"Functions cannot be passed directly to Client Components"** | Non-serializable prop crossing the boundary | Pass data, not functions - or make it a server action (phase 5) |
| **Page shows old data after a write** | Missing revalidation | `revalidatePath`/`revalidateTag` in the action (phase 5/6) |
| **Stale in prod, fine in dev** | Static route without a freshness story | `revalidate`, or revalidate-on-write (phase 6) |
| **`useRouter` throws immediately** | Imported from `next/router` in an `app/` project | Import from `next/navigation` (phase 2) |
Three of these deserve the full walk-through.
## Hydration mismatch: the flagship error
The message is alarming and the cause is almost always mundane:
```text
Error: Text content does not match server-rendered HTML.
Server: "Order placed 11/17/2026, 10:03 PM"
Client: "Order placed 17/11/2026, 22:03"
```
Remember hydration (phase 1): the browser re-renders your components and *attaches* to the
server's HTML, trusting they'll produce identical output. Anything that renders differently in the
two environments breaks that trust. The usual suspects:
- **Locale-formatted dates and numbers** - `toLocaleString()` used the server's locale, then the
user's. (The transcript above: US server, European visitor.)
- **`Date.now()` / `Math.random()`** in render - by definition different on every run.
- **Browser-only branching** - `typeof window !== 'undefined' ? : ` renders `` on the
server and `` on the client. The check *prevents* the crash and *causes* the mismatch.
- **Invalid HTML nesting** - `
` inside `
`, `
` inside `
`: the browser's parser
silently rearranges the server HTML, and then React's render doesn't match the rearranged DOM.
The standard fix pattern for values only the client can know correctly:
```tsx
'use client';
function LocalTime({ iso }) {
const [text, setText] = useState(null); // server and first client render agree: nothing
useEffect(() => {
setText(new Date(iso).toLocaleString()); // after mount, browser-only, no mismatch
}, [iso]);
return {text ?? 'β¦'};
}
```
*What just happened:* both environments render the placeholder identically, hydration succeeds,
*then* the effect fills in the locale-correct value. You'll see this pattern (or the
`suppressHydrationWarning` attribute for single unavoidable nodes, like a timestamp in a `