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 (released March 18, 2026): performance and DX improvements including much faster developer startup and server rendering. Release highlights from the Next.js team include dramatically faster Time‑to‑URL in development (~87% faster on a default app vs 16.1), 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).

• Turbopack: 16.2 includes 200+ Turbopack fixes and feature improvements. Notable items: Server Fast Refresh for server code (fine-grained server-side hot reload), Subresource Integrity (SRI) support, postcss.config.ts support (TypeScript PostCSS config), improved tree-shaking of dynamic imports, Web Worker origin fixes to support WASM/workers, LightningCSS experimental configuration 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 a transitionTypes prop to annotate client-side transitions (useful when coordinating with View Transitions APIs).

• Next.js Across Platforms (Adapter API, stable; announced March 25, 2026): Next.js 16.2/16.3 work ships a stable Adapter API and a collaboration with OpenNext and providers to emit a typed, versioned build description that adapters consume. This improves deploy-target parity across Vercel, Netlify, Cloudflare, AWS Amplify, and others. Source: Next.js Across Platforms blog (March 25, 2026).

• Middleware → Proxy: The 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. (See Notes / Upgrade guidance.)

Action: pin Next.js and React versions during upgrades, verify Node.js / TypeScript minimums in the Next.js upgrade docs, run the Next.js upgrade codemod for large apps (npx @next/codemod@canary upgrade latest), and run the middleware→proxy codemod when migrating (npx @next/codemod@canary middleware-to-proxy .). Test in CI and update CI Node images as needed. (Sources: Next.js 16.2 blog; Turbopack post; Next.js Across Platforms blog)

React runtime and security

• Critical/High RSC vulnerabilities (Dec 2025 → Jan 2026): The React team disclosed an unauthenticated remote code execution vulnerability in React Server Components in December 2025, with follow-up disclosures adding Denial of Service and Source Code Exposure variants. Patches were released and backported; upgrade immediately if you use RSC-enabled packages or frameworks that bundle them. Source: React security advisories (Dec 3 & Dec 11, 2025; updates thereafter).

• Patched versions and remediation: Ensure your package.json pins the fixed react-server-dom packages and that framework/bundler plugins that embed these packages are updated. Do not rely solely on provider mitigations; update packages and rebuild.

• Practice: treat Server Actions and Server Component endpoints like any other server endpoint — validate input, avoid deserializing untrusted payloads without careful checks, add dependency vulnerability scanning in CI, and pin runtime/compiler versions used in production builds.

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 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 the React Server DOM packages to the patched backported versions and update any framework/bundler plugins that bundle 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; updated thereafter).