# Nextjs16 Skills

> Key facts and links for Next.js 16. Use for planning, writing, and troubleshooting Next.js 16 changes.

- Skill: `elophanto/nextjs16-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add elophanto/nextjs16-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/elophanto/nextjs16-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: elophanto (https://skillmd.com/u/elophanto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/elophanto/nextjs16-skills

---



## Triggers

- nextjs
- next.js
- next
- app router
- server component
- ssr
- ssg
- vercel
- next 16
- pages router
- middleware
- next api

## Links

- Docs: https://nextjs.org/docs
- Upgrade guide (v16): https://nextjs.org/docs/app/guides/upgrading/version-16
- Release notes/blog: https://nextjs.org/blog/next-16

## Upgrade

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