React Reference ยท Concepts and Pitfalls
Server Components
How React Server Components work: components that run only on the server, the use client boundary, what can cross it, and where they fit with SSR.
A Server Component is a React component that runs only on the server, either at build time or per request. It can be async, it can read a database or the file system directly, and its code and dependencies are never sent to the browser. What the browser receives is the rendered result: a description of the UI tree, in React's own serialized format, which the client merges into the page.
Server Components need a framework or bundler integration (Next.js App Router, React Router framework mode, Waku and others); plain createRoot apps do not have them. In such a setup every component is a Server Component by default, and the 'use client' directive marks the file where Client Components begin.
// Server Component: runs on the server only export default async function Posts() { const posts = await db.posts.findAll(); return ( <ul> {posts.map((p) => ( <li key={p.id}>{p.title}</li> ))} </ul> ); }
The component above is shown read-only because the site cannot run a server. The examples below use stand-ins that follow the same data flow, so you can see what actually travels to the browser.
Try it
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.
The payload contains tags, text and one reference object, {"$$client":"LikeButton"}. The PostList and Page functions, the database and everything they imported stay on the server.
Server and Client Components
| Server Component | Client Component | |
|---|---|---|
| Runs | On the server (build or request) | In the browser, and also on the server for the first HTML |
Can be async |
Yes | No |
| State, effects, event handlers | No | Yes |
| Browser APIs | No | Yes |
| Reads the database or files | Yes | No (call a server function or API) |
| Code sent to the browser | None | Yes, in the bundle |
| Marked by | Default | 'use client' at the top of the file |
A Server Component can import and render Client Components. A Client Component cannot import a Server Component, but it can receive one as children or another prop, because the server renders it first and passes the result through.
What can cross the boundary
Props passed from a Server Component to a Client Component are serialized. Plain values (strings, numbers, booleans, arrays and objects of those), Date, Map, Set, BigInt, typed arrays, promises and other Server Component output (JSX) can cross. Functions, class instances and anything closing over server-only state cannot, with one exception: server functions marked 'use server'. Passing a promise lets the client read it with use while the rest of the page is already visible.
Server Components and SSR are different things
Server-side rendering turns Client Components into HTML for the first paint, and the browser then hydrates them. Server Components never hydrate because they have no client code. In a typical app both happen: Server Components produce the payload, SSR turns that payload plus Client Components into HTML, and hydration attaches handlers only to the Client Component parts.
Usage notes
- Default to server, add
'use client'at the leaves that need interactivity. Keep the boundary as low in the tree as practical so less code ships. 'use client'marks a module boundary, not a single component. Everything that file imports becomes client code too.- No state or lifecycle on the server. Hooks like
useStateanduseEffectthrow in a Server Component.useanduseIdwork. - Secrets stay safe by structure, but a value you pass as a prop to a Client Component is public.
taintAPIs can guard against leaks. - Data fetching is plain
await. Fetch in parallel withPromise.allor by starting promises early; sequential awaits create waterfalls. - Caching and revalidation are provided by the framework. React offers
cacheto deduplicate calls within one render. - Streaming: wrap slow parts in
Suspenseso the shell is sent first.