Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 72 ยท Server and Client Components

Inside the RSC Payload

Look inside the React Server Components payload: how Next.js serializes the tree, marks client component references, streams rows and merges updates on navigation.

You have seen that Server Components run on the server and Client Components run in the browser. That raises a practical question: what actually travels over the network? A Server Component is a function, and functions cannot be sent as text. The answer is the RSC payload, a compact, streamable description of the rendered tree. It is the data format that connects the two worlds.

This lesson opens that box. You will learn what is inside the payload, how Client Components appear in it as small references, why some props are not allowed, and how the browser merges a new payload into the page when you navigate. The format itself is an internal detail of React and Next.js and it changes between versions, so treat everything here as a mental model. The ideas are stable even when the bytes are not.

On this site the real Next.js server cannot run. The code that belongs to Next.js is shown in read-only blocks, and the runnable examples are small stand-ins written in plain Node.js that follow the same idea. Each section says which is which.

What the payload is

When you render <Post /> on the server, React calls the function and gets back elements. It keeps calling any Server Components it finds until only two kinds of things remain: plain HTML elements such as div and h1, and Client Component references. The result is a tree of simple data, and that tree is serialized.

What the payload holds

The rendered tree HTML elements, text and props as plain data.
Client references A pointer to a component's JavaScript file.
Props for clients Only data that can be serialized.

The code of Server Components is never part of it.

1 / 2

In a real Next.js app the payload reaches the browser in two ways. On the first visit it is embedded in the HTML document, in small inline <script> tags, next to the HTML that was produced from the same tree. On later navigations the browser asks for it directly: Next.js sends a request with an RSC: 1 header and the server answers with a response of type text/x-component, which is the payload alone with no HTML.

A tiny model of the format

The real payload is a sequence of lines called rows. Each row has an id, a colon and some data. A React element is written as an array that starts with the marker "$", followed by the type, a key and the props: ["$","h1",null,{"children":"Hello"}]. A Client Component cannot be rendered on the server, so it gets two things instead: an import row that says which module and export to load, and an element whose type is a lazy reference to that row, written $L1, $L2 and so on.

The stand-in below follows that shape. It has a small h() function to build elements, a clientRef() that marks a component as client-side, and a serialize() function that walks the tree. Server Components, which are ordinary functions here, are called on the spot, and only their output is serialized. The format of the rows is simplified, but the logic is the real one: run the server parts, keep references for the client parts, and refuse anything that cannot be serialized.

Node.js Serialize a tree into a mini payload

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.

Look at the output. Row 1 is the import row: it says "load components/like-button.js and use its LikeButton export". Row 0 is the tree. The Post function has disappeared completely: only the article, the h1 and the p it returned are there. The LikeButton appears as $L1 and carries its props as plain JSON. Notice what the second half of the output shows: a function cannot cross the boundary, so serialization stops with an error. Next.js reports the same kind of error when you pass an event handler from a Server Component to a Client Component.

What can cross the boundary

Props that go to a Client Component must be serializable, because they are written into the payload. React's format is richer than JSON, so more than plain objects can pass:

  • strings, numbers, booleans, null, undefined and bigint;
  • arrays and plain objects, as well as Date, Map, Set and typed arrays;
  • Promises, which a Client Component can read with use() (see Fetching Data on the Client);
  • JSX, including other Server Components, passed as children or any other prop. This is the pattern from Composing Server and Client Components;
  • Server Actions, which are functions marked with "use server" and travel as references to an endpoint, not as code.

Ordinary functions, class instances and objects with methods cannot cross. This is the rule behind the familiar error that says functions cannot be passed to Client Components.

TSX
// app/post/page.tsx  (real Next.js, read-only)
import LikeButton from './like-button'; // a file that starts with "use client"

export default async function Page() {
  const post = await getPost();

  return (
    <article>
      <h1>{post.title}</h1>
      {/* OK: plain data */}
      <LikeButton initial={post.likes} />
      {/* Error: an ordinary function cannot be serialized */}
      {/* <LikeButton onLike={() => console.log('liked')} /> */}
    </article>
  );
}

