Next.js Knowledge Patch (15.3 – 16.x)

Supplementary knowledge for Next.js features released after Claude's training cutoff. Covers versions 15.3 through 16.1 (April 2025 – January 2026).

Request Interception: proxy.ts

Next.js 16 replaces middleware.ts with proxy.ts . Rename the file and export a proxy function instead of middleware . Runs on Node.js runtime by default.

// proxy.ts (project root) import { NextRequest, NextResponse } from 'next/server';

export function proxy(request: NextRequest) { return NextResponse.next(); }

middleware.ts still works (Edge runtime) but is deprecated and will be removed.

15.5 note: Middleware gained stable Node.js runtime support via export const config = { runtime: 'nodejs' } before the full proxy.ts transition.

Caching: "use cache" and Cache Components

Next.js 16 introduces an opt-in caching model. All dynamic code runs at request time by default — caching is no longer implicit. Enable with:

// next.config.ts const nextConfig: NextConfig = { cacheComponents: true, };

Apply the "use cache" directive to cache pages, components, or functions. The compiler generates cache keys automatically:

"use cache";

export default async function CachedPage() { const data = await fetchData(); return <div>{data}</div>; }

Replaces experimental.ppr and experimental.dynamicIO . Completes the Partial Prerendering story — static shells with dynamic holes via Suspense, fully opt-in.

For detailed caching API patterns and code examples, see references/caching.md .

Caching API Quick Reference

API Context Semantics Use Case

updateTag(tag)

Server Actions only Read-your-writes (immediate) Forms, user settings

refresh()

Server Actions only Refreshes uncached data only Notification counts, live metrics

revalidateTag(tag, profile)

Any server context SWR (eventual consistency) Static content invalidation

Breaking: revalidateTag() now requires a cacheLife profile as 2nd argument ('max' , 'hours' , 'days' , or { expire: N } ).

Navigation Hooks (15.3+)

onNavigate — prop on <Link> . Fires during SPA navigations only (not all clicks). Call e.preventDefault() to cancel.

<Link href="/dashboard" onNavigate={(e) => { if (hasUnsavedChanges) e.preventDefault(); }}> Dashboard </Link>

useLinkStatus — hook from next/navigation . Returns { pending: boolean } . Must be used inside a <Link> descendant. Modeled after React's useFormStatus .

'use client'; import { useLinkStatus } from 'next/navigation';

function LinkSpinner() { const { pending } = useLinkStatus(); return pending ? <Spinner /> : null; }

// <Link href="/page"><LinkSpinner /> Go</Link>

TypeScript (15.5+)

Route Props Type Helpers

Auto-generated PageProps , LayoutProps , RouteContext types — globally available, no imports needed:

// app/blog/[slug]/page.tsx — no manual typing needed export default async function Page({ params }: PageProps) { const { slug } = await params; return <article>{slug}</article>; }

Typed Routes

Compile-time route validation — moved from experimental to stable:

// next.config.ts const nextConfig: NextConfig = { typedRoutes: true };

Invalid <Link href> paths cause TypeScript errors. Works with both Webpack and Turbopack.

next typegen

Standalone type generation for CI validation without running dev/build:

next typegen && tsc --noEmit

File Conventions

File Since Purpose

proxy.ts

16.0 Request interception (replaces middleware.ts )

instrumentation-client.js|ts

15.3 Client-side monitoring/analytics — runs before app code

default.js in parallel routes 16.0 Required for all slots or build fails

Configuration Reference

Config Purpose Since

cacheComponents: true

Enable "use cache"

• PPR 16.0

reactCompiler: true

React Compiler (was experimental ) 16.0

typedRoutes: true

Typed routes (was experimental ) 15.5

turbopack: { ... }

Turbopack config (was experimental.turbo ) 15.3

Turbopack is default bundler Opt out with --webpack flag 16.0

Removed config: experimental.ppr , experimental.dynamicIO , serverRuntimeConfig , publicRuntimeConfig (use .env files), devIndicators options.

Tooling Changes

• next lint removed (16.0) — use ESLint CLI or Biome directly. Codemod: npx @next/codemod@latest next-lint-to-eslint

• next typegen (15.5) — standalone type generation for CI

• Turbopack FS caching — stable and on by default for next dev in 16.1

React 19.2 (via App Router, 16.0+)

These are React-level APIs available through the App Router's React Canary channel. Refer to the React 19.2 docs for full usage details.

• <ViewTransition> — animate elements during transitions

• useEffectEvent() — extract non-reactive logic from Effects into stable functions

• <Activity> — hide UI (display: none ) while preserving state and cleaning up Effects

Breaking Changes (16.0)

For full migration details with code examples, see references/migration-guide.md .

• Node.js 20.9+, TypeScript 5.1+, Chrome/Edge/Firefox 111+, Safari 16.4+

• Async APIs enforced: await params , await searchParams , await cookies() , await headers() — sync access now errors

• Parallel routes: all slots require explicit default.js or build fails

• Removed: AMP, next lint , legacyBehavior on Link, serverRuntimeConfig /publicRuntimeConfig

• Image defaults: images.qualities → [75] , minimumCacheTTL → 14400s, localPatterns required for query strings, dangerouslyAllowLocalIP blocks local IPs

Additional Resources

Reference Files

• references/caching.md — Detailed "use cache" , updateTag() , refresh() , revalidateTag() patterns with code examples

• references/migration-guide.md — Complete Next.js 16 breaking changes, removals, and migration steps