React Server Components Explained: Architecture, Internals, and Production Pitfalls

// app/products/[id]/page.tsx — Next.js 13+ App Router
// This is a Server Component by default (no 'use client' directive)
// It runs ONLY on the server. Never shipped to the browser.

import { Suspense } from 'react';
import { getProductById } from '@/lib/db'; // direct DB call — safe here
import { AddToCartButton } from '@/components/AddToCartButton'; // Client Component
import { ProductReviews } from '@/components/ProductReviews'; // another Server Component

// The props come from the URL — Next.js injects them server-side
interface ProductPageProps {
  params: { id: string };
}

export default async function ProductPage({ params }: ProductPageProps) {
  // Await the database directly — no useEffect, no loading state needed here
  // This query NEVER appears in the client bundle
  const product = await getProductById(params.id);

  if (!product) {
    // notFound() throws a special Next.js error that renders the not-found page
    notFound();
  }

  return (
    <article className="product-detail">
      <h1>{product.name}</h1>

      {/* Serializable primitive props cross the Server→Client boundary fine */}
      <p className="price">${product.price.toFixed(2)}</p>

      {/*
        AddToCartButton is a Client Component ('use client').
        We pass only serializable props — productId (string) is fine.
        Passing the entire `product` object would serialize all its fields.
        Be deliberate: pass the minimum data the client component needs.
      */}
      <AddToCartButton
        productId={product.id}
        productName={product.name}
        price={product.price}
      />

      {/*
        Suspense lets the page stream — the product info above renders
        immediately while reviews fetch in parallel on the server.
        The browser shows the fallback until the ProductReviews chunk arrives.
      */}
      <Suspense fallback={<p>Loading reviews...</p>}>
        <ProductReviews productId={product.id} />
      </Suspense>
    </article>
  );
}

// lib/db.ts — this module is NEVER in the client bundle
// because it's only imported by Server Components
export async function getProductById(id: string) {
  // Direct Postgres query — no REST API needed
  const row = await sql`SELECT * FROM products WHERE id = ${id} LIMIT 1`;
  return row ?? null;
}

// ✅ PATTERN 1: Server Component wraps Client Component
// app/dashboard/page.tsx — Server Component
import { MetricsChart } from '@/components/MetricsChart'; // Client Component
import { getDashboardMetrics } from '@/lib/analytics'; // server-only DB call

export default async function DashboardPage() {
  // Fetch on server, pass serializable data to client
  const metrics = await getDashboardMetrics();

  // metrics = { revenue: 48200, orders: 312, topProducts: ['A','B','C'] }
  // All primitive/plain-object values — safe to serialize
  return <MetricsChart data={metrics} />;
}

// components/MetricsChart.tsx
'use client'; // This marks the Client boundary

import { useState, useEffect } from 'react';
import { LineChart } from 'recharts'; // Client-side charting library

interface MetricsData {
  revenue: number;
  orders: number;
  topProducts: string[];
}

export function MetricsChart({ data }: { data: MetricsData }) {
  // useState and useEffect are fine here — this IS a Client Component
  const [highlightedProduct, setHighlightedProduct] = useState<string | null>(null);

  return (
    <div>
      <LineChart data={[data]} width={600} height={300} />
      <ul>
        {data.topProducts.map((product) => (
          <li
            key={product}
            onClick={() => setHighlightedProduct(product)}
            style={{ fontWeight: highlightedProduct === product ? 'bold' : 'normal' }}
          >
            {product}
          </li>
        ))}
      </ul>
    </div>
  );
}

// ----------------------------------------------------------------

// ✅ PATTERN 2: Passing Server Components as children to Client Components
// This keeps the server logic on the server even inside a client wrapper

// components/Modal.tsx — Client Component (needs state for open/close)
'use client';
import { useState, ReactNode } from 'react';

export function Modal({ trigger, children }: { trigger: string; children: ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>{trigger}</button>
      {isOpen && (
        <div className="modal-overlay" onClick={() => setIsOpen(false)}>
          <div className="modal-content" onClick={(e) => e.stopPropagation()}>
            {children} {/* children was resolved by the server — no bundle cost */}
          </div>
        </div>
      )}
    </div>
  );
}

// app/orders/page.tsx — Server Component
import { Modal } from '@/components/Modal';
import { getOrderHistory } from '@/lib/orders';

