React Server Components: the server/client boundary, payload and streaming

HOW IT FITS TOGETHER

KEY TERMS

Server vs Client Components

Server Components are the default in RSC frameworks. They may be async, read files, databases and secrets, and import large libraries at zero client cost, but cannot use state, effects, event handlers, context or browser APIs. Client Components are ordinary React components: they are prerendered to HTML on the server and then hydrated in the browser. "Client" means "also runs in the browser", not "only runs in the browser".

"use client" and "use server"

"use client" at the top of a file marks a boundary in the module graph: that module and everything it imports become client code. You put it on entry points, not on every file. "use server" marks server functions (a whole file of exports, or a single async function body). There is no directive for Server Components; they are what you get without one.

RSC payload

A streamed, line-oriented serialization of the rendered Server Component tree: host elements, text, references to client modules with their props, and promises that resolve later in the stream. The client uses it to build or reconcile the React tree; on navigations frameworks fetch and cache only the payload, so Client Component state survives.

Streaming with Suspense

A slow async Server Component inside <Suspense> does not block the shell: the server flushes the fallback first and streams the finished segment later in the same response, and React swaps it in. Without a boundary, the slowest await on the page gates the whole response. Since React 19.2, reveals of streamed boundaries are batched for a short time so nearby content appears together, as on the client; React stops batching as the load nears the 2.5 s LCP threshold.

Server functions (actions)

Async functions marked "use server" that the client can call; the framework turns them into POST endpoints with an opaque ID. Passed to <form action> or useActionState they work before hydration and integrate with transitions. Every one is reachable by anyone who can send a request, so each must authenticate, authorize and validate its arguments itself.

What can cross the boundary

Props from Server to Client Components must be serializable: primitives, globally registered symbols, plain objects, arrays, Map, Set, typed arrays, Date, promises, JSX and server function references. Class instances, ordinary functions and null-prototype objects cannot cross. Everything that crosses is visible in the page source, so pass the fields you need, not the database row.

Framework support

Next.js App Router is the mature, stable implementation. React Router ships RSC support as experimental, unstable_-prefixed APIs on Vite with @vitejs/plugin-rsc; Waku, a minimal RSC-first framework, reached its 1.0 release candidate in August 2026; Parcel 2.14+ has beta RSC support. React itself marks the bundler-facing RSC APIs as able to change between 19.x minors, so frameworks pin React versions.

IN YOUR STACK

// app/orders/[id]/page.tsx  (Server Component: no directive)
import "server-only";
import { db } from "@/lib/db";
import { LikeButton } from "./like-button";

export default async function OrderPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const order = await db.order.findUniqueOrThrow({ where: { id } }); // runs on the server only
  return (
    <article>
      <h1>Order {order.number}</h1>
      <p>{formatMoney(order.totalCents)}</p>
      {/* Pass only what the island needs: it is serialized into the page */}
      <LikeButton orderId={order.id} initialLikes={order.likes} />
    </article>
  );
}

// app/orders/[id]/like-button.tsx
"use client";
import { useState } from "react";
export function LikeButton({ orderId, initialLikes }: { orderId: string; initialLikes: number }) {
  const [likes, setLikes] = useState(initialLikes);
  return <button onClick={() => setLikes((n) => n + 1)}>{likes} likes</button>;
}

// Server Component: start the slow fetch, don't await it.
import { Suspense } from "react";
import { Reviews } from "./reviews";

export default async function ProductPage({ id }: { id: string }) {
  const product = await getProduct(id);   // fast, blocks the shell
  const reviewsPromise = getReviews(id);  // slow, streamed later
  return (
    <>
      <h1>{product.name}</h1>
      <Suspense fallback={<p>Loading reviews...</p>}>
        <Reviews reviewsPromise={reviewsPromise} />
      </Suspense>
    </>
  );
}

// reviews.tsx
"use client";
import { use } from "react";
export function Reviews({ reviewsPromise }: { reviewsPromise: Promise<Review[]> }) {
  const reviews = use(reviewsPromise); // suspends until the stream delivers it
  return <ul>{reviews.map((r) => <li key={r.id}>{r.text}</li>)}</ul>;
}

// app/actions.ts
"use server";
import { z } from "zod";
import { revalidatePath } from "next/cache";
const Rename = z.object({ id: z.uuid(), name: z.string().min(1).max(80) });

