Verified 2026-09 against https://nextjs.org/blog/next-16 and https://nextjs.org/docs (16.3.x). Shared by
react-development,react-architecture,react-performanceandreact-testing; this is the only Next.js-specific reference in the catalog.
1. Version facts
| Item | Next.js 16 |
|---|---|
| Node / TypeScript | Node 20.9+ (use 22 LTS), TypeScript 5.1+ |
| Bundler | Turbopack default for dev and build; next build --webpack to opt out |
| React | 19.2 (App Router uses the canary channel: <ViewTransition>, useEffectEvent, <Activity>) |
| Caching model | Cache Components (cacheComponents: true) — everything dynamic by default, caching opt-in with 'use cache' |
| Request interception | proxy.ts (Node runtime) replaces middleware.ts (deprecated) |
| Compiler | reactCompiler: true (stable, not on by default) |
| Removed | AMP, next lint, experimental.ppr/dynamicIO (now cacheComponents), sync params/searchParams/cookies()/headers() |
| Deprecated | revalidateTag(tag) single argument, next/legacy/image, images.domains |
Upgrade: npx @next/codemod@canary upgrade latest.
2. Cache Components and 'use cache'
// next.config.ts
import type { NextConfig } from 'next';
const nextConfig: NextConfig = { cacheComponents: true, reactCompiler: true };
export default nextConfig;
// features/catalog/api/products.ts
import { cacheLife, cacheTag } from 'next/cache';
export async function getProducts(category: string) {
'use cache';
cacheLife('hours'); // built-in profiles: default, seconds, minutes, hours, days, weeks, max
cacheTag('products', `products-${category}`);
const res = await fetch(`https://api.example.com/products?category=${encodeURIComponent(category)}`);
return res.json() as Promise<Product[]>;
}
Rules that bite:
- Cached functions and components must be
async; arguments and return values must be serialisable (React Server serialisation for arguments). cookies(),headers()andsearchParamscannot be read inside a cached scope — read them outside and pass values in as arguments. Build-time hang ("Filling a cache during prerender timed out") means a runtime promise leaked into a cached function.'use cache'at the top of a file caches every export (generateMetadata,generateStaticParamsincluded, all must be async). A cached layout does not cache thechildrenslot — slots pass through.- Set
cacheLifeexplicitly at every call site; thedefaultprofile (stale 5 min, revalidate 15 min, never expires) is otherwise implicit. - Partial Prerendering is now the default mental model: static shell served from the CDN, dynamic holes streamed via
<Suspense>. There is no page-level static/dynamic switch any more. - The default handler is an in-memory LRU: entries persist on a long-running Node server but usually not across serverless invocations, and never across deploys (the build id is part of the key).
'use cache: remote'plugs in a platform cache (Redis/KV);'use cache: private'is the rare escape hatch for code that must read request data inside the cached scope. https://nextjs.org/docs/app/api-reference/directives/use-cache unstable_cacheand implicitfetchcaching: "This API has been replaced byuse cachein Next.js 16." Keepunstable_cacheonly for data that must survive deploys and you cannot move yet.
3. Invalidation APIs
'use server';
import { revalidateTag, updateTag, refresh } from 'next/cache';
export async function updateProduct(id: string, data: ProductInput) {
await db.products.update(id, data);
updateTag('products'); // Server Actions only: expire AND re-read in the same request (read-your-writes)
}
export async function nightlySync() {
revalidateTag('products', 'max'); // stale-while-revalidate; second argument = cacheLife profile or { expire }
}
export async function markRead(id: string) {
await db.notifications.markRead(id);
refresh(); // Server Actions only: refresh uncached data, leave caches alone
}
revalidateTag('products') without a profile is deprecated. revalidatePath is unchanged.
4. Async request APIs
export default async function Page({ params, searchParams }: {
params: Promise<{ id: string }>;
searchParams: Promise<Record<string, string | string[] | undefined>>;
}) {
const { id } = await params;
const { tab } = await searchParams;
const cookieStore = await cookies();
// …
}
Sync access is removed in 16; the codemod rewrites most call sites.
5. proxy.ts
// proxy.ts (project root or src/)
import { NextResponse, type NextRequest } from 'next/server';
export default function proxy(request: NextRequest) {
if (!request.cookies.get('session') && request.nextUrl.pathname.startsWith('/app')) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
export const config = { matcher: ['/app/:path*'] };
Runs on Node; do the real authorisation in the Server Component or Server Action as well — the proxy is a fast pre-check, not the security boundary.
6. next/image defaults that changed
The priority prop is deprecated in favour of preload (and the docs prefer fetchPriority="high" or loading="eager" for the LCP image); images.minimumCacheTTL 60 s → 4 h; images.qualities [75] (the quality prop snaps to the nearest configured value); imageSizes no longer includes 16; remote sources need images.remotePatterns; local src with a query string needs images.localPatterns; max 3 redirects; local-IP optimisation blocked unless dangerouslyAllowLocalIP.
7. Migration from 15 in order
- Run the codemod; fix sync
params/cookiesleftovers. - Rename
middleware.ts→proxy.ts, exportproxy. - Turn on
cacheComponents: true; the build now reports every dynamic read that was silently cached before — wrap the cacheable ones in'use cache'withcacheLife, replaceunstable_cache, replacefetch(..., { next: { revalidate } })with'use cache'+cacheLife. - Replace
revalidateTag(tag)withupdateTag(tag)in Server Actions andrevalidateTag(tag, 'max')elsewhere. - Add
default.jsto every parallel route slot (builds fail without it). - Enable
reactCompiler: true; remove hand-written memo that the lint rule proves redundant. - Testing: Server Components are plain async functions —
await Page({ params: Promise.resolve({ id: '1' }) })and render the result with Testing Library; Server Actions are plain async functions withcookies()/headers()mocked (vi.mock('next/headers'));'use cache'functions can be called directly (the directive is a no-op outside the Next.js runtime). Seereact-testing.