export default async function OrdersPage() {
  const orders = await getOrderHistory(); // server-only

  return (
    <Modal trigger="View Order History">
      {/* This JSX is resolved on the server and passed as serialized nodes */}
      <ul>
        {orders.map((order) => (
          <li key={order.id}>
            {order.date} — ${order.total}
          </li>
        ))}
      </ul>
    </Modal>
  );
}

// ----------------------------------------------------------------

// ❌ ANTI-PATTERN: Importing a Server Component inside a Client Component
// components/BadWrapper.tsx
'use client';
// THIS WILL FAIL OR PRODUCE WRONG BEHAVIOR:
// import { ProductReviews } from './ProductReviews'; // Server Component
// ProductReviews gets pulled into the client bundle — server-only code breaks
// Fix: Pass <ProductReviews /> as a child from a Server Component parent instead

// lib/actions/product-actions.ts
// Server Actions file — all functions here run on the server
'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { redirect } from 'next/navigation';
import { z } from 'zod'; // Validation still matters on the server
import { updateProduct, deleteProduct } from '@/lib/db';
import { auth } from '@/lib/auth'; // Server-only auth check

// Zod schema for validating incoming form data
const UpdateProductSchema = z.object({
  name: z.string().min(1).max(200),
  price: z.coerce.number().positive(), // coerce because FormData gives strings
  description: z.string().optional(),
});

// Server Action — called from a Client Component form
export async function updateProductAction(
  productId: string,
  formData: FormData
): Promise<{ success: boolean; error?: string }> {
  // 1. Auth check — this runs on the server, never exposed to client
  const session = await auth();
  if (!session?.user?.isAdmin) {
    return { success: false, error: 'Unauthorized' };
  }

  // 2. Extract and validate — FormData values are always strings
  const rawData = {
    name: formData.get('name'),
    price: formData.get('price'),
    description: formData.get('description'),
  };

  const parsed = UpdateProductSchema.safeParse(rawData);
  if (!parsed.success) {
    // Return validation errors to the client — these are serializable
    return { success: false, error: parsed.error.errors[0].message };
  }

  // 3. Perform the mutation — direct DB call, never exposed to browser
  await updateProduct(productId, parsed.data);

  // 4. Revalidate — without this, the RSC tree shows stale data
  // revalidatePath tells Next.js to re-render this route's Server Components
  revalidatePath(`/products/${productId}`);

  // Also revalidate the product listing page
  revalidatePath('/products');

  // revalidateTag invalidates any cached fetch() calls tagged 'products'
  revalidateTag('products');

  return { success: true };
}

export async function deleteProductAction(productId: string): Promise<void> {
  const session = await auth();
  if (!session?.user?.isAdmin) throw new Error('Unauthorized');

  await deleteProduct(productId);

  // After delete, redirect away from the now-nonexistent product page
  // redirect() throws internally — must be outside try/catch
  revalidatePath('/products');
  redirect('/products');
}

// ----------------------------------------------------------------

// components/EditProductForm.tsx — Client Component that calls Server Actions
'use client';

import { useState, useTransition } from 'react';
import { updateProductAction } from '@/lib/actions/product-actions';

interface EditProductFormProps {
  productId: string;
  initialName: string;
  initialPrice: number;
  initialDescription: string;
}

export function EditProductForm({
  productId,
  initialName,
  initialPrice,
  initialDescription,
}: EditProductFormProps) {
  const [errorMessage, setErrorMessage] = useState<string | null>(null);
  const [successMessage, setSuccessMessage] = useState<string | null>(null);

  // useTransition lets us mark the Server Action call as a non-urgent update
  // isPending gives us a loading state without any extra state management
  const [isPending, startTransition] = useTransition();

  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setErrorMessage(null);
    setSuccessMessage(null);

    const formData = new FormData(event.currentTarget);

    startTransition(async () => {
      // This call compiles to a POST request to the Server Action endpoint
      // The framework serializes formData and sends it
      const result = await updateProductAction(productId, formData);

      if (result.success) {
        setSuccessMessage('Product updated successfully!');
        // Next.js automatically re-fetches and re-renders the RSC tree
        // for /products/[id] because we called revalidatePath in the action
      } else {
        setErrorMessage(result.error ?? 'Something went wrong');
      }
    });
  }

  return (
    <form onSubmit={handleSubmit} aria-busy={isPending}>
      <label htmlFor="product-name">Product Name</label>
      <input
        id="product-name"
        name="name"
        defaultValue={initialName}
        disabled={isPending}
        required
      />

      <label htmlFor="product-price">Price ($)</label>
      <input
        id="product-price"
        name="price"
        type="number"
        step="0.01"
        defaultValue={initialPrice}
        disabled={isPending}
        required
      />

      <label htmlFor="product-description">Description</label>
      <textarea
        id="product-description"
        name="description"
        defaultValue={initialDescription}
        disabled={isPending}
      />

      {errorMessage && <p role="alert" style={{ color: 'red' }}>{errorMessage}</p>}
      {successMessage && <p role="status" style={{ color: 'green' }}>{successMessage}</p>}

      <button type="submit" disabled={isPending}>
        {isPending ? 'Saving...' : 'Save Changes'}
      </button>
    </form>
  );
}

