Triggers
- nextjs
- next.js
- next
- app router
- server component
- ssr
- ssg
- vercel
- next 16
- pages router
- middleware
- next api
Links
Upgrade
# Automated upgrade
npx @next/codemod@canary upgrade latest
# Manual upgrade
npm install next@latest react@latest react-dom@latest
# New project
npx create-next-app@latest
Codemod covers (high-level): moves Turbopack config, migrates next lint → ESLint CLI, migrates middleware → proxy, removes some unstable_ prefixes, removes route-level experimental_ppr.
TypeScript: also upgrade @types/react and @types/react-dom.
What’s New (v16)
- Cache Components: opt-in caching via the
"use cache" directive; evolves/absorbs PPR.
- Next.js DevTools MCP: Model Context Protocol integration for AI-assisted debugging.
proxy.ts: clearer network boundary; middleware.ts deprecated for most use.- Better logs/metrics: more detailed
next dev and build timing output.
Performance / DX
- Turbopack: stable; default bundler (opt out with
next dev --webpack, next build --webpack).
- If you have a custom
webpack config, next build may fail (to prevent misconfiguration). Fix by migrating config, using next build --webpack, or using Turbopack and removing/ignoring the webpack config.
- Turbopack config moved:
experimental.turbopack → top-level turbopack in next.config.*.
- Turbopack migration gotchas:
- Sass imports: remove the Webpack-only
~ prefix (e.g. @import 'bootstrap/...';).
- Browser bundles must not import Node built-ins (e.g.
fs). If unavoidable, use turbopack.resolveAlias as a stopgap.
- Turbopack filesystem cache (dev, beta):
experimental.turbopackFileSystemCacheForDev: true.
- React Compiler support: stable opt-in via
reactCompiler: true (expect higher build/compile cost).
- Build Adapters API: alpha (custom build adapters).
- Routing/prefetching rewrite: layout deduplication + incremental prefetching.
Caching APIs (key signatures)
revalidateTag(tag, profile) now requires a cacheLife profile (or { expire }) for SWR behavior.updateTag(tag) (Server Actions only): read-your-writes semantics.refresh() (Server Actions only): refresh uncached data; does not mutate cache.cacheLife and cacheTag are stable (no unstable_ prefix).
Requirements (v16)
- Node.js: 20.9+ (Node 18 not supported)
- TypeScript: 5.1+
- Browsers: Chrome/Edge/Firefox 111+, Safari 16.4+
Breaking / Behavior Changes (high-impact)
- Async Request APIs: sync access removed. Use
await params, await searchParams, await cookies(), await headers(), await draftMode().
- Tip (TypeScript):
npx next typegen can generate helpers like PageProps, LayoutProps, RouteContext to migrate params/searchParams types safely.
- Metadata images:
opengraph-image, twitter-image, icon, apple-icon now receive params (and id) as Promises in the image function.
- Sitemaps:
sitemap({ id }) now receives id as a Promise when using generateSitemaps.
- Parallel routes: slots require explicit
default.js.
next/image defaults changed (cache TTL, sizes/qualities); local src with query strings requires images.localPatterns.
Other notable behavior changes:
next dev and next build use separate output dirs (next dev → .next/dev) and a lockfile prevents concurrent instances.- Scroll behavior: Next.js no longer overrides global
scroll-behavior: smooth during navigations; add data-scroll-behavior="smooth" on <html> to restore the previous override behavior.
- ESLint:
@next/eslint-plugin-next defaults to ESLint Flat Config; legacy .eslintrc projects may need migration.
Removed / Deprecated (high-level)
- Removed: AMP support;
next lint (use ESLint/Biome directly); eslint option in next.config.*; serverRuntimeConfig/publicRuntimeConfig (use env vars); experimental.ppr + route-level experimental_ppr; unstable_rootParams.
- Deprecated:
middleware.ts filename (prefer proxy.ts); next/legacy/image; images.domains (prefer images.remotePatterns); revalidateTag(tag) single-arg form.
proxy.ts note: proxy runs on nodejs only; Edge runtime is not supported in proxy. Keep middleware.ts if you must stay on Edge.- Config rename example:
skipMiddlewareUrlNormalize → skipProxyUrlNormalize.
Verify
- The Next.js version targeted is named explicitly (e.g., 'Next 16') and the change does not silently rely on features from a different major
next build (or the project's equivalent) was run and completed without errors; the build output / route table is captured- Server components vs client components were chosen deliberately for each new file; the choice is justified in a comment or PR note
next dev was loaded and the touched routes were rendered without console warnings or hydration mismatches- Caching/revalidation behavior (fetch options,
revalidate, dynamic) is set explicitly on new data fetches, not left to defaults
- Type-check and lint (
tsc --noEmit, next lint) pass on the changed files; output is in the transcript
1---2name: nextjs16-skills3description: Key facts and links for Next.js 16. Use for planning, writing, and troubleshooting Next.js 16 changes.4---567## Triggers89- nextjs10- next.js11- next12- app router13- server component14- ssr15- ssg16- vercel17- next 1618- pages router19- middleware20- next api2122## Links2324- Docs: https://nextjs.org/docs25- Upgrade guide (v16): https://nextjs.org/docs/app/guides/upgrading/version-1626- Release notes/blog: https://nextjs.org/blog/next-162728## Upgrade2930```sh31# Automated upgrade32npx @next/codemod@canary upgrade latest3334# Manual upgrade35npm install next@latest react@latest react-dom@latest3637# New project38npx create-next-app@latest39```4041Codemod covers (high-level): moves Turbopack config, migrates `next lint` → ESLint CLI, migrates `middleware` → `proxy`, removes some `unstable_` prefixes, removes route-level `experimental_ppr`.4243TypeScript: also upgrade `@types/react` and `@types/react-dom`.4445## What’s New (v16)4647- Cache Components: opt-in caching via the `"use cache"` directive; evolves/absorbs PPR.48- Next.js DevTools MCP: Model Context Protocol integration for AI-assisted debugging.49- `proxy.ts`: clearer network boundary; `middleware.ts` deprecated for most use.50- Better logs/metrics: more detailed `next dev` and build timing output.5152## Performance / DX5354- Turbopack: stable; default bundler (opt out with `next dev --webpack`, `next build --webpack`).55- If you have a custom `webpack` config, `next build` may fail (to prevent misconfiguration). Fix by migrating config, using `next build --webpack`, or using Turbopack and removing/ignoring the webpack config.56- Turbopack config moved: `experimental.turbopack` → top-level `turbopack` in `next.config.*`.57- Turbopack migration gotchas:58 - Sass imports: remove the Webpack-only `~` prefix (e.g. `@import 'bootstrap/...';`).59 - Browser bundles must not import Node built-ins (e.g. `fs`). If unavoidable, use `turbopack.resolveAlias` as a stopgap.60- Turbopack filesystem cache (dev, beta): `experimental.turbopackFileSystemCacheForDev: true`.61- React Compiler support: stable opt-in via `reactCompiler: true` (expect higher build/compile cost).62- Build Adapters API: alpha (custom build adapters).63- Routing/prefetching rewrite: layout deduplication + incremental prefetching.6465## Caching APIs (key signatures)6667- `revalidateTag(tag, profile)` now requires a cacheLife profile (or `{ expire }`) for SWR behavior.68- `updateTag(tag)` (Server Actions only): read-your-writes semantics.69- `refresh()` (Server Actions only): refresh uncached data; does not mutate cache.70- `cacheLife` and `cacheTag` are stable (no `unstable_` prefix).7172## Requirements (v16)7374- Node.js: 20.9+ (Node 18 not supported)75- TypeScript: 5.1+76- Browsers: Chrome/Edge/Firefox 111+, Safari 16.4+7778## Breaking / Behavior Changes (high-impact)7980- Async Request APIs: sync access removed. Use `await params`, `await searchParams`, `await cookies()`, `await headers()`, `await draftMode()`.81- Tip (TypeScript): `npx next typegen` can generate helpers like `PageProps`, `LayoutProps`, `RouteContext` to migrate `params/searchParams` types safely.82- Metadata images: `opengraph-image`, `twitter-image`, `icon`, `apple-icon` now receive `params` (and `id`) as Promises in the image function.83- Sitemaps: `sitemap({ id })` now receives `id` as a Promise when using `generateSitemaps`.84- Parallel routes: slots require explicit `default.js`.85- `next/image` defaults changed (cache TTL, sizes/qualities); local `src` with query strings requires `images.localPatterns`.8687Other notable behavior changes:8889- `next dev` and `next build` use separate output dirs (`next dev` → `.next/dev`) and a lockfile prevents concurrent instances.90- Scroll behavior: Next.js no longer overrides global `scroll-behavior: smooth` during navigations; add `data-scroll-behavior="smooth"` on `<html>` to restore the previous override behavior.91- ESLint: `@next/eslint-plugin-next` defaults to ESLint Flat Config; legacy `.eslintrc` projects may need migration.9293## Removed / Deprecated (high-level)9495- Removed: AMP support; `next lint` (use ESLint/Biome directly); `eslint` option in `next.config.*`; `serverRuntimeConfig/publicRuntimeConfig` (use env vars); `experimental.ppr` + route-level `experimental_ppr`; `unstable_rootParams`.96- Deprecated: `middleware.ts` filename (prefer `proxy.ts`); `next/legacy/image`; `images.domains` (prefer `images.remotePatterns`); `revalidateTag(tag)` single-arg form.97- `proxy.ts` note: `proxy` runs on `nodejs` only; Edge runtime is not supported in `proxy`. Keep `middleware.ts` if you must stay on Edge.98- Config rename example: `skipMiddlewareUrlNormalize` → `skipProxyUrlNormalize`.99100## Verify101102- The Next.js version targeted is named explicitly (e.g., 'Next 16') and the change does not silently rely on features from a different major103- `next build` (or the project's equivalent) was run and completed without errors; the build output / route table is captured104- Server components vs client components were chosen deliberately for each new file; the choice is justified in a comment or PR note105- `next dev` was loaded and the touched routes were rendered without console warnings or hydration mismatches106- Caching/revalidation behavior (fetch options, `revalidate`, `dynamic`) is set explicitly on new data fetches, not left to defaults107- Type-check and lint (`tsc --noEmit`, `next lint`) pass on the changed files; output is in the transcript
elophanto