# Next.js 16 — what changed and how to use it

> 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-performance` and `react-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'`

```ts
// next.config.ts
import type { NextConfig } from 'next';
const nextConfig: NextConfig = { cacheComponents: true, reactCompiler: true };
export default nextConfig;
```

```tsx
// 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()` and `searchParams` cannot 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`, `generateStaticParams` included, all must be async). A cached layout does not cache the `children` slot — slots pass through.
- Set `cacheLife` explicitly at every call site; the `default` profile (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_cache` and implicit `fetch` caching: "This API has been replaced by `use cache` in Next.js 16." Keep `unstable_cache` only for data that must survive deploys and you cannot move yet.

## 3. Invalidation APIs

```ts
'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

```tsx
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`

```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

1. Run the codemod; fix sync `params`/`cookies` leftovers.
2. Rename `middleware.ts` → `proxy.ts`, export `proxy`.
3. Turn on `cacheComponents: true`; the build now reports every dynamic read that was silently cached before — wrap the cacheable ones in `'use cache'` with `cacheLife`, replace `unstable_cache`, replace `fetch(..., { next: { revalidate } })` with `'use cache'` + `cacheLife`.
4. Replace `revalidateTag(tag)` with `updateTag(tag)` in Server Actions and `revalidateTag(tag, 'max')` elsewhere.
5. Add `default.js` to every parallel route slot (builds fail without it).
6. Enable `reactCompiler: true`; remove hand-written memo that the lint rule proves redundant.
7. 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 with `cookies()`/`headers()` mocked (`vi.mock('next/headers')`); `'use cache'` functions can be called directly (the directive is a no-op outside the Next.js runtime). See `react-testing`.
