Composing Server and Client Components

A button that opens server-rendered details

The tea shop's Mint tea page has two kinds of work in it. The facts about the tea, where it's grown and how it tastes, come from the shop's database, so they belong on the server. A Show details button opens and closes them, and a button that reacts to clicks belongs in the browser. Server Components in Next.js and Client Components teach each kind on its own. The two fit together: a Client Component can hold a Server Component, as long as a Server Component puts it there.

This example is a real Next.js 16.4.3 project. It was built with next build and run with next start, and then real Chrome opened it and clicked the button. The result under the files is that recording.

1import Details from "./details";2import TeaFacts from "./tea-facts";3 4export default function MintPage() {5  return (6    <main>7      <h1>Mint tea</h1>8      <Details>9        <TeaFacts />10      </Details>11    </main>12  );13}

The project has three files that matter here:

• app/tea-facts.tsx is a Server Component. On line 4 it waits for getTea("mint") from app/teas.ts, a stand-in for the database.
• app/details.tsx is a Client Component: line 1 is "use client". Line 6 keeps open in state, the button on lines 9 to 11 flips it, and line 12 shows children only while it's open.
• app/page.tsx, a Server Component, puts the two together. On lines 8 to 10, <TeaFacts /> sits between <Details> and </Details>, so it becomes Details's children.

Open the Steps tab and pick the second step: Chrome clicked Show details, and Grown in Morocco appeared. The list of requests for that step is empty. The facts weren't fetched when the button was clicked: they were already in the browser. Now open the Network tab. The first response is the page's HTML, and its visible markup doesn't contain Grown in, because the details start closed. Pick the second response, the page's RSC payload: the description of what the Server Components rendered, with the props for Client Components. The recording asked for it with the rsc: 1 header; on a first visit, Next.js sends the same payload inside the HTML response, in inline scripts. There the facts are, as plain text: Grown in and Morocco.

The recording also searched the JavaScript files the page loads. They contain Show details, from Details. They don't contain Grown in: TeaFacts's code never reached the browser, only what it rendered.

Server Components as children of Client Components

TeaFacts sits inside Details on the page, yet it runs on the server. That's because React keeps two roles apart, and Next.js's guide to the boundary names them:

• The owner of an element is the component whose code wrote it. <TeaFacts /> is written on line 9 of app/page.tsx, so its owner is MintPage.
• The parent is the component that holds it when the page is put together. Details is the parent of TeaFacts.

The owner decides where a component runs. MintPage is a Server Component, so React runs TeaFacts on the server, while it renders the page. By the time Details runs, TeaFacts is already done, and what Details receives as children is its output. Details places it, hides it or shows it, but can't run it again.

Look at the imports. "use client" on line 1 of app/details.tsx pulls everything that file imports into the browser's JavaScript, as Client Components shows. Line 3 imports only React. TeaFacts is imported by app/page.tsx, a Server Component, so its code stays on the server.

children isn't special. Any prop can carry JSX across. Here Details takes the facts as a prop called facts:

1import Details from "./details";2import TeaFacts from "./tea-facts";3 4export default function MintPage() {5  return (6    <main>7      <h1>Mint tea</h1>8      <Details facts={<TeaFacts />} />9    </main>10  );11}

Line 8 of app/page.tsx passes facts={<TeaFacts />}, and line 12 of app/details.tsx shows facts while the details are open. The Steps tab shows the same result as before: the facts appear on the click, with no request. The recording searched the JavaScript again, and Grown in isn't in it. A Client Component can take several of these props, like a title and children, and put each one in its own place.

Each row asks where each component in the Mint tea page runs. Read it with the owner and parent in mind:

Props must be serializable

A Server Component and a Client Component run in different places, so props from one to the other have to travel. Next.js puts them in the RSC payload, as text. A value that can be turned into text and back into the same value is called serializable. React has its own format for this, and it carries more than JSON can: a Date comes back as a Date, not as a string.

Try it below. Each button is a version of the Mint tea page that passes a different kind of value to a Client Component, and each one was built with real Next.js. Before you click, guess which versions build.

1import Stock from "./stock";2 3export default function MintPage() {4  const harvested = new Date("2026-05-12");5  const stock = new Map([["mint", 4], ["green", 0]]);6  return (7    <main>8      <h1>Mint tea</h1>9      <Stock harvested={harvested} stock={stock} />10    </main>11  );12}

Two versions build and two don't:

