Rule: Default to Server Components. Add "use client" only when you need interactivity, effects, or browser APIs. Push the "use client" boundary as deep into the component tree as possible.

Caching layers

Workflow

1. Define the route structure

app/
  layout.tsx          # root layout (Server Component)
  page.tsx            # home page
  loading.tsx         # loading UI for streaming
  error.tsx           # error boundary
  not-found.tsx       # 404 page
  (marketing)/
    page.tsx          # marketing home with different layout
    layout.tsx        # marketing layout
  dashboard/
    layout.tsx        # dashboard layout with sidebar
    page.tsx          # dashboard home
    settings/
      page.tsx        # settings page

2. Server Actions for mutations

"use server";

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";

export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;
  const body = formData.get("body") as string;

  await db.post.create({ data: { title, body } });
  revalidatePath("/posts");
  redirect("/posts");
}

3. Streaming with Suspense

import { Suspense } from "react";

async function SlowData() {
  const data = await fetchExpensiveData();
  return <DataDisplay data={data} />;
}

export default function Page() {
  return (
    <main>
      <h1>Dashboard</h1>
      <Suspense fallback={<TableSkeleton />}>
        <SlowData />
      </Suspense>
    </main>
  );
}

4. Middleware for auth and routing

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  const token = request.cookies.get("session")?.value;

  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"],
};

5. Metadata API for SEO

import type { Metadata } from "next";

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await getPost(params.slug);
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [{ url: post.coverImage }],
    },
  };
}

6. Parallel data fetching

export default async function DashboardPage() {
  const [stats, recentPosts, notifications] = await Promise.all([
    getStats(),
    getRecentPosts(),
    getNotifications(),
  ]);

  return (
    <div>
      <StatsPanel stats={stats} />
      <PostList posts={recentPosts} />
      <NotificationFeed notifications={notifications} />
    </div>
  );
}

7. Error boundary hierarchy

"use client";

export default function ErrorBoundary({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div className="flex flex-col items-center gap-space-md p-space-xl">
      <h2 className="text-xl font-semibold">Something went wrong</h2>
      <p className="text-text-secondary">{error.message}</p>
      <button onClick={reset} className="rounded-sm bg-accent px-space-md py-space-sm text-surface">
        Try again
      </button>
    </div>
  );
}

Examples

Example 1 — ISR with revalidation

async function getProducts() {
  const res = await fetch("https://api.example.com/products", {
    next: { revalidate: 3600 },
  });
  return res.json();
}

export default async function ProductsPage() {
  const products = await getProducts();
  return <ProductGrid products={products} />;
}

Example 2 — Form with Server Action

import { createPost } from "./actions";

export default function NewPostForm() {
  return (
    <form action={createPost}>
      <input name="title" required placeholder="Post title" />
      <textarea name="body" required placeholder="Write something..." />
      <button type="submit">Publish</button>
    </form>
  );
}

Example 3 — Route group with separate layout

app/
  (auth)/
    login/page.tsx
    register/page.tsx
    layout.tsx          # centered card layout for auth pages
  (app)/
    dashboard/page.tsx
    settings/page.tsx
    layout.tsx          # sidebar layout for app pages

Decision tree

• Need interactivity (state, effects, browser APIs)? → "use client"
• Fetching data for display? → Server Component with direct fetch
• Form submission / mutation? → Server Action with "use server"
• Slow data on a page? → Wrap in <Suspense> for streaming
• Auth protection? → Middleware with path matcher
• SEO metadata? → generateMetadata function in the page file
• Shared layout with state? → Route group with client layout
• Cache invalidation after mutation? → revalidatePath() or revalidateTag()

Edge cases and gotchas

1. "use client" boundary — "use client" goes at the top of the file, before imports. It marks that file and all its imports as client components. Push this boundary as deep as possible.
2. Server Action security — Server Actions are POST endpoints. Always validate input server-side. Never trust formData without sanitization.
3. Middleware limitations — Middleware runs at the edge. It cannot access Node.js APIs (fs, crypto, etc.) or make database connections directly.
4. Hydration mismatch — Server and client must render the same initial HTML. Avoid Date.now(), Math.random(), or browser-only checks in shared render paths.
5. Caching surprises — fetch() in Server Components is cached by default. Use { cache: "no-store" } for data that must always be fresh.
6. Route groups don't affect URL — (marketing)/about/page.tsx maps to /about, not /marketing/about.

Evaluation criteria

• Server Components are the default; "use client" is pushed as deep as possible
• Data fetches are parallelized with Promise.all (no waterfalls)
• Mutations use Server Actions with server-side validation
• Slow data is wrapped in <Suspense> with appropriate fallbacks
• Middleware handles auth/routing for protected paths
• generateMetadata provides title, description, and OpenGraph for every page
• Error boundaries (error.tsx) exist at layout and page levels
• Loading states (loading.tsx) provide meaningful skeleton UI
• Environment secrets are in .env.local, never committed
• Caching strategy is intentional (revalidate, no-store, or tags)