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.2 (published March 18, 2026): performance and DX improvements including significantly faster developer startup and server rendering. Highlights from the Next.js team include dramatically faster Time‑to‑URL in development, faster server rendering (25–60% faster HTML render depending on RSC payload size), a redesigned default error page, Server Function logging in the dev terminal, a Hydration Diff Indicator in the overlay, and next start --inspect to attach a Node.js debugger to a running server. Source: Next.js 16.2 blog (March 18, 2026).

  • Time-to-URL / dev startup: the release notes report large improvements (top-line measurements show up to ~400% faster next dev startup in some scenarios; the default-app measurement in the post reports ~87% faster startup vs 16.1). Expect measurable gains on both small and large apps—benchmark your codebase when upgrading.

  • Server rendering improvements: Next.js 16.2 includes changes that reduce RSC payload deserialization overhead (a two-step parse + walk approach contributed to React), delivering roughly 25–60% faster HTML render times in real-world workloads.

• Turbopack (16.2 deep-dive): 200+ fixes and feature improvements landed in Turbopack for 16.2. Notable items: Server Fast Refresh (fine-grained server hot reload), Subresource Integrity (SRI) support, postcss.config.ts (TypeScript PostCSS config) support, improved tree-shaking for dynamic imports, Web Worker origin fixes (better WASM/worker support), LightningCSS experimental hooks, and log filtering. Turbopack remains the recommended default bundler for most Next.js workflows. Source: Turbopack deep-dive (Next.js blog, March 18, 2026).

• transitionTypes prop for next/link: the Link component accepts transitionTypes to annotate client-side transitions (useful when coordinating with View Transitions APIs).

• Next.js Across Platforms (Adapter API, stable; published March 25, 2026): the release includes a stable Adapter API and collaboration with OpenNext and major providers to produce a typed, versioned build description that adapters consume. This improves deploy-target parity across Vercel, Netlify, Cloudflare, AWS, and others. Source: Next.js Across Platforms blog (March 25, 2026).

• Middleware → Proxy: the previous middleware convention is replaced by Proxy (exported as proxy.ts / proxy.js) as the network-boundary entry point. Use matcher to scope Proxy execution. Run the provided migration codemods when upgrading. Keep Proxy logic small and fast; offload heavy I/O to server code.

Actionable checklist when upgrading to v16.x:

• Read the Next.js 16.2 release notes and the Turbopack deep-dive for Turbopack behavior changes.
• Run Next.js codemods for large upgrades: npx @next/codemod@canary upgrade latest.
• Migrate middleware to Proxy with the codemod: npx @next/codemod@canary middleware-to-proxy . and validate matcher scopes.
• Benchmark your dev startup and server render times pre/post-upgrade.
• Verify Node.js and TypeScript minimums in the Next.js docs before upgrading CI images.

Sources: Next.js 16.2 blog (Mar 18, 2026), Turbopack deep-dive (Mar 18, 2026), Next.js Across Platforms blog (Mar 25, 2026), Next.js docs (Proxy/Caching guidance).

React runtime and security

• December 2025 — January 2026 RSC advisories: the React team disclosed a critical unauthenticated remote code execution vulnerability affecting React Server Components in early December 2025 (CVE-2025-55182) with follow-up disclosures adding Denial of Service and Source Code Exposure variants (December 11, 2025 and later updates). These advisories were patched and subsequently backported. Source: React blog (Dec 3 & Dec 11, 2025; updates Jan 26, 2026).

• Patched packages and remediation (high level): React published fixes and backports for the react-server-dom-* packages. The advisories recommend upgrading the affected react-server-dom packages to the patched backported versions (see the React blog for the exact fixed package versions for your release series). Do not rely on provider mitigations alone — upgrade packages, rebuild, and redeploy.

• Practical guidance:

  • Audit whether your app (or any dependency) uses React Server Components or Server Functions. If yes, treat these packages as high-priority for patching.
  • Upgrade react-server-dom-* to the fixed backported versions as listed by the React advisory (and update react/react-dom per your framework's guidance). Rebuild and redeploy.
  • Update Next.js to the recommended patch for your release line; follow the Next.js blog/upgrade docs because framework integrations may bundle or pin these packages.
  • Add dependency vulnerability scanning to CI and pin critical runtime/compiler/tooling versions in your lockfile and CI images.
  • Validate any temporary hosting-provider mitigations with your provider, but do not substitute them for package upgrades.

Caching layers (updated)

Important: Cache Components remain 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 handler function (named proxy or as a default export). Use matcher to limit where Proxy runs for performance and clarity. To migrate existing middleware, use the Next.js codemods and migration docs (example codemod: npx @next/codemod@canary middleware-to-proxy .).

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 and early 2026. The React team published fixes and backports; upgrade react-server-dom packages to the patched backported versions listed in the React advisories, update framework/bundler plugins that embed these packages, pin versions, add CI vulnerability scanning, and audit code that deserializes 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 — Verify runtime compatibility before upgrading. Consult the Next.js v16 upgrade docs for the exact Node/TypeScript minimums for your minor version.

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). Example codemods: npx @next/codemod@canary upgrade latest (upgrade) and npx @next/codemod@canary middleware-to-proxy . (middleware→proxy rename). Test the upgrade in CI and use next start --inspect when attaching debuggers in production-like environments.
• Sources: Next.js 16.2 release notes (March 18, 2026), Turbopack deep-dive (March 18, 2026), Next.js Across Platforms / Adapter API (March 25, 2026), Next.js docs (Proxy migration), React security advisories (Dec 3 & Dec 11, 2025; updates Jan 26, 2026).