Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 72 ยท Server and Client Components

Composing Server and Client Components

Mix Server and Client Components well: push the boundary down, pass Server Components as children, follow the props serialization rules and use interleaving patterns.

Once you know both kinds of component, the interesting question is how to combine them. A real page is a mix: server-fetched content around a few interactive pieces, sometimes with interactive pieces that wrap server-rendered content. The rules look strict at first: a Client Component cannot import a Server Component, and not every value can travel from one side to the other. But a handful of patterns cover almost everything.

This lesson teaches those patterns: push the client boundary down to the leaves, pass Server Components through children slots, send only serializable props across the boundary, and hand data to the browser as a promise when it is slow. The framework itself cannot run on this site, so Next.js code is read-only. The two runnable examples are React stand-ins that demonstrate the mechanics, and the text says which part is real React and which part is a model.

Four composition patterns

Push the boundary down Make small leaves interactive, not whole pages.
Children as a slot A client wrapper renders server content passed in.
Serializable props Only data, never plain functions or class instances.
Promises as props Start the fetch on the server, read it in the browser.

Most pages use all four.

1 / 2

Pattern 1: push the boundary down

Imagine a product page with a long description, a gallery and an "Add to cart" button. Only the button needs the browser. The wrong move is to mark the whole page as a client component to make that button work. The right move is to extract the button.

TSX
// app/products/[id]/page.tsx (read-only): stays a Server Component
import AddToCart from "./add-to-cart";

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <main>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <AddToCart productId={product.id} />
    </main>
  );
}
TSX
// app/products/[id]/add-to-cart.tsx (read-only)
"use client";

import { useState } from "react";

export default function AddToCart({ productId }: { productId: string }) {
  const [quantity, setQuantity] = useState(1);
  return (
    <button onClick={() => addToCart(productId, quantity)}>
      Add {quantity} to cart
    </button>
  );
}

The description, the heading and every library used to render them stay on the server. Only the tiny button ships. Client Components and "use client" explains why imports of a client file join the bundle, which is the reason to keep these files small.

Pattern 2: pass Server Components as children

Sometimes the interactive piece is a wrapper: a collapsible panel, a modal, a tab strip, a layout with a sidebar toggle. The wrapper needs state, but the content inside can be server-rendered. You cannot import a Server Component inside a Client Component (it would become a client module), but you can receive it as a prop, usually children.

TSX
// app/components/collapsible.tsx (read-only)
"use client";

import { useState } from "react";

export default function Collapsible({
  title,
  children,
}: {
  title: string;
  children: React.ReactNode;
}) {
  const [open, setOpen] = useState(true);
  return (
    <section>
      <button onClick={() => setOpen(!open)}>{title}</button>
      {open && <div>{children}</div>}
    </section>
  );
}
TSX
// app/page.tsx (read-only): a Server Component fills the slot
import Collapsible from "./components/collapsible";
import LatestOrders from "./components/latest-orders"; // async Server Component

export default function Page() {
  return (
    <Collapsible title="Latest orders">
      <LatestOrders />
    </Collapsible>
  );
}

LatestOrders runs on the server. The client wrapper never learns how it works; it receives already-rendered output in children, which it places inside its own markup. The idea is often called the "donut" pattern: a client ring around a server hole.

There is a real React mechanism underneath, and you can see it in plain React. When a component receives children that were created by its parent, those elements keep the same identity as long as the parent does not re-render, and React skips re-rendering them when the wrapper's own state changes. The stand-in below counts renders: the left panel receives its content as children, the right panel imports the same content directly, as a Client Component would be forced to do. Click each "re-render" button a few times and compare the counters.

Children as a slot do not re-render

After three clicks on each button, the slot version still says "rendered 1 time", while the importing version says 4. The stand-in uses ordinary components for both, so it shows the React behavior, not a real server render. In Next.js the effect is stronger: the children are already-rendered output from the server, so they cannot re-render in the browser at all.

