Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 72 ยท Getting Started

How a Request Flows Through Next.js

Follow a request through Next.js from build time to the browser: route matching, Server Components, the RSC payload, HTML streaming and hydration.

Before you write more code, it helps to have a picture of what Next.js actually does. When someone types a URL, a surprising amount happens before the first pixel appears and again before the first button works. Knowing the order of those steps makes later topics, such as caching, streaming and the server and client boundary, much easier to understand.

This lesson follows one request from start to finish. It also separates build time, when your project is compiled, from request time, when a visitor asks for a page. The diagram and the two live examples are models of the pipeline. They follow the real design, but they are small stand-ins and not Next.js itself.

Two moments: build time and request time

Next.js code runs at two different moments, and many beginner mistakes come from mixing them up.

Build time happens when you run next build, usually on your computer or in a deployment pipeline. Your code is compiled and split into bundles. Pages that do not depend on a specific visitor can be rendered ahead of time, so the finished result is stored as a file. Visitors then get that stored result instantly.

Request time happens when a visitor asks for a URL on the running server. Pages that need fresh or per-user data are rendered now, for that request, and sent back.

Two moments in the life of a page

Build time next build compiles and pre-renders what it can.
Request time A visitor asks and the server answers.

Static pages finish at build time. Dynamic pages finish at request time.

1 / 2

By default, Next.js tries to make a route static and switches it to dynamic when your code reads something only known at request time, such as cookies, headers or the URL's query string. You will study that decision in Static vs Dynamic Rendering. For now, remember that the pipeline below is the same either way. The only question is whether it ran earlier or runs now.

The journey of one request

Here is the whole flow for a page that has both Server and Client Components, on the very first visit:

sequenceDiagram
    participant B as Browser
    participant S as Next.js server
    B->>S: GET /products
    S->>S: Run the proxy and match the route
    S->>S: Render Server Components into the RSC payload
    S->>S: Render HTML from the payload
    S-->>B: HTML, streamed, plus the payload
    B->>B: Show the HTML right away
    B->>S: Download JavaScript for Client Components
    B->>B: Hydrate, now the page is interactive
    B->>S: Later link click, ask for the payload only
    S-->>B: RSC payload
    B->>B: React updates the page in place

One request in time order: HTML first for speed, JavaScript second for interactivity, payload-only navigation afterwards.

Let's walk through it.

1. Route matching and the proxy

The server receives GET /products. If you have a proxy.ts file, it runs first and can rewrite, redirect or add headers. Then Next.js matches the URL to a folder in app, for example app/products/page.tsx, and collects every layout file from the root down to that page. Layouts and the page are one nested tree of components.

2. Server Components render into the RSC payload

Next, React runs your Server Components. This is where async components wait for data and where database calls happen. The output is not HTML. It is a compact description of the UI tree called the RSC payload (React Server Components payload). It contains the rendered output of the Server Components and, for each Client Component, a reference: "put the component from this file here, with these props". Server Component code never appears in the payload, only its results. We look inside the payload in Inside the RSC Payload.

3. HTML is generated from the payload

The server then turns that tree into HTML, so the browser can paint the page before any JavaScript runs. Client Components are also rendered here once, with their initial state, so they appear in the HTML too. HTML and payload are sent together, and large pages can be streamed: the parts that are ready go first and slower parts follow, which you will see in Streaming with Suspense.

4. The browser paints, then hydrates

The browser shows the HTML immediately. At this point the page looks finished, but a Client Component's button has no event handler yet, because it is only markup. The browser then downloads the JavaScript for the Client Components, and React walks the existing HTML and attaches event handlers and state to it. That step is called hydration. Hydration reuses the HTML rather than rebuilding it, which is why it must match what the server produced. If the two differ, React reports a hydration mismatch; we study that in Debugging and Error Handling.

5. Later navigations only fetch the payload

After the first load, clicking a link does not reload the whole page. The Next.js client router asks the server for the RSC payload of the next route only, and React merges it into the page. Shared layouts stay mounted and keep their state, and only the segments that changed are replaced. This is why navigation in a Next.js app feels like a single-page app even though most of the work happens on the server.

Try it: a mini pipeline

Real framework or stand-in? The program below is a toy. Real Next.js renders React elements and uses a binary-like streaming format, not objects and strings like this one. What it does show faithfully is the order of the stages and the key facts: the Server Component's own code and its database stay on the server, Client Components become references, and only references need JavaScript.

The Node.js stand-in below runs the stages one at a time. A server component fetches data, the render step produces a payload where LikeButton is only a reference, the HTML step turns the payload into markup, and a final list shows which code the browser would have to download. At the end, a static page and a dynamic page are asked for three times each, to count how often each one is rendered.

Node.js Run the pipeline: render, payload, HTML, hydration list

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.

In step 1 you can see that LikeButton is only {"client":"LikeButton","props":{"count":3}}. That is the pattern behind everything in the next chapters: server work stays on the server, and the browser only receives what it needs to continue. The last line shows why static routes are cheap to serve.

Try it: hydration

The second live example makes hydration visible. It uses React's real renderToString and hydrateRoot, the same two functions at the core of the process. First the page is only server-made HTML: click the button and nothing happens, because no JavaScript is attached. Then press "Hydrate" to attach React, and click again.

Before and after hydration

Before hydration the button text never changes, even though the browser received your clicks. After hydration the same button, in the same place, counts. Nothing was rebuilt: React matched its component tree against the existing markup and added the handlers. That is also why Client Components make a page heavier, since each one needs its JavaScript downloaded and run before it comes alive.

Why this order matters

The flow explains many design choices you will meet later:

  • HTML first gives fast first paint and good SEO, while hydration comes later and only for the parts that need it.
  • Server Components do not hydrate, because they are finished on the server. That is the main reason they reduce the JavaScript sent to the browser.
  • Payload-only navigation is why layouts keep their state between pages.
  • Caching can be applied at several stages: the rendered output, the data behind it, or the payload in the browser. The caching overview lays out each layer.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Next.js do at build time?

    next build compiles and splits your code, and pre-renders routes that can be made ahead of time so they can be served as ready-made results.
  2. 2. What is the RSC payload?

    It carries the output of Server Components and references to where Client Components go, not the Server Component source code.
  3. 3. What is hydration?

    The server-made HTML is shown first. Hydration makes it interactive by connecting React's component tree to the existing elements.
  4. 4. When you click a link after the first page load, what does the client router normally request?

    Soft navigation fetches the payload for the changed segments. Shared layouts stay mounted and keep their state.
  5. 5. Why do Server Components reduce the JavaScript sent to the browser?

    Only their output is sent. Client Components are the ones that need their code downloaded and hydrated.

Summary

  • Build time compiles your project and pre-renders what it can; request time renders what depends on the visitor.
  • A request is matched to a route, Server Components render into the RSC payload, and HTML is generated from it and streamed to the browser.
  • The browser paints the HTML first, then downloads JavaScript and hydrates Client Components to make them interactive.
  • Later navigations fetch only the RSC payload of the changed segments, so layouts keep their state.
  • Server Components are never hydrated, which is why keeping components on the server shrinks the JavaScript sent.

Next: Pages and Layouts