React Server Components: Production Pattern Guide

Component Tree Example

// app/dashboard/page.tsx (Server Component — default)
// ✓ Fetches data directly, no JS sent to browser
export default async function DashboardPage() {
  const data = await db.query("SELECT * FROM metrics");

  return (
    <main>
      {/* Server component — no JS */}
      <MetricsSummary data={data} />

      {/* Client component leaf — JS only for this widget */}
      <InteractiveChart initialData={data} />
    </main>
  );
}

// components/interactive-chart.tsx
"use client";
// ✓ Only this file and its imports become client JS
export function InteractiveChart({ initialData }) {
  const [filter, setFilter] = useState("7d");
  // ... interactive logic
}

Children Pattern — Correct Interleaving

// components/scroll-container.tsx
"use client";
// Client wrapper for scroll/animation behavior
export function ScrollContainer({ children }) {
  const ref = useRef(null);
  useScrollAnimation(ref);
  return <div ref={ref}>{children}</div>;
}

// app/products/page.tsx (Server Component)
import { ScrollContainer } from "@/components/scroll-container";
import { ProductGrid } from "@/components/product-grid"; // Server Component

export default async function ProductsPage() {
  const products = await fetchProducts(); // runs on server

  return (
    // ScrollContainer is a Client Component but its children
    // (ProductGrid) remain a Server Component — no JS for grid
    <ScrollContainer>
      <ProductGrid products={products} />
    </ScrollContainer>
  );
}

Server-Only Protection

// lib/db.ts
import "server-only"; // throws at build if imported from client

import { PrismaClient } from "@/generated/prisma/client";

// This database client will never reach the browser
export const db = new PrismaClient();

CORRECT — Parallel Fetching (1 round trip)

// GOOD: All independent requests fire simultaneously
export default async function DashboardPage() {
  const userId = await getUserId(); // required first — session lookup

  // All fire in parallel — total latency = max(A, B, C) = 120ms
  const [user, projects, metrics] = await Promise.all([
    fetchUser(userId),
    fetchProjects(userId),
    fetchMetrics(userId),
  ]);

  return <Dashboard user={user} projects={projects} metrics={metrics} />;
}

React cache() for Non-Fetch Data Sources

import { cache } from "react";
import { db } from "@/lib/db";

// Calling getUser(id) multiple times in one render
// only hits the DB once — results are memoized per request
export const getUser = cache(async (id: string) => {
  return db.user.findUnique({ where: { id } });
});

// Multiple components can call getUser() freely
// — only one DB query per render pass
export async function UserAvatar({ userId }: { userId: string }) {
  const user = await getUser(userId); // DB hit (first call)
  return <img alt={user.name} src={user.avatarUrl} />;
}

export async function UserCard({ userId }: { userId: string }) {
  const user = await getUser(userId); // Cache hit (no extra DB query)
  return <div>{user.name}</div>;
}

Streaming Dashboard with Independent Boundaries

import { Suspense } from "react";
import { MetricsSkeleton, FeedSkeleton } from "@/components/skeletons";

// The page shell renders immediately (fast)
// Each Suspense boundary streams in independently
export default function DashboardPage() {
  return (
    <div className="grid grid-cols-3 gap-4">
      {/* Renders in ~50ms — static content */}
      <PageHeader />

      {/* Streams when metrics DB query completes (~200ms) */}
      <Suspense fallback={<MetricsSkeleton />}>
        <MetricsPanel />
      </Suspense>

      {/* Streams when feed query completes (~350ms) — independent */}
      <Suspense fallback={<FeedSkeleton />}>
        <ActivityFeed />
      </Suspense>
    </div>
  );
}

// MetricsPanel and ActivityFeed are both async Server Components
async function MetricsPanel() {
  const metrics = await fetchMetrics(); // ~200ms DB query
  return <MetricsDisplay data={metrics} />;
}

Cache Invalidation on Mutation

"use server";
import { revalidatePath, revalidateTag } from "next/cache";

export async function updateProduct(id: string, data: ProductData) {
  await db.product.update({ where: { id }, data });

  // Invalidate specific tag (used with next: { tags: [...] })
  revalidateTag("products");

  // Or invalidate a specific page path
  revalidatePath(`/products/${id}`);
}