Pattern 3: props must be serializable

When a Server Component renders a Client Component, the props travel in the RSC payload, which is a text format. So the values must be something React knows how to write down and rebuild in the browser. Supported values include strings, numbers, booleans, null, undefined, bigint, plain objects and arrays, Date, Map, Set, typed arrays, promises, and Server Actions. Not supported are ordinary functions, class instances, and symbols that are not from Symbol.for.

TSX
// read-only
// Fine
<Chart data={[1, 2, 3]} createdAt={new Date()} />

// Error: functions cannot be passed to a Client Component
<Chart format={(value) => value.toFixed(1)} />

// Error: only plain objects can be passed, not class instances
<Chart cart={new Cart()} />

The usual fix is to move the function into the Client Component, or pass a plain description (such as precision={1}) and let the client build the function. Server Actions are the exception to the function rule; they are covered in Server Actions.

The stand-in below implements a small checker with these rules and runs it on sample values. It is a model of what Next.js and React enforce, written for teaching, so the error wording is ours.

Which props can cross the boundary?

Notice how nested problems are reported with a path, such as the function hidden inside a Map. When Next.js reports this error in real life, finding the offending value inside a big props object is the hard part, so check nested values first.

Pattern 4: start the fetch on the server, read it on the client

Sometimes a Client Component needs data but you do not want to block the page while it loads. A Server Component can start the request without awaiting it and pass the promise down. The client component reads it with React's use hook, wrapped in Suspense so the rest of the page shows right away.

TSX
// app/page.tsx (read-only)
import { Suspense } from "react";
import Comments from "./comments";

export default function Page() {
  const commentsPromise = getComments(); // no await: the promise is the prop

  return (
    <Suspense fallback={<p>Loading comments...</p>}>
      <Comments commentsPromise={commentsPromise} />
    </Suspense>
  );
}
TSX
// app/comments.tsx (read-only)
"use client";

import { use } from "react";

export default function Comments({
  commentsPromise,
}: {
  commentsPromise: Promise<{ id: number; text: string }[]>;
}) {
  const comments = use(commentsPromise);
  return (
    <ul>
      {comments.map((c) => (
        <li key={c.id}>{c.text}</li>
      ))}
    </ul>
  );
}

This keeps the fetch on the server, close to your data, and still lets the client component own any interactivity around the result. Fetching Data on the Client returns to use in more depth.

Patterns to avoid

  • Importing a Server Component into a Client file. It silently becomes a client module, loses access to server-only code and may break the build. Pass it as children instead.
  • Putting the directive at the top of a layout just to make one thing interactive. Wrap the interactive piece instead.
  • Passing a whole database record when the client needs two fields. Everything you pass is written into the payload, so send what the component uses.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How can a Client Component render content produced by a Server Component?

    Importing a Server Component into a client file makes it part of the client graph. Passing it in as children keeps it on the server and lets the wrapper place it.
  2. 2. Which prop can a Server Component pass to a Client Component?

    Dates are supported. Ordinary functions, class instances and local symbols cannot be written into the RSC payload.
  3. 3. Why does passing server content as children avoid extra client work?

    The server renders the children and sends the result. The client wrapper only decides where to put them.
  4. 4. A page needs one interactive button. What is the best structure?

    Pushing the boundary down keeps the heavy parts on the server and ships only the button's code.

Summary

  • Push the client boundary down: extract small interactive leaves instead of marking pages or layouts.
  • A Client Component cannot import a Server Component, but it can render one passed as children or another prop.
  • Props crossing the boundary must be serializable: primitives, plain objects, arrays, Date, Map, Set, promises and Server Actions, but not plain functions or class instances.
  • A Server Component can pass an unawaited promise to a Client Component that reads it with use inside Suspense.
  • Send only the data the client needs; everything you pass ends up in the payload.

Next: Keeping Server Code on the Server