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

Next.js 16 notable platform changes (confirmed)

• Next.js 16.1 (Dec 18, 2025): Turbopack file-system caching for next dev is stable and enabled by default; a new experimental Next.js Bundle Analyzer integrates with Turbopack; improved debug support for next dev --inspect. See Next.js 16.1 release notes for details.
• Next.js 16.2 (Mar 18, 2026): Faster dev startup (Time-to-URL), faster server rendering (React deserialization improvements), Server Function logging in the dev terminal, Hydration Diff Indicator, and many Turbopack improvements including Server Fast Refresh and SRI support. See Next.js 16.2 release notes and the Turbopack deep-dive.
• Cache Components (use cache) and Partial Pre-Rendering (PPR) are supported in Next.js 16 — Cache Components remain opt-in via cacheComponents: true in next.config.ts. Read the Caching docs before enabling.
• Middleware has been renamed to Proxy: convention is a single proxy.ts (or .js) at the project root (or src root). Proxy runs at the network boundary and keeps the same capabilities as the old middleware, with clarified guidance about use cases and limitations.
• Turbopack continues to be the primary bundler and has received extensive performance and parity work; features like file-system caching, server fast refresh, and bundle analysis substantially improve the developer experience for large apps.

Action: pin Next.js and React versions during upgrades, read the Next.js upgrade guides for 16.1→16.2, and run the @next/codemod when migrating large apps.

React runtime and security

• React Server Components received security fixes in late 2025 — upgrade React to the patched 19.x releases as recommended by the React team. (See React security advisories published Dec 2025 for the affected Server Components vulnerabilities.)
• Server Components and Server Actions run on the server — audit any code that deserializes input, executes templates, or evaluates untrusted data. Add dependency vulnerability scanning to CI and pin runtime/compiler versions.

Caching layers (updated)

Important: Cache Components are opt-in via next.config.ts (set cacheComponents: true). The use cache directive controls compiler-level caching; arguments and closed-over values are part of the generated cache key — follow serialization constraints in the docs.

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
    layout.tsx
  dashboard/
    layout.tsx
    page.tsx
    settings/
      page.tsx

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 = String(formData.get("title"));
  const body = String(formData.get("body"));

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

Notes: Always validate and sanitize form data server-side. Server Actions are convenient but are still server-side endpoints: treat them like any other server API.

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. Proxy (formerly Middleware) for auth and routing

• Use a single proxy.ts at the project root or src root. Compose logic into modules and import into the main proxy.ts.
• Proxy runs at the network boundary and should be used for light, fast checks (header rewrites, redirects, A/B logic). Avoid slow DB queries or heavy I/O inside Proxy.
• fetch() cache options and { next: { revalidate } } do not affect code running inside Proxy.

Example: proxy.ts

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

export function proxy(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 — Cache Components + ISR with revalidation

Enable Cache Components in next.config.ts:

// next.config.ts
export default {
  cacheComponents: true,
};

Cache a data function or component with the use cache directive:

// app/lib/data.ts
export async function getProducts() {
  'use cache'
  cacheLife('hours'); // optional helper to hint lifetime
  const res = await db.query('SELECT * FROM products');
  return res;
}

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

Notes: arguments and closed-over values participate in the cache key. Follow serialization constraints when caching parameterized data.

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 or use cache when using Cache Components
• Form submission / mutation? → Server Action with "use server"
• Slow data on a page? → Wrap in <Suspense> for streaming
• Auth protection at network boundary? → proxy.ts with matcher or redirects in next.config if simple
• SEO metadata? → generateMetadata function in the page file
• Shared layout with state? → Route group with client layout
• Cache invalidation after mutation? → revalidatePath(), revalidateTag(), or updateTag() when using Cache Components

Edge cases and gotchas (updated)

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. Treat any code that deserializes or executes untrusted input as high-risk.
3. Proxy limitations — Proxy runs at the network boundary and should be fast. It cannot access Node.js-only APIs in the same way server code can at runtime; avoid slow DB calls. Also: fetch() cache options and { next: { revalidate } } do not affect code running inside Proxy.
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 — With Cache Components enabled, the use cache directive is compiler-driven and requires you to understand cache keys and serialization constraints. Use cacheComponents: true in next.config to opt in. For per-request always-fresh data, continue to use { cache: 'no-store' } or next: { revalidate: 0 }.
6. Route groups don't affect URL — (marketing)/about/page.tsx maps to /about, not /marketing/about.
7. React Server Components security (important) — Security vulnerabilities affecting React Server Components were disclosed in late 2025. Upgrade React to the patched 19.x releases, pin versions, and audit Server Actions and any code that deserializes or evaluates Server Component input.
8. View Transitions (Chrome 147) — Chrome now supports element-scoped and nested view transitions. Treat View Transitions as an enhanced client-side UX technique:
   • Implement View Transitions in client components and feature-detect (e.g., if (document.startViewTransition) { ... }).
   • Test across hydration boundaries — wrap transition-triggering code in client-only logic and avoid invoking transitions during server render.
   • Provide graceful fallbacks for non-supporting browsers or complex SSR flows; for cross-browser consistency consider a dedicated animation approach.
9. Scoped custom element registries — Scoped registries allow encapsulation of custom elements to avoid global collisions. If you use web components inside React components, prefer scoped registries and test SSR hydration behavior.

Evaluation criteria

• Server Components are the default; "use client" is pushed deep
• Data fetches are parallelized with Promise.all
• Mutations use Server Actions with server-side validation
• Slow data is wrapped in <Suspense> with appropriate fallbacks
• Proxy handles auth/routing for protected paths when appropriate
• 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 (use cache, revalidate, no-store, or tags)
• React runtime and compiler versions are pinned and patched; CI scans for known RSC vulnerabilities

Notes

• Upgrade guidance: run Next.js codemod and read the Next.js 16.1/16.2 upgrade guides for edge cases when migrating from older versions.
• Sources: Next.js 16.1 and 16.2 release notes and docs (Turbopack, Caching, Proxy) and React security advisories (Dec 2025) and Chrome developer signals for View Transitions.