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 ~400% faster next dev Time‑to‑URL, up to ~50% faster server rendering in real-world workloads (React contribution for faster RSC deserialization), Server Function logging in the dev terminal, a Hydration Diff Indicator in the overlay, next start --inspect support, and many Turbopack fixes and features. (See: Next.js 16.2 release notes)
• Next.js Across Platforms (March 25, 2026): Next.js 16.2 introduced a stable Adapter API (collaboration with OpenNext, Netlify, Cloudflare, AWS Amplify, Google Cloud). The Adapter API, a shared test suite, and verified adapters aim to make Next.js deployable at full fidelity across multiple providers. (See: Next.js Across Platforms)
• Turbopack: Turbopack is stable and used by default for next dev and next build in Next.js 16.x (improves incremental builds and dev startup). Next.js 16.2 focused on SRI support, Server Fast Refresh, tree-shaking improvements, and 200+ bug fixes. If you must temporarily use webpack, Next.js continues to provide flags to select a bundler. (See: Turbopack deep-dive)
• Middleware → Proxy: The middleware convention has been replaced with proxy.ts (or .js). Next.js provides a codemod to migrate existing middleware to proxy (npx @next/codemod@canary middleware-to-proxy). Proxy behaves similarly to the old middleware but is the supported network-bound entry point and should be used for fast checks and header/redirect logic.
• React & RSC: Next.js 16's rendering improvements include a React-side fix that makes Server Components payload deserialization substantially faster (contribution to React’s parsing approach). For security: React Server Components had critical vulnerabilities disclosed in late 2025 — upgrade React to a patched 19.x release and follow React security advisories.
• Upgrade guidance: run the Next.js codemod for large apps (npx @next/codemod@canary upgrade latest) or follow the official upgrade guide; test in CI, pin versions, and update CI Node images as needed.

Action: pin Next.js and React versions during upgrades, verify the Node.js / TypeScript minimums in the Next.js upgrade docs, run the Next.js upgrade codemod 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, run the 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. 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 — 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). 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), Next.js Across Platforms (March 25, 2026), Turbopack deep-dive, React security advisories (Dec 2025).