server-components-design

name	server-components-design
description	Use when designing or reviewing React Server Components: what an RSC can do (async, data fetching, server-only imports) versus what it cannot (state, effects, event handlers, browser APIs), where to draw the server/client boundary in the tree, and how RSC composes with Suspense to stream content without a separate API layer. Covers Next.js App Router as the canonical implementation, but the discipline is framework-agnostic. Do NOT use for the 'use client' directive mechanics (use client-server-boundary), hook discipline on Client Components (use hooks-patterns), rendering strategy choice (use rendering-models), or the server-action mutation surface (use server-actions-design when authored).
license	MIT
allowed-tools	Read Grep
metadata	{"metadata":"{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"React Server Components\\\\\\\",\\\\\\\"RSC\\\\\\\",\\\\\\\"Next.js App Router\\\\\\\",\\\\\\\"async components\\\\\\\",\\\\\\\"server-side data fetching\\\\\\\",\\\\\\\"streaming RSC\\\\\\\",\\\\\\\"server/client component tree\\\\\\\",\\\\\\\"RSC payload\\\\\\\",\\\\\\\"Suspense boundaries with RSC\\\\\\\",\\\\\\\"data flow without API layer\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a Server Component or a Client Component\\\\\\\",\\\\\\\"can I fetch data here\\\\\\\",\\\\\\\"why can't I use useState in this file\\\\\\\",\\\\\\\"how does data move from server to client\\\\\\\",\\\\\\\"do I need an API route\\\\\\\",\\\\\\\"why is the bundle so large\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether a dashboard widget should be a Server Component (fetches and renders) or a Client Component (interactive)\\\\\\\",\\\\\\\"explain why a Server Component cannot pass a function as a prop to a Client Component\\\\\\\",\\\\\\\"design a page where the layout fetches user data once and child widgets fetch their own data, with Suspense streaming each in\\\\\\\",\\\\\\\"audit a component tree for unnecessary 'use client' boundaries that pull static rendering into the bundle\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"add a click handler to an existing component (use hooks-patterns and client-server-boundary)\\\\\\\",\\\\\\\"choose between SSR and SSG for a marketing page (use rendering-models)\\\\\\\",\\\\\\\"build the form-submission mutation flow (use server-actions-design when authored)\\\\\\\",\\\\\\\"design the public API for a third-party integration (use api-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"rendering-models\\\\\\\",\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"streaming-architecture\\\\\\\",\\\\\\\"suspense-patterns\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the serialization-and-directive mechanics of the boundary itself ('use client', what can cross, RSC payload format); server-components-design owns the discipline of which work belongs on the server side of that boundary.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"rendering-models\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"rendering-models owns the strategic decision among SSR, SSG, ISR, and CSR; server-components-design operates within the App Router / RSC paradigm and is one rendering mode among several.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"hooks-patterns covers state and effect discipline on Client Components; Server Components cannot use those primitives at all, so the two skills cover disjoint surfaces.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"rendering-models\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A Server Component is to a React tree what a printed page is to a book — the typesetter (server) sets the lead, presses the ink, and ships the printed page (RSC payload); the reader's table lamp (Client Component) is wired and switchable at the reader's end. You do not ship the typesetter to the reader's living room, and you do not ship the lamp's wiring to the printer — the boundary is where 'this never changes once it leaves my workshop' ends and 'this responds to who touches it' begins.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A React Server Component is a component that runs only on the server, never ships to the browser as JavaScript, can be async, and can directly access server-side resources (databases, file system, secrets) — its output is serialized to a wire format (the RSC payload) and reconstituted into the client tree without a separate API layer. Server Components compose with Client Components in a single tree, but the directionality is one-way: a Server Component can render a Client Component, but a Client Component cannot import a Server Component as a child.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\…","skill_graph_source_repo":"https://github.com/jacob-balslev/skill-graph","skill_graph_protocol":"Skill Metadata Protocol v4","skill_graph_project":"Skill Graph","skill_graph_canonical_skill":"skills/server-components-design/SKILL.md"}

Server Components Design

Coverage

The discipline of designing React Server Components (RSC): what an RSC is for, what it can do that Client Components cannot, what it cannot do, how the server/client boundary shapes the component graph and the data-flow graph, how RSC composes with Suspense to stream content from the server in chunks, why Server Components remove the need for a separate API layer for read-path data, and the recurring design questions a reviewer asks of any RSC tree. Next.js App Router is the canonical implementation referenced throughout; the discipline applies to any RSC implementation (Remix RSC, Waku, hand-rolled RSC servers) since the underlying primitive is the React RFC, not a single framework.

Philosophy

The original React component model collapsed two roles into one function: produce HTML for the initial render, and produce a virtual DOM update in response to client-side state. Server-Side Rendering pre-React-18 tried to make that single function run twice — once on the server to produce HTML, once on the client to produce the interactive tree — and pay for it with hydration: a full re-execution on the client to bind event handlers and reconstruct state.

Hydration has two costs the industry tolerated for a decade: every component must ship to the client (bundle size grows with the page), and every component re-runs on the client (CPU cost grows with the page). React Server Components separate the two roles into different kinds of component. A Server Component runs once, on the server, and produces a serialized output that the client uses directly — no shipping, no re-execution. A Client Component is what we used to call "a component": ships to the browser, runs on render and on every interaction.

The discipline of RSC design is to push as much of the tree as possible to the server side of the boundary, and to draw the line as close to the actual interactive leaves as possible. A button needs useState; the dashboard surrounding the button does not. A chart that responds to filter clicks is interactive; the page header above it is not. The win is real: bundle size shrinks toward "only the interactive parts," and the server has direct access to databases, file systems, and secrets without an intermediating API layer.

But the boundary is unforgiving. A Server Component cannot use hooks. It cannot read state. It cannot attach event handlers. Anything that crosses to a Client Component must be serializable — strings, numbers, plain objects, arrays, Promises (in React 19), JSX, and React elements; not functions, not class instances, not symbols, not Maps. The discipline is to express the work in shapes that respect that constraint, and to use Suspense boundaries to let the server-rendered tree stream piece by piece rather than blocking on the slowest piece.

What a Server Component Can Do (And What a Client Component Cannot)