/nextjs

name: nextjs
description: Use when building Next.js applications with the App Router. Covers server and client component boundaries, data fetching and caching, server actions, streaming, and rendering strategy.
metadata:
  category: frontend
  version: 1.0.0
  tags: [nextjs, react, ssr, rsc, caching]

Next.js

Purpose

Build Next.js applications where the server/client boundary is drawn deliberately, caching is understood rather than fought, and the rendering strategy matches what the page actually needs.

When to Use

• Building or reviewing a Next.js App Router application.
• Deciding what renders on the server versus the client.
• Debugging stale data or unexpectedly dynamic rendering.
• Implementing mutations with server actions.

Capabilities

• Server and client component composition.
• Data fetching, caching, and revalidation (time-based and tag-based).
• Server actions for mutations, with validation and revalidation.
• Streaming with Suspense and loading boundaries.
• Rendering strategy: static, dynamic, ISR, partial prerendering.

Inputs

• The page, its data dependencies, and how fresh each must be.
• Which parts are genuinely interactive.
• Auth model and whether the page is personalized.

Outputs

• A component tree with `"use client"` pushed as far down as possible.
• Explicit cache and revalidation settings per fetch.
• Mutations that revalidate exactly what they changed.

Workflow

1. **Default to server components** — They ship no JavaScript. Add `"use client"` only where you need state, effects, or browser APIs — and add it to the leaf, not the page. 2. **Fetch where you render** — Fetch data in the component that needs it. Requests are deduplicated within a render pass; prop-drilling data down from the page is unnecessary. 3. **Set the cache explicitly** — Every `fetch` gets a deliberate `cache` or `next.revalidate`. Relying on the framework default is how you ship stale prices. 4. **Stream the slow parts** — Wrap slow sections in `<Suspense>` with a meaningful fallback so the shell renders immediately. 5. **Mutate with server actions** — Validate the input (it is a public endpoint, whatever it looks like), perform the write, then `revalidateTag` or `revalidatePath` for exactly what changed.

Best Practices

• `"use client"` at the top of a page turns the entire subtree into client components. Push it to the interactive leaf — the button, not the layout.
• A server action is an HTTP endpoint. It has no implicit authorization. Check the session inside it, every time.
• Reading `cookies()`, `headers()`, or `searchParams` opts the route into dynamic rendering. If a page unexpectedly stopped being static, this is why.
• Tag-based revalidation (`revalidateTag`) is far more precise than path-based. Tag by entity, invalidate on write.
• Never put a secret in a component that could be a client component. If it is imported by anything with `"use client"`, it ships to the browser.
• Use `loading.tsx` and `error.tsx` at every route segment. The defaults are a blank screen and a crash.

Examples

**Server component with explicit caching, streaming a slow section:**

// app/orders/[id]/page.tsx  — a server component by default
export default async function OrderPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;

  const order = await fetch(`${API}/orders/${id}`, {
    next: { tags: [`order:${id}`], revalidate: 60 },
  }).then((r) => r.json());

  return (
    <main>
      <OrderHeader order={order} />

      {/* Shell renders immediately; this streams in when ready. */}
      <Suspense fallback={<TimelineSkeleton />}>
        <OrderTimeline orderId={id} />
      </Suspense>

      {/* Only this leaf ships JavaScript. */}
      <RefundButton orderId={id} />
    </main>
  );
}

**Server action: authorize, validate, mutate, revalidate:**

"use server";

export async function refundOrder(orderId: string, formData: FormData) {
  const session = await auth();
  if (!session) throw new Error("Unauthorized");     // a server action is a public endpoint

  const parsed = RefundSchema.safeParse({
    amountCents: formData.get("amountCents"),
  });
  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors };
  }

  await orders.refund(orderId, parsed.data.amountCents, session.user.id);
  revalidateTag(`order:${orderId}`);                  // precise invalidation
  return { ok: true };
}

Notes

• Next.js caching changed materially between versions 14 and 15 — `fetch` is no longer cached by default in 15. Never rely on remembered defaults; set them.
• Partial prerendering serves a static shell with dynamic holes streamed in. It is the right default for pages that are mostly static with a personalized corner.
• A client component can render server components passed as `children`. That composition pattern lets you keep an interactive wrapper without dragging the whole subtree to the client.