The same rule explains why the boundary is the place where bundle size is decided. Everything behind a "use client" import is shipped to the browser as JavaScript. Everything else only contributes its output to the payload.

Streaming: the payload arrives in pieces

The payload is not one block that has to be complete before anything is sent. Rows are written as they become ready. When a Server Component is wrapped in a <Suspense> boundary and is still waiting for data, React writes the surrounding tree first, with a placeholder where the slow part will go. Later, when the data is ready, it writes a new row with the finished part and the browser slots it into the right place.

That is the mechanism behind streaming, which you will use in Streaming with Suspense. The row ids are what make it work: the early row says "something with id 5 goes here", and the late row 5: supplies it. A row can arrive at any time after the row that mentions it.

Now the important part for users. When you click a <Link>, Next.js does not reload the page. It fetches the payload for the target URL, and React reconciles the new tree with the one already on screen. That is the same diffing React always does, applied to a tree that came from the network.

sequenceDiagram
  participant U as User
  participant B as Browser (React)
  participant S as Next.js server
  U->>B: Click link to /about
  B->>S: GET /about with the RSC header
  S-->>B: Payload rows (text/x-component)
  B->>B: Reconcile new tree with current tree
  B-->>U: Update only what changed

A client navigation fetches only the payload. React keeps what matches and replaces what does not.

Two consequences follow. First, layouts that exist both before and after the click are kept: they stay mounted, and the state inside their Client Components (an open menu, text in a search box, a counter) survives. Only the part that differs, usually the page, is replaced. Second, nothing is thrown away just because the server rendered again: if a Server Component produces the same output, React has nothing to update.

The stand-in below reconciles two payload trees the way the browser does. A sidebar counter is client state keyed by its position in the tree. Going from /home to /about keeps the layout and the counter and replaces the page content. Going to /blog, where the layout is different at the root, replaces everything and the state is lost.

Node.js Merging a new payload into the current tree

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.

Read the log from the top. For /about, body, the sidebar (still holding {"count":3}), main and section are all kept. The heading changes from h1 to h2, so that one node is replaced, while the paragraph with the same text is reported as unchanged. For /blog, the root element type is different, so the whole tree is replaced and the counter state is dropped. This is the same rule you know from React: same type at the same position means keep, different type means start over.

This is why shared layouts are cheap in the App Router. Moving between sibling pages never re-renders the layout's Client Components from scratch, and the browser never downloads their JavaScript twice.

Mutations use the same format

When a Server Action finishes, Next.js can answer with a fresh payload as part of the response, so the screen updates in the same round trip as the mutation. It is the same row format and the same merge. You will see this in Server Actions and in Optimistic UI and Refreshing After Mutations, where router.refresh() simply asks for a new payload of the current page and merges it in.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the RSC payload contain for a Server Component such as <Post />?

    The function runs on the server. What is sent is its output as a tree of elements and references, never the function itself.
  2. 2. How does a Client Component appear in the payload?

    The payload holds an import row naming the module and export, and an element that points to it. The browser loads the code from that reference and renders it with the props.
  3. 3. Which prop can a Server Component NOT pass to a Client Component?

    Plain functions cannot be serialized. Only functions marked with "use server" (Server Actions) can travel, as references.
  4. 4. A user clicks a link to a sibling page that shares the same layout. What happens to the layout's Client Component state?

    Next.js fetches only the payload and merges it. Nodes that match stay mounted, so layout state survives and only the changed page part is replaced.

Summary

  • The RSC payload is a streamable, row-based description of the rendered tree: HTML elements, text, props and Client Component references.
  • Server Component functions run on the server and are never sent. Only their output is.
  • A Client Component becomes an import row plus a $L reference, so the browser knows which JavaScript to load.
  • Props crossing to a Client Component must be serializable: no ordinary functions or class instances.
  • Rows are written as they are ready, which is how Suspense streaming works.
  • On navigation, the browser fetches the payload and React merges it with the current tree, keeping layouts and their state.
  • The exact wire format is internal and changes, so use it as a mental model and never parse it yourself.

Next, learn how Server Components fetch their data in Fetching Data in Server Components.