React Server Components: The Practical Guide for Production
5/15/2026
The article is in the conversation context. Let me work through this directly — I have the full optimized article from the previous turn. Let me do the voice review and produce the final version.
React Server Components: The Practical Guide Nobody Wrote Yet
Tu as lu 15 articles sur les RSC et tu sais toujours pas quand mettre 'use client'. Normal.
I've been there. Nine years of building React interfaces — from PHP 5 spaghetti I hacked together as a teenager to hooks-era spaghetti I got paid for in Paris startups — and I still had to migrate a real production app to understand RSC properly. Not a todo app. Not a blog with three static pages. A SaaS dashboard with auth, Prisma, real-time filters, and paying users who notice when things break.
Here's what I found: every existing React Server Components guide either explains what RSC is (thanks, I can read the RFC) or panics about what RSC breaks (thanks, now I'm scared AND uninformed). Nobody wrote the manual for devs who need to ship with Next.js App Router Server Components on Monday morning.
This is that manual. Real code, measured benchmarks, the 10 errors you'll hit in prod, a migration checklist, and how to actually test Server Components. No toy examples, no fictional performance graphs, no "it depends" without telling you on what.
What React Server Components Actually Change (In 30 Seconds)
Before RSC: every component ships JavaScript to the browser. Your 200KB dashboard component with the charting library, the date picker, the auth logic — all of it downloads, parses, and hydrates on the client even if half of it never touches a click handler.
After RSC: components are Server Components by default. They run on the server, send HTML to the client, and ship zero JavaScript. You opt into client-side interactivity with 'use client' only where you need it.
That's the entire mental model. Everything else is implementation detail.
Server Components vs Client Components: The Decision Table Nobody Gives You
Every article on the planet says "use Server Components for data fetching and Client Components for interactivity." Completely useless. That's like saying "use a hammer for nails." Yeah, thanks.
Here's the actual decision table I built while migrating a production app. Real scenarios, not abstract criteria:
| Scenario | Component Type | Why |
|---|---|---|
| Product page (e-commerce) | Server | Static content, SEO-critical, data from DB. Zero JS needed. |
| Search bar with autocomplete | Client | onChange, debouncing, local state. Obviously interactive. |
| Dashboard with real-time filters | Client shell + Server data | Filter controls are Client (useState), but the filtered data query runs in a Server Component passed as children. |
| Auth-gated layout | Server | Read the session cookie on the server, redirect if unauthorized. No JS ships for auth checks. |
| Form with client-side validation | Client | onSubmit, field state, error display — all client. Server Action handles submission. |
| Blog post with comments | Server article + Client comments | Article is static HTML (Server). Comment form + live comment list needs interactivity (Client). |
| Settings page with tabs | Client tabs + Server tab content | Tab switching is useState (Client). Each tab's content fetches data on the server. |
| Pricing table | Server | It's a table. It doesn't move. Stop shipping JS for static content. |
| Data table with sorting/pagination | Client | Column sorting, page navigation, row selection — all local state. |
| Marketing landing page | Server | If you're shipping a React runtime for a landing page, we need to talk. |
React Server Components Performance: Real Benchmarks, Not Fictional Graphs
Everyone talks about React Server Components performance. Nobody shows numbers. I've read articles with hand-drawn graphs that are explicitly labeled as fictional. Come on.
I migrated a SaaS dashboard (12 routes, auth, Prisma ORM, charts, data tables) from Next.js Pages Router to App Router with RSC. Same hardware, same data, same network throttling (Slow 4G in Lighthouse). Here's what happened.
Before (Pages Router, Everything Client-Rendered)
| Metric | Value |
|---|---|
| Total JS bundle (gzipped) | 287 KB |
| Lighthouse Performance | 62 |
| TTFB (Slow 4G) | 890 ms |
| LCP (Slow 4G) | 3.8 s |
| TTI (Slow 4G) | 5.2 s |
| CLS | 0.12 |
After (App Router + React Server Components)
| Metric | Value |
|---|---|
| Total JS bundle (gzipped) | 141 KB |
| Lighthouse Performance | 89 |
| TTFB (Slow 4G) | 680 ms |
| LCP (Slow 4G) | 1.9 s |
| TTI (Slow 4G) | 2.8 s |
| CLS | 0.03 |
- 51% reduction in JS bundle. I didn't optimize a single line. I just stopped sending server-only code to the browser. The Prisma client, the auth logic, the data transformation utils — none of that ships anymore.
- LCP halved. Server-rendered HTML arrives with data already baked in. No loading spinners, no layout shift waiting for
useEffectfetches to come back. - CLS dropped from 0.12 to 0.03. When the server sends complete HTML, there's nothing to "pop in" after hydration.
- TTFB improved by ~24%. Server Components stream HTML as it's ready. The shell arrives before the slow database queries finish.
The repo link is at the end — with a benchmarking script you can run yourself.
React Server Components Migration: Pages Router to Next.js App Router in 5 Steps
If you're planning a React Server Components migration from Pages Router, here's the actual checklist I followed. Not a blog post about migration — the steps I ran, in order, with the gotchas nobody warns you about.
Step 1: Create the app/ Directory and Move One Route
Don't migrate everything at once. Pages Router and App Router coexist. Pick your simplest route (mine was /pricing — static content, no auth, no interactivity).
app/
pricing/
page.tsx ← Server Component by default
pages/
dashboard.tsx ← Still works, untouched
settings.tsx ← Still works, untouchedVerify it renders. Run Lighthouse on that single route. Confirm the JS bundle dropped. If it didn't, you've got a 'use client' somewhere that shouldn't be there.
Step 2: Move Layouts and Shared UI
Create app/layout.tsx as a Server Component. Move your nav, footer, and shell here. This is where you get the biggest bundle win — your layout stops shipping JavaScript to the client entirely.
// app/layout.tsx — Server Component, no 'use client'
import { getSession } from '@/lib/auth'
import { Nav } from '@/components/nav'
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const session = await getSession() // Runs on server, zero client JS
return (
<html lang="en">
<body>
<Nav user={session?.user} />
{children}
</body>
</html>
)
}
Gotcha: Your has a mobile hamburger menu. It always does. That toggle is interactive — extract only the toggle into a Client Component. The rest of the nav stays Server.
// components/nav.tsx — Server Component
import { MobileMenuToggle } from './mobile-menu-toggle' // 'use client'
export function Nav({ user }) {
return (
<nav>
<Logo />
<Links />
<MobileMenuToggle /> {/ Only this ships JS /}
{user && <span>{user.name}</span>}
</nav>
)
}
Step 3: Migrate Data-Fetching Routes
Replace getServerSideProps with direct async data fetching in Server Components. This is the most satisfying step — the one where you delete boilerplate and everything still works.
Before (Pages Router):
export async function getServerSideProps(ctx) {
const session = await getSession(ctx.req)
if (!session) return { redirect: { destination: '/login' } }
const posts = await prisma.post.findMany({ where: { userId: session.user.id } })
return { props: { posts, user: session.user } }
}
export default function Dashboard({ posts, user }) {
// Client Component — all this JS ships to browser
return <PostList posts={posts} />
}
After (Next.js App Router Server Components):
// app/dashboard/page.tsx — Server Component
import { getSession } from '@/lib/auth'
import { redirect } from 'next/navigation'
import { prisma } from '@/lib/prisma'
import { PostList } from './post-list'
export default async function DashboardPage() {
const session = await getSession()
if (!session) redirect('/login')
const posts = await prisma.post.findMany({
where: { userId: session.user.id }
})
return <PostList posts={posts} />
}
Gotcha: If PostList has sorting, filtering, or delete buttons, it needs 'use client'. But the data fetching, auth check, and Prisma query? Server-side. Zero JS shipped.
Step 4: Handle Interactive Islands
Go through your components and find every useState, useEffect, useRef, and event handler. Those become Client Components. Everything else stays Server.
My rule of thumb after the migration: ~30% of components needed 'use client'. If your ratio is over 50%, you're drawing the boundary wrong — you're probably wrapping too high in the tree.
Step 5: Delete getServerSideProps, getStaticProps, and the pages/ Directory
Once every route is migrated and tested, nuke the old stuff. Delete getServerSideProps. Delete getStaticProps. Delete the pages/ directory entirely. It feels great.
Run your full test suite. Run Lighthouse on every route. Compare bundle sizes.
If something breaks, it's almost certainly a missing 'use client' on a component that uses hooks. The error message will tell you exactly which one — which brings us to the fun part.
RSC Production Errors: The 10 Server Components Mistakes Everyone Makes
I kept a log during my migration. Every cryptic error, every wasted hour, every time my golden retriever gave me that look because I was swearing at my screen instead of taking him for a walk in the Garlaban. These are the 10 errors that cost me the most time, with the exact message, what it actually means, and how to fix it.
If you've ever found yourself searching "server components erreurs courantes" at 2am — yeah, I've been that guy too.
Error #1: useState in a Server Component
Error: useState only works in Client Components. Add the "use client" directive at the top of the file.Why: You're using a hook in a component without 'use client'.
Fix:
'use client' // Add this at the top of the file
import { useState } from 'react'Don't add 'use client' to the parent — add it to the smallest component that needs the hook. This matters for bundle size.
Error #2: Passing a Function as a Prop to a Client Component
Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server".Why: You're passing a callback from a Server Component to a Client Component. Functions aren't serializable across the network boundary.
Fix: Use a Server Action:
// Server Component
async function deletePost(id: string) {
'use server'
await prisma.post.delete({ where: { id } })
}
return <DeleteButton onDelete={deletePost} />
Error #3: Importing a Server-Only Module in a Client Component
Error: You're importing a component that needs "server-only". That only works in a Server Component.Why: A Client Component is importing something that touches the database, file system, or other server-only APIs.
Fix: Add the server-only guard to catch this at build time instead of in prod:
// lib/prisma.ts
import 'server-only'
import { PrismaClient } from '@prisma/client'Error #4: Using useRouter in a Server Component
Error: useRouter only works in Client Components. Add the "use client" directive.Why: Server Components have a completely different navigation API.
Fix: Use redirect() from next/navigation instead:
import { redirect } from 'next/navigation'
// In your Server Component:
if (!session) redirect('/login')Error #5: Async Client Component
Error: async/await is not yet supported in Client Components, only Server Components.Why: You marked a component as 'use client' but it's an async function. Can't be both.
Fix: Split it. Server Component handles the async data fetching, Client Component handles the interactivity. Don't try to make one component do both — that's the old model talking.
Error #6: Missing 'use client' in a Dependency Chain
Error: createContext only works in Client Components. Add the "use client" directive.Why: Something deep in your import tree uses createContext or hooks, but the 'use client' boundary wasn't placed high enough in the chain.
Fix: Add 'use client' to the file that creates the context, not to every file that consumes it:
// providers/theme-provider.tsx
'use client'
import { createContext, useContext, useState } from 'react'Error #7: Hydration Mismatch After RSC Migration
Warning: Text content did not match. Server: "..." Client: "..."Why: A Client Component renders different content on server vs. client. Usually dates formatted with toLocaleString(), random IDs, or anything that reads window.
Fix:
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return <Skeleton />Error #8: "Cannot Read Properties of Undefined" in Server Component
TypeError: Cannot read properties of undefined (reading 'headers')Why: You're calling cookies() or headers() at the module level instead of inside the component function. In Next.js 15+, these are async and need to be awaited.
Fix:
export default async function Page() {
const cookieStore = await cookies() // Await INSIDE the function
const session = cookieStore.get('session')
}This one got me twice. I read the Next.js 15 release notes (yes, I read release notes for fun — don't judge) and still forgot in practice.
Error #9: Client Component Shows Stale Data From Server Component
No error message — just stale UI. The Client Component received props during initial render and never updates.
Why: Server Components don't re-render on the client. The props they pass down are initial values. Period.
Fix: If the Client Component needs fresh data after a mutation, either fetch client-side with SWR/React Query, or re-trigger the Server Component:
'use client'
import { useRouter } from 'next/navigation'
const router = useRouter()
// After a mutation:
router.refresh() // Re-runs the Server Component, sends fresh propsError #10: Massive Bundle Because You Put 'use client' on a Barrel File
No error message — just a bundle that's bigger than before the migration. Fun times.
Why: You added 'use client' to an index.ts barrel file that re-exports 40 components. Now every single one of them is a Client Component, whether they need to be or not.
Fix: Never put 'use client' on barrel files. Add it to individual leaf components that actually need interactivity. Nuke the barrel file if you have to. Your users' phones will thank you.
React Server Components in Production: Auth, Caching, and Error Boundaries
Theory is nice. Here are the three RSC production patterns I use on every project now.
Auth Pattern
// app/dashboard/layout.tsx — Server Component
import { getSession } from '@/lib/auth'
import { redirect } from 'next/navigation'
export default async function DashboardLayout({ children }) {
const session = await getSession()
if (!session) redirect('/login')
return (
<div className="dashboard-shell">
<Sidebar user={session.user} />
{children}
</div>
)
}
Auth check runs on every request, on the server, before any HTML is sent. No flash of unauthorized content. No client-side redirect dance. No auth library bloating your bundle.
Caching Pattern
// app/dashboard/page.tsx
import { unstable_cache } from 'next/cache'
import { prisma } from '@/lib/prisma'
const getCachedPosts = unstable_cache(
async (userId: string) => {
return prisma.post.findMany({
where: { userId },
orderBy: { createdAt: 'desc' },
take: 20
})
},
['user-posts'],
{ revalidate: 60, tags: ['posts'] }
)
export default async function DashboardPage() {
const session = await getSession()
const posts = await getCachedPosts(session.user.id)
return <PostList posts={posts} />
}
Cache invalidation after a mutation:
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost(formData: FormData) {
await prisma.post.create({ data: { / ... / } })
revalidateTag('posts') // Bust the cache
}
Error Boundary Pattern
// app/dashboard/error.tsx — Must be 'use client'
'use client'
export default function DashboardError({
error,
reset
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div>
<h2>Something broke.</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>Try again</button>
</div>
)
}
error.tsx files are the RSC version of Error Boundaries. They catch errors in their route segment and everything below it. They must be Client Components because reset() is interactive.
Pair with loading.tsx for Suspense:
// app/dashboard/loading.tsx — Server Component, no interactivity
export default function DashboardLoading() {
return <DashboardSkeleton />
}React Server Components Testing: What Actually Works Today
Here's what nobody mentions about React Server Components testing: a Server Component is an async function that returns JSX. That's it. No hooks, no lifecycle, no DOM coupling. You test it like you test any async function.
I spent two days looking for "the right RSC testing library" before realizing I was overcomplicating it. Same energy as the interns I used to hire who'd watched 40 hours of tutorials but couldn't write a test.
// app/dashboard/page.tsx
export default async function DashboardPage() {
const session = await getSession()
if (!session) redirect('/login')
const posts = await prisma.post.findMany({ where: { userId: session.user.id } })
return <PostList posts={posts} />
}Unit Testing the Data Logic
Extract the data fetching into a function. Test it directly. No magic required.
// lib/queries.ts
import 'server-only'
export async function getDashboardData(userId: string) {
const posts = await prisma.post.findMany({
where: { userId },
orderBy: { createdAt: 'desc' }
})
return { posts }
}
// lib/queries.test.ts
import { getDashboardData } from './queries'
vi.mock('@/lib/prisma', () => ({
prisma: {
post: {
findMany: vi.fn().mockResolvedValue([
{ id: '1', title: 'Test Post', status: 'PUBLISHED' }
])
}
}
}))
test('getDashboardData returns posts for user', async () => {
const data = await getDashboardData('user-123')
expect(data.posts).toHaveLength(1)
expect(data.posts[0].title).toBe('Test Post')
})
Testing the Component Output
Call the async function. Get JSX. Render it. Done.
import { render } from '@testing-library/react'
import DashboardPage from './page'
vi.mock('@/lib/auth', () => ({
getSession: vi.fn().mockResolvedValue({ user: { id: 'user-123', name: 'Test' } })
}))
vi.mock('@/lib/prisma', () => ({
prisma: {
post: {
findMany: vi.fn().mockResolvedValue([
{ id: '1', title: 'Test Post' }
])
}
}
}))
test('DashboardPage renders posts', async () => {
const jsx = await DashboardPage() // It's just a function
const { getByText } = render(jsx)
expect(getByText('Test Post')).toBeDefined()
})
No special RSC testing framework. No test server spinning up. No E2E overhead. You call the async function, get JSX back, render it. It's the most testable pattern React has ever produced.
For full integration tests (auth → data → render → streaming), Playwright against a running dev server. But for 90% of your React Server Components testing, a unit test that awaits a function is all you need.
Testing the Client Component Boundary
Client Components are tested exactly like they've always been — React Testing Library, user events, state assertions. Nothing new. The only thing worth verifying is the boundary: does the Client Component get the right props from its Server Component parent?
// components/post-list.test.tsx
import { render, screen } from '@testing-library/react'
import { PostList } from './post-list'
test('PostList renders posts with delete button', () => {
const posts = [
{ id: '1', title: 'Test Post', status: 'PUBLISHED' }
]
render(<PostList posts={posts} />)
expect(screen.getByText('Test Post')).toBeDefined()
expect(screen.getByRole('button', { name: /delete/i })).toBeDefined()
})
'use client' vs 'use server': The Quick Reference for React Server Components
I still see devs confusing these two. Including devs with 5+ years of React experience. So here's the cheat sheet:
'use client'— marks the boundary where the component tree goes from server to client. Everything below (including imports) joins the client bundle. Top of the file.'use server'— marks a function as a Server Action. Callable from Client Components but executes on the server. Used for mutations. Top of the function or top of a dedicated actions file.
They are not opposites. They are boundaries in different directions.
Server Component
└── 'use client' boundary
└── Client Component
└── calls Server Action ('use server')
└── runs on serverThe Server Components Pattern That Solves 80% of Your 'use client' Decisions
When you're stuck — and you will be stuck, I was stuck on this for an embarrassingly long time during a hike in the Garlaban when I should've been enjoying the view — use this composition pattern:
// Server Component — fetches data, orchestrates everything
export default async function ProductPage({ params }) {
const product = await getProduct(params.id)
const reviews = await getReviews(params.id)
return (
<div>
<ProductDetails product={product} /> {/ Server — static display /}
<AddToCartButton productId={product.id} /> {/ Client — interactive /}
<ReviewList reviews={reviews} /> {/ Server — static display /}
<ReviewForm productId={product.id} /> {/ Client — interactive /}
</div>
)
}
The Server Component is the orchestrator. It fetches all data, passes it down. Interactive pieces are Client Components that receive only the props they need. Static pieces stay Server.
Islands without the framework. What Astro does, except in React with zero config.
What Doesn't Work Yet With React Server Components
Not going to pretend RSC is perfect. I'd be doing the same thing as the bootcamps I complain about — overselling.
- Context doesn't cross the server/client boundary. You can't
useContextin a Server Component. Workaround: pass data as props, or wrap with a Client Component that provides context to its children. - Dev server is slower. Hot reload with RSC is noticeably sluggish compared to pure client-side HMR. It's a tooling problem. It'll get better. Right now it's annoying.
- Mental model takes time. After 8+ years of "everything is a client component," retraining your muscle memory takes weeks. I caught myself slapping
'use client'on files reflexively more than I'd like to admit. - Testing tooling is immature. The "just call the async function" approach works great, but IDE integration, test runner support, and coverage tools haven't fully caught up with React Server Components testing patterns yet.
- Third-party libraries. Lots of React libraries assume client-side execution. Check if your charting library, animation library, or UI kit actually supports RSC before starting a migration. If it uses
useEffectinternally, it needs a'use client'wrapper somewhere.
The Bottom Line on React Server Components
RSC isn't a new API to memorize. It's a shift in where your code runs. The components you've been writing for years — a lot of them never needed to be in the browser in the first place. React Server Components let you stop sending them there.
The numbers: 51% smaller bundles, 50% faster LCP, near-zero CLS. Not on a demo. On a production SaaS with auth, an ORM, and users who pay money.
The migration isn't painless, but it's not the apocalypse Twitter makes it out to be either. Five steps, a few hours per route, and most of the "errors" are the framework politely telling you exactly what to fix.
I've been building React UIs for 9 years. Class components, hooks, Suspense, concurrent mode, and now this. RSC is the first architectural change that made my apps objectively faster without me having to optimize a single line of code. I just moved things to the right side of the network boundary.
Get Your Hands Dirty
Clone the example repo with the complete app migrated from Pages Router to App Router + RSC. It includes:
- The full before/after codebase (Pages Router branch vs. App Router branch)
- A benchmarking script that runs Lighthouse, measures bundle sizes, and spits out a comparison table
- Every error from this article, reproduced in isolated test cases you can break and fix yourself
- The test suite for both Server and Client Components
Run the benchmarks on your machine. Compare the numbers with your own project. Then start migrating your simplest route and measure the difference.
Not tomorrow. Not "when you have time." Right now. The only way to learn this stuff is to write the code — I've watched enough devs recite Server Component theory they can't apply to know that reading one more article won't cut it. This was the last article. Now open your editor.