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 in next dev flows; an experimental Next.js Bundle Analyzer integrates with Turbopack and debug support for next dev --inspect was improved.
• 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, next start --inspect support, and many Turbopack improvements including Server Fast Refresh and SRI support.
• Turbopack is now the default bundler for development and production builds (used by next dev and next build). Expect faster incremental builds and improved DX for large apps.
• Cache Components (use cache) are supported in Next.js 16 but remain opt-in via cacheComponents: true in next.config.ts. Read the Caching docs before enabling—understand cache keys, serialization constraints, and effects on revalidation.
• Middleware has been renamed to Proxy: the convention is proxy.ts (or .js) at the project root (or src root). The codemod (@next/codemod) will migrate middleware to proxy automatically where possible.
• Node.js and TypeScript minimums changed for v16: Next.js 16 requires Node.js 20.9+ and TypeScript 5.x (5.1+ recommended). Verify runtime requirements before upgrading.

Action: pin Next.js and React versions during upgrades, verify the Node.js / TypeScript minimums, run the Next.js upgrade codemod (npx @next/codemod@canary upgrade latest) for large apps, and read the Next.js 16 upgrade docs for edge cases.

React runtime and security

• React Server Components (RSC) had critical vulnerabilities disclosed in late 2025 that affected the Flight protocol and Server Components payloads. The React team published patched releases in the 19.x line — upgrade React to a patched 19.x release immediately and follow React security advisories.
• 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 — prefer to set headers/cookies and let server code fetch heavy data.
• 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*"],
};

Notes: The Proxy file must export a single function (named proxy or default). Use matcher to limit where Proxy runs for performance and clarity. To migrate existing middleware, use the Next.js codemod or the upgrade guide.

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'
  // Hinting helpers are illustrative only; rely on revalidation APIs for correctness
  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, add CI vulnerability scanning, and audit any code that deserializes or evaluates Server Component input.
8. View Transitions (Chrome 147) — Chrome supports element-scoped and nested view transitions. Treat View Transitions as a client-side UX enhancement:
   • 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; for cross-browser consistency consider a dedicated animation approach.
9. Node / TypeScript requirements — Next.js 16 requires Node.js 20.9+ and TypeScript 5.x. Verify runtime compatibility before upgrading and update your CI images accordingly.

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 the Next.js codemod and read the Next.js 16 upgrade docs (includes middleware→proxy migration, Turbopack defaults, and Node/TypeScript minimums). Test the upgrade in CI and use next start --inspect when attaching debuggers in production-like environments.
• Sources: Next.js 16.2 release notes and upgrade guide (March–April 2026), proxy file convention docs, Turbopack deep-dive, and React security advisories (Dec 2025).