// app/blog/[slug]/page.tsx
// Demonstrates: fetch caching, Suspense streaming, and zero-cost server libraries

import { Suspense } from 'react';
import { unified } from 'unified';       // ~180KB library — zero client bundle cost
import remarkParse from 'remark-parse'; // ~50KB — stays on server
import remarkHtml from 'remark-html';   // ~30KB — stays on server

interface BlogPageProps {
  params: { slug: string };
}

// Fetch with caching strategy:
// - 'force-cache': cache forever (good for static data)
// - 'no-store': never cache (good for user-specific data)
// - { next: { revalidate: 3600 } }: ISR-style, revalidate every hour
// - { next: { tags: ['blog-posts'] } }: tag for on-demand revalidation
async function getBlogPost(slug: string) {
  const response = await fetch(
    `${process.env.CMS_API_URL}/posts/${slug}`,
    {
      next: {
        revalidate: 3600, // Re-fetch at most once per hour
        tags: [`blog-post-${slug}`, 'blog-posts'], // Tag for targeted invalidation
      },
    }
  );

  if (!response.ok) return null;
  return response.json() as Promise<{ title: string; content: string; authorId: string }>;
}

// This is a SEPARATE async function so it can be Suspense-streamed independently
async function getRelatedPosts(slug: string) {
  // Simulate a slower, separate data source
  const response = await fetch(
    `${process.env.CMS_API_URL}/posts/${slug}/related`,
    { next: { revalidate: 1800, tags: ['blog-posts'] } }
  );
  return response.json() as Promise<Array<{ slug: string; title: string }>>;
}

// Server Component for related posts — loaded lazily via Suspense
async function RelatedPosts({ currentSlug }: { currentSlug: string }) {
  const relatedPosts = await getRelatedPosts(currentSlug);

  return (
    <aside>
      <h2>Related Articles</h2>
      <ul>
        {relatedPosts.map((post) => (
          <li key={post.slug}>
            <a href={`/blog/${post.slug}`}>{post.title}</a>
          </li>
        ))}
      </ul>
    </aside>
  );
}

// Main page — Server Component
export default async function BlogPage({ params }: BlogPageProps) {
  const post = await getBlogPost(params.slug);

  if (!post) notFound();

  // Process Markdown to HTML on the server — unified/remark never touches the browser
  const processedContent = await unified()
    .use(remarkParse)
    .use(remarkHtml)
    .process(post.content);

  const htmlContent = processedContent.toString();

  return (
    <main>
      <article>
        <h1>{post.title}</h1>
        {/* dangerouslySetInnerHTML is safer here because we processed trusted CMS content */}
        <div dangerouslySetInnerHTML={{ __html: htmlContent }} />
      </article>

      {/*
        RelatedPosts is wrapped in Suspense.
        Next.js streams the article content IMMEDIATELY after it resolves.
        The related posts section arrives later as a separate stream chunk.
        The browser shows the article and renders related posts when they arrive —
        no spinner on the whole page, no waterfall.
      */}
      <Suspense
        fallback={
          <aside aria-busy="true">
            <h2>Related Articles</h2>
            <p>Finding related articles...</p>
          </aside>
        }
      >
        <RelatedPosts currentSlug={params.slug} />
      </Suspense>
    </main>
  );
}

// To invalidate a specific post after a CMS update, call this from a webhook Route Handler:
// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { slug, secret } = await request.json();

  // Validate the webhook secret — never trust incoming requests blindly
  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // Invalidate just this post's cache — all other posts stay cached
  revalidateTag(`blog-post-${slug}`);

  return NextResponse.json({ revalidated: true, slug });
}