hanzoai/next.js
2
0
Fork 0
mirror of https://github.com/hanzoai/next.js.git synced 2026-09-24 17:00:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: modernize Next 16 upgrade AI guidance (#96314)

Browse Source 
## What

Updates the Next.js 16 upgrade guide's AI-agent section to present:

- a recommended agent-assisted upgrade path
- a dedicated docs setup section using `npx @next/codemod@canary
agents-md`
- a copy prompt that points to the guide's own docs setup and codemod
sections, uses the Version 16 guide as the source of truth, asks the
agent to communicate tradeoffs, verify with the AI-agent runtime flow
such as `next-dev-loop` when available, and repeat the post-upgrade docs
check
- a non-agent path that keeps the existing upgrade codemod instructions

It also removes the stale external MCP setup from the upgrade flow,
calls out the async Request APIs codemod gap, and clarifies how to
migrate or remove removed `experimental.dynamicIO` /
`experimental.useCache` config.

## Why

The upgrade guide should make the docs setup useful for humans and
agents before migration starts, while keeping the agent prompt concise,
self-contained, and grounded in the docs as the source of truth.

## Checks

- `git diff --check`
- MDX fence balance check
- commit hook: `lint-staged` ran Prettier and ESLint on the changed MDX
file
This commit is contained in:
Aurora Scharff
2026-07-29 15:29:05 -04:00
committed by GitHub
parent a80c0c0588
commit d321ec8aa1
1 changed files with 61 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-app/02-guides/upgrading/version-16.mdx
+61 -17
View File
@@ -6,28 +6,60 @@ description: Upgrade your Next.js Application from Version 15 to 16.
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
## Upgrading from 15 to 16
## Use an AI agent (recommended)
### Using AI Agents
An AI coding agent can run the mechanical parts of the upgrade, inspect the diff, fix follow-up breakages, and verify the app. The prompt below asks the agent to read version-matched docs, use the codemods where appropriate, explain important changes, and verify the result. Some runtime verification tools are only available after the app is upgraded.
If you're using an AI coding assistant, it can run the upgrade for you with the [codemod](#using-the-codemod) below and then help resolve any remaining breaking changes.
Give the agent this prompt:
For the best results, also configure the [`next-devtools-mcp`](https://github.com/vercel/next-devtools-mcp) server. It lets your agent inspect your running dev server for migration errors and read the version-accurate Next.js docs bundled with your project:
```prompt
Upgrade this app to Next.js 16.
```json filename=".mcp.json"
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}
Before editing code, make sure AGENTS.md points at version-matched Next.js docs. If it is missing or outdated, follow [Set up AI agent docs](/docs/app/guides/upgrading/version-16#set-up-ai-agent-docs), then read AGENTS.md.
Then follow the [Next.js 16 upgrade guide](/docs/app/guides/upgrading/version-16) as the source of truth for the migration. Use the [codemod](/docs/app/guides/upgrading/version-16#using-the-codemod) when you're ready to run the mechanical upgrade.
Briefly explain the upgrade plan in user-facing language before making broad changes. Follow the documented defaults and keep moving unless the guide requires a project-specific decision, the change is destructive, credentials or environment setup are missing, or the correct migration is ambiguous. Keep the migration scoped to the upgrade, inspect the diff, run the relevant checks, and fix remaining breaking changes.
After the app is upgraded, use the runtime verification flow from the [AI Coding Agents guide](/docs/app/guides/ai-agents) to confirm it still works. Prefer the `next-dev-loop` skill when it is available (Next.js 16.3 or later with Turbopack); otherwise fall back to the best available `next dev`, browser, and build checks. Open the key interactive UI states and check the Next dev indicator plus browser and server logs. Summarize what changed, what was verified, and what could not be verified.
Before finishing, repeat the post-upgrade check in [Set up AI agent docs](/docs/app/guides/upgrading/version-16#set-up-ai-agent-docs) so the project is ready for future agent work.
```
See the [Next.js MCP guide](/docs/app/guides/mcp) and the [`next-devtools-mcp` documentation](https://github.com/vercel/next-devtools-mcp#mcp-client-configuration) for client setup. Then ask your agent to upgrade your app — it will run the codemod and use the dev server's diagnostics to fix breaking changes.
## Or upgrade manually
### Using the Codemod
Upgrading manually follows a few steps, in order:
1. [Set up AI agent docs](#set-up-ai-agent-docs) if you use an assistant now or want future agent work grounded in version-matched docs.
2. [Run the upgrade codemod](#using-the-codemod).
3. If you prefer not to run the codemod, [install packages manually](#install-packages-manually).
4. Continue through the breaking changes below, run the relevant checks, and fix any remaining issues.
## Set up AI agent docs
The prompt above asks the agent to do this before it edits code. You can also prepare the project yourself before starting the upgrade. See the [AI Coding Agents guide](/docs/app/guides/ai-agents) for the full setup.
```bash filename="Terminal"
npx @next/codemod@canary agents-md
```
After upgrading, verify `AGENTS.md` still points at the docs for the installed Next.js version. On Next.js 16.2 and later, that should be the bundled docs in `node_modules/next/dist/docs/`. If the pre-upgrade setup downloaded docs into `.next-docs/`, update `AGENTS.md` to point at the bundled docs, then remove `.next-docs/` once nothing references it.
The managed block should look like this:
```md filename="AGENTS.md"
<!-- BEGIN:nextjs-agent-rules -->
# This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
<!-- END:nextjs-agent-rules -->
```
## Using the codemod
To update to Next.js version 16, you can use the `upgrade` [codemod](/docs/app/guides/upgrading/codemods#160):
@@ -55,6 +87,14 @@ The [codemod](/docs/app/guides/upgrading/codemods#160) is able to:
- Remove `unstable_` prefix from stabilized APIs
- Remove `experimental_ppr` Route Segment Config from pages and layouts
The `upgrade` codemod does not run every migration codemod. If your app still uses synchronous `params`, `searchParams`, `cookies()`, `headers()`, or `draftMode()` access from the Next.js 15 compatibility period, also run the async Request APIs codemod:
```bash filename="Terminal"
npx @next/codemod@canary next-async-request-api .
```
## Install packages manually
If you prefer to do it manually, install the latest Next.js and React versions:
```bash package="pnpm"
@@ -1184,7 +1224,7 @@ The indicator itself remains available.
### `experimental.dynamicIO` and `experimental.useCache`
The `experimental.dynamicIO` and `experimental.useCache` flags are deprecated. Use top-level [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) instead.
The `experimental.dynamicIO` and `experimental.useCache` flags have been removed.
```js filename="next.config.js"
// Before: experimental.useCache
@@ -1204,6 +1244,8 @@ module.exports = {
}
```
If you were actively using these flags, migrate to top-level [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents):
```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'
@@ -1222,7 +1264,9 @@ module.exports = {
}
```
For more on Cache Components, see [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components).
If you were not actively adopting Cache Components, remove the flags instead. Enabling `cacheComponents` is not a rename-only change: it can surface build errors for uncached data outside of `<Suspense>` and requires adopting the Cache Components model.
For the full migration path, see [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components).
### `unstable_rootParams`