export async function renameProject(_prev: State, formData: FormData): Promise<State> {
  const user = await requireUser();                       // authenticate every call
  const input = Rename.safeParse(Object.fromEntries(formData));
  if (!input.success) return { error: "Invalid name" };   // validate every argument
  if (!(await canEdit(user, input.data.id))) return { error: "Forbidden" }; // authorize
  await db.project.update({ where: { id: input.data.id }, data: { name: input.data.name } });
  revalidatePath(`/projects/${input.data.id}`);
  return { error: null };
}

// rename-form.tsx
"use client";
import { useActionState } from "react";
export function RenameForm({ id }: { id: string }) {
  const [state, action, pending] = useActionState(renameProject, { error: null });
  return <form action={action}><input type="hidden" name="id" value={id} />
    <input name="name" /><button disabled={pending}>Save</button>
    {state.error && <p role="alert">{state.error}</p>}</form>;
}

// modal.tsx: a client shell with a server-rendered slot
"use client";
import { useState } from "react";
export function Modal({ trigger, children }: { trigger: string; children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  return <>
    <button onClick={() => setOpen(true)}>{trigger}</button>
    {open && <dialog open>{children}</dialog>}
  </>;
}

// theme-provider.tsx: context lives in a client module
"use client";
import { createContext } from "react";
export const ThemeContext = createContext<"light" | "dark">("light");
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  return <ThemeContext value="dark">{children}</ThemeContext>;
}

// app/layout.tsx (Server Component)
export default function Layout({ children }: { children: React.ReactNode }) {
  return <html><body><ThemeProvider>
    {children}
    <Modal trigger="Cart"><Cart /></Modal>{/* Cart stays a Server Component */}
  </ThemeProvider></body></html>;
}

// Server Component passing props to a "use client" component
export default async function Account() {
  const user = await db.user.find(currentUserId());

  // Leaks: the whole row (passwordHash, stripeId...) is serialized into the HTML.
  // return <Profile user={user} />;

  // Fails: class instances and plain functions cannot be serialized.
  // return <Profile user={new UserModel(user)} onSave={() => save(user)} />;

  // OK: plain data, a Date, a promise, and a server function reference.
  return (
    <Profile
      user={{ id: user.id, name: user.name, joined: user.createdAt }}
      invoices={getInvoices(user.id)}
      onSave={saveProfile} // exported from a "use server" file
    />
  );
}

// vite.config.ts
import { defineConfig } from "vite";
import { unstable_reactRouterRSC as reactRouterRSC } from "@react-router/dev/vite";
import rsc from "@vitejs/plugin-rsc";

export default defineConfig({
  plugins: [reactRouterRSC(), rsc()],
});

// app/routes/favorites.actions.ts
"use server";
import { unstable_getRequest as getRequest } from "react-router";

export async function updateFavorite(formData: FormData) {
  const user = await requireUser(getRequest()); // route middleware is not enough
  const id = String(formData.get("id") ?? "");
  if (!id) throw new Response("Bad request", { status: 400 });
  await favorites.toggle(user.id, id);
  // React Router revalidates the route after a server function call
}

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Putting "use client" on a top-level layout or page: every import below it becomes client code and the bundle win disappears. Push the boundary down to the interactive leaf.
• Passing whole database objects to Client Components. Every serialized prop is in the page source and the RSC payload, including fields the component never renders.
• Treating server functions as private RPC. They are public endpoints; missing per-function auth, authorization and validation is the most common RSC security bug.
• Awaiting every request at the top of the page instead of starting promises in parallel and wrapping slow parts in Suspense, which recreates a waterfall on the server.
• Expecting context, useState or browser APIs in Server Components, or importing a client-only third-party component without wrapping it in a "use client" module.
• Upgrading React minors independently of the framework: the bundler-facing RSC APIs are not semver-stable within 19.x.

WHEN IT BREAKS IN PRODUCTION

• Hydration fails or the page flickers after SSR
• The first page load is slow because of a huge JavaScript bundle
• The UI shows old data after a save
• Users see an old version or chunks fail to load after a deploy

SOURCES

• React: Server Components (opens in new tab)Checked 2026-11-06
• React: 'use client' (opens in new tab)Checked 2026-11-06
• React: 'use server' (opens in new tab)Checked 2026-11-06
• Next.js: Server and Client Components (opens in new tab)Checked 2026-11-06
• React Router: React Server Components (opens in new tab)Checked 2026-11-06
• React 19.2 (opens in new tab)Checked 2026-11-06
• Waku v1 RC (opens in new tab)Checked 2026-11-06