Org Skills

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

Supporting material for react-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

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'

// 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() 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

'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

  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.