• A Date and a Map cross as themselves. Stock calls harvested.toISOString() and stock.get("mint"), which only work on a real Date and a real Map. The recorded page shows Harvested on 2026-05-12 and Mint tea in stock: 4, and Chrome logged no error when React ran the same code in the browser.
• A function can't cross. A function is code, and code from a Server Component stays on the server. The build stops while it prerenders the page: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server". A prop whose name starts with on, like onAdd, gets a different message for the same reason, Event handlers cannot be passed to Client Component props, as The React you need for Next.js recorded.
• A class instance can't cross either. The payload could carry its fields, but not its class, so the build stops: Only plain objects, and a few built-ins, can be passed to Client Components from Server Components. Turn it into a plain object, like { name: tea.name, price: tea.price }, before you pass it.
• A Server Function crosses as a reference: an id the browser can send back. Open its Steps tab and pick the click: Chrome sent a POST to / with a next-action header, and the Terminal tab shows what next start printed, addToCart ran on the server for mint. That text isn't in the page's JavaScript. The function ran on the server; only the request to run it came from the browser.

Next.js's TypeScript plugin, in your editor, only accepts a function-typed prop on a Client Component when its name is action or ends in Action, because a Server Function and an ordinary function have the same type. That's why the prop is called addAction. Each row is one kind of value, from React's reference for "use client" and the recordings above:

Being able to cross doesn't make a value safe to send. Everything in a prop reaches the browser, even the fields the Client Component never shows. Server-only code and environment variables shows how that leaks secrets.

Passing a promise and reading it with use()

A promise is serializable too. The React you need for Next.js showed the pattern: a Server Component starts a request without await, passes the promise to a Client Component, and the Client Component reads it with use. Here is why you'd want it. The Mint tea page shows its reviews: they come from the server, and the list has a Show all button, which needs state.

1import { Suspense } from "react";2import { getReviews } from "./reviews";3import ReviewList from "./review-list";4 5export default function MintPage() {6  const reviews = getReviews();7  return (8    <main>9      <h1>Mint tea</h1>10      <Suspense fallback={<p>Loading reviews…</p>}>11        <ReviewList reviews={reviews} />12      </Suspense>13    </main>14  );15}

Line 6 of app/page.tsx calls getReviews() without await, so reviews is a promise, and the page doesn't wait for it. Line 11 hands the promise to ReviewList, inside the Suspense on lines 10 to 12. In app/review-list.tsx, line 8 reads it with use(reviews). Until the promise settles, the component waits, and the Suspense shows Loading reviews…. Line 9 keeps showAll in state, and line 18 is the button. In app/reviews.ts, line 6 calls connection(), which waits for a real request, so the reviews are read for each visitor and not during the build.

Open the Terminal tab: ◐ /, prerendered as static HTML with dynamic server-streamed content. The heading and the fallback were made during the build. The Network tab shows the HTML as it arrived: the fallback inside <main>, and further down, in a hidden <div>, the first review and the button, which React swaps in. That markup holds only Asha's review. Yet in the Steps tab, clicking Show all 3 reviews shows Ben's and Chen's with no request at all. They came with the page, in the RSC payload, as the promise's value: the second response, the payload recorded with rsc: 1, holds all three reviews. On a first visit, that payload arrives inside the HTML response, in inline scripts. The JavaScript files don't contain Cool and fresh: the reviews are data, not code.

The other way to load them is the one you may know from client-rendered React apps: the Client Component asks for them itself, in an Effect, from a Route Handler, a route.ts file that answers requests with data. Step through both. Before you start, guess after which step each visitor sees the first review.

As a promise, the first review is on the screen after step 4, and nothing else is requested. Fetched in an Effect, it shows after step 6: the browser waits for the HTML, then the JavaScript, then hydration, React running the Client Components in the browser over the HTML that's already there, and only then starts a second request. Here is that version, recorded:

1"use client";2 3import { useEffect, useState } from "react";4 5type Review = { id: number; author: string; text: string };6 7export default function ReviewList() {8  const [all, setAll] = useState<Review[] | null>(null);9  const [showAll, setShowAll] = useState(false);10  useEffect(() => {11    fetch("/api/reviews")12      .then((response) => response.json())13      .then(setAll);14  }, []);15  if (all === null) return <p>Loading reviews…</p>;16  const shown = showAll ? all : all.slice(0, 1);17  return (18    <section>19      {shown.map((review) => (20        <p key={review.id}>21          {review.author}: {review.text}22        </p>23      ))}24      {!showAll && <button onClick={() => setShowAll(true)}>Show all {all.length} reviews</button>}25    </section>26  );27}

Lines 10 to 14 of app/review-list.tsx are the Effect, and line 15 shows Loading reviews… until it's done. The visible markup of the Network tab's HTML has only Loading reviews…, and the Steps tab lists two requests for one visit: the page, then GET /api/reviews. Next.js's docs still suggest fetching in the browser when the data depends on something only the browser knows, like what the visitor typed.

Context providers in a Client Component

The shop shows a cart count at the top of every page, and every Add button changes it. Context shares a value like that with every component below a provider, without passing props through each one. But context needs the browser: createContext and the state behind it only work in Client Components, and a Server Component can't read context. The answer is the same pattern as Details: a Client Component that provides the context and takes children.

1import CartProvider from "./cart-provider";2import CartCount from "./cart-count";3 4export const metadata = { title: "Tea shop" };5 6export default function RootLayout({ children }: LayoutProps<"/">) {7  return (8    <html lang="en">9      <body>10        <CartProvider>11          <CartCount />12          {children}13        </CartProvider>14      </body>15    </html>16  );17}

app/cart-provider.tsx starts with "use client". Line 5 creates CartContext, line 8 keeps the count in state, and line 9 provides it with an add function around children. In app/layout.tsx, still a Server Component, lines 10 to 13 wrap the page in CartProvider, with CartCount above it. CartCount and AddTea read the context with use(CartContext) on line 7 of their files.

The page is the layout's children, so it stays a Server Component: line 5 of app/page.tsx still awaits getTeas() on the server. The Steps tab shows Chrome clicking Add Mint tea, then Add Green tea, and the count going to Cart: 1 and then Cart: 2, with no request. Two Client Components inside a Server Component page share one value from a provider above it.

Common mistakes at the boundary

The most common mistake is to import a Server Component into a Client Component's file, instead of passing it in. It looks like the same page. Try four ways of putting TeaFacts inside Details; each opens on the click, in the Steps tab, unless its build failed.

1import Details from "./details";2import TeaFacts from "./tea-facts";3 4export default function MintPage() {5  return (6    <main>7      <h1>Mint tea</h1>8      <Details>9        <TeaFacts />10      </Details>11    </main>12  );13}

What happened in each version:

• Passed as children, the pattern from the start of this lesson, works, and keeps TeaFacts on the server.
• Imported, no data: the import on line 4 of app/details.tsx makes TeaFacts client code, with or without a directive of its own. It still works, because this TeaFacts only returns fixed text, but its code is in the browser's JavaScript now: the recording found Grown in there.
• Imported, async: the build passes and the page loads. On the click, React tries to render an async component in the browser, and the page breaks: React's error #482 says an async Client Component isn't supported, and Next.js shows This page couldn’t load. This bug waits for a visitor to click.
• Imported, reads a cookie: cookies() from next/headers only works on the server, so Turbopack stops the build. Its message says one of the module's parents is marked with "use client", so the module is a Client Component too, and its import trace lists app/details.tsx.

Each row is one mistake, what you'll see, and the fix. The recordings in this lesson show every one of them.

The whole Mint tea page

Here is the page with every pattern from this lesson: the cart provider in the layout, an Add button, the details with the facts as children, and the reviews as a promise.

1import { Suspense } from "react";2import AddTea from "./add-tea";3import Details from "./details";4import TeaFacts from "./tea-facts";5import ReviewList from "./review-list";6import { getReviews } from "./reviews";7 8export default function MintPage() {9  const reviews = getReviews();10  return (11    <main>12      <h1>Mint tea</h1>13      <AddTea name="Mint tea" />14      <Details>15        <TeaFacts />16      </Details>17      <Suspense fallback={<p>Loading reviews…</p>}>18        <ReviewList reviews={reviews} />19      </Suspense>20    </main>21  );22}

MintPage stays a Server Component from top to bottom. Line 9 starts the reviews, line 13 renders the AddTea button, lines 14 to 16 give Details the facts, and lines 17 to 19 stream the reviews. The build prints ◐ /. In the Steps tab, three clicks change the cart, open the facts and show every review, and none of them makes a request. The page's JavaScript contains Show details and Show all, but not Grown in or Cool and fresh.

Sort the page's parts. Which ones send their code to the browser?

Common mix-ups

• "A Server Component inside a Client Component becomes a Client Component." No. Its owner decides. Passed in by a Server Component, it runs on the server, and the Client Component only places its output. Only an import from a client file makes it client code.
• "A provider in the root layout turns the whole app into Client Components." No. The pages arrive as children and stay Server Components. The shop's Home still awaited getTeas() on the server.
• "Props are sent as JSON." No. React's format also carries Date, Map, Set, promises, JSX and Server Function references. It doesn't carry ordinary functions or objects made from your own classes.
• "Passing a promise means the browser fetches the data." No. The server reads it, and the value arrives with the page. In the recording, showing all three reviews sent no request.
• "A Server Function prop sends the function to the browser." No. The browser gets a reference. Calling it sends a POST, and the server runs the function.
• "If it builds, the boundary is fine." No. The imported async TeaFacts and Menu.Item both built, then broke the page when a visitor clicked.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

"use client";

type Props = { harvested: Date; stock: Map<string, number> };

export default function Stock({ harvested, stock }: Props) {
  return (
    <ul>
      <li>Harvested on {harvested.toISOString().slice(0, 10)}</li>
      <li>Mint tea in stock: {stock.get("mint")}</li>
    </ul>
  );
}

import Details from "./details";
import TeaFacts from "./tea-facts";

export default function MintPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <Details>
        <TeaFacts />
      </Details>
    </main>
  );
}

import Price from "./price";

export default function MintPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <Price price={3} formatPrice={(amount) => `$${amount}.00`} />
    </main>
  );
}

"use client";

import { useState } from "react";

function formatPrice(amount: number) {
  return `$${amount}.00`;
}

export default function Price({ price }: { price: number }) {
  const [count, setCount] = useState(1);
  return (
    <p>
      {count} × {formatPrice(price)} = {formatPrice(price * count)}{" "}
      <button onClick={() => setCount(count + 1)}>One more</button>
    </p>
  );
}

import { createContext, useState, type ReactNode } from "react";

export const CartContext = createContext({ count: 0, add: () => {} });

export default function CartProvider({ children }: { children: ReactNode }) {
  const [count, setCount] = useState(0);
  return <CartContext value={{ count, add: () => setCount(count + 1) }}>{children}</CartContext>;
}

"use client";

import { createContext, useState, type ReactNode } from "react";

export const CartContext = createContext({ count: 0, add: () => {} });

export default function CartProvider({ children }: { children: ReactNode }) {
  const [count, setCount] = useState(0);
  return <CartContext value={{ count, add: () => setCount(count + 1) }}>{children}</CartContext>;
}

import { getReviews } from "./reviews";
import ReviewList from "./review-list";

export default async function MintPage() {
  const reviews = await getReviews();
  return (
    <main>
      <h1>Mint tea</h1>
      <ReviewList reviews={reviews} />
    </main>
  );
}

import { Suspense } from "react";
import { getReviews } from "./reviews";
import ReviewList from "./review-list";

export default function MintPage() {
  const reviews = getReviews();
  return (
    <main>
      <h1>Mint tea</h1>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <ReviewList reviews={reviews} />
      </Suspense>
    </main>
  );
}

"use client";

import { useState, type ReactNode } from "react";

export default function Menu({ children }: { children: ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <nav>
      <button onClick={() => setOpen(!open)}>Menu</button>
      {open && <ul>{children}</ul>}
    </nav>
  );
}

Menu.Item = function MenuItem({ children }: { children: ReactNode }) {
  return <li>{children}</li>;
};

"use client";

import { useState, type ReactNode } from "react";

export default function Menu({ children }: { children: ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <nav>
      <button onClick={() => setOpen(!open)}>Menu</button>
      {open && <ul>{children}</ul>}
    </nav>
  );
}

export function MenuItem({ children }: { children: ReactNode }) {
  return <li>{children}</li>;
}

// app/page.tsx
import Menu, { MenuItem } from "./menu";

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Menu>
        <MenuItem>Teas</MenuItem>
        <MenuItem>Gift boxes</MenuItem>
      </Menu>
    </main>
  );
}

Check your understanding

For each question, ask who owns each component, and what has to travel between the server and the browser.

Key takeaways

• A Client Component can hold Server Components when a Server Component passes them in, as children or any other prop. They run on the server, and the Client Component gets their output.
• The owner, the component whose code writes the JSX, decides where it runs. The parent only places the output.
• Props must be serializable by React: values, plain objects, Date, Map, Set, promises, JSX and Server Functions cross. Ordinary functions and class instances stop the build.
• Pass a promise without await and read it with use() inside Suspense: the shell is built ahead, and the data arrives with the page, with no second request.
• Context needs a Client Component provider that takes children. The pages inside it stay Server Components.
• Importing a Server Component into a client file makes it client code. Some of these mistakes stop the build; others only break when a visitor clicks.

Coming next: Server-only code and environment variables. It keeps secrets on the server with server-only, .env files and the NEXT_PUBLIC_ prefix, and shows how they still leak.