Unverified Commit 044ef6dc authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: add upgrade section to installation and expand AI agents guide (#95861)

DOC-6499, two changes:

**Installation: new "Upgrade your Next.js app" section.** The `next
upgrade` command, why frequent updates matter (security patches, fixes,
optimizations, new features), and that upgrading also updates the docs
bundled in the `next` package, with a prompt for agents to catch up
after an upgrade. Links the Upgrading page for version guides.

**AI agents guide expanded.** Beyond bundled docs: runtime visibility
(browser logs forwarded to the terminal, structured error copy, the MCP
server for querying dev-server state) and skills for multi-step
workflows. Covers the 16.2 case where docs are bundled but `AGENTS.md`
is not auto-generated, and cross-links Upgrading.

Claims verified against source (`next-upgrade.ts`, `agentRules`,
`browserDebugInfoInTerminal`, `--no-agents-md`). Docs-only.
parent f54dbb9c
...@@ -460,3 +460,31 @@ For example, the following configuration maps `@/components/*` to `components/*` ...@@ -460,3 +460,31 @@ For example, the following configuration maps `@/components/*` to `components/*`
``` ```
Each of the `"paths"` are relative to the `baseUrl` location. Each of the `"paths"` are relative to the `baseUrl` location.
## Upgrade your Next.js app
Keep your Next.js version up to date. Each release ships security patches, bug fixes, and performance optimizations alongside new features, and staying current keeps every individual upgrade small. Run the `upgrade` command:
```bash package="pnpm"
pnpm next upgrade
```
```bash package="npm"
npx next upgrade
```
```bash package="yarn"
yarn next upgrade
```
```bash package="bun"
bunx next upgrade
```
Upgrading also updates the documentation bundled inside the `next` package at `node_modules/next/dist/docs/`. New features arrive with their docs, and existing pages pick up new guidance and pitfalls discovered along the way. [AI coding agents](/docs/app/guides/ai-agents) in your project then work from the version you have installed rather than their training data. After an upgrade, you can prompt your agent to catch up:
```prompt
Let's get our Next.js knowledge up to speed, and give me a summary of what's new for you
```
See [Upgrading](/docs/app/getting-started/upgrading) for version guides and manual upgrade steps, or the [preview docs](https://preview.nextjs.org) to explore features before they ship in a stable version.
...@@ -6,10 +6,15 @@ related: ...@@ -6,10 +6,15 @@ related:
title: Next Steps title: Next Steps
links: links:
- app/guides/mcp - app/guides/mcp
- app/getting-started/upgrading
- app/api-reference/cli/create-next-app
- app/api-reference/cli/next
--- ---
Next.js ships version-matched documentation inside the `next` package, allowing AI coding agents to reference accurate, up-to-date APIs and patterns. An `AGENTS.md` file at the root of your project directs agents to these bundled docs instead of their training data. Next.js ships version-matched documentation inside the `next` package, allowing AI coding agents to reference accurate, up-to-date APIs and patterns. An `AGENTS.md` file at the root of your project directs agents to these bundled docs instead of their training data.
Beyond the docs, Next.js gives agents [runtime visibility](#runtime-visibility) into the running dev server, with forwarded browser logs, an [MCP server](/docs/app/guides/mcp), and a browser they can drive. [Skills](#skills-for-multi-step-workflows) package multi-step workflows like adopting Cache Components.
## How it works ## How it works
When you install `next`, the Next.js documentation is bundled at `node_modules/next/dist/docs/`. The bundled docs mirror the structure of the [Next.js documentation site](https://nextjs.org/docs): When you install `next`, the Next.js documentation is bundled at `node_modules/next/dist/docs/`. The bundled docs mirror the structure of the [Next.js documentation site](https://nextjs.org/docs):
...@@ -25,9 +30,9 @@ node_modules/next/dist/docs/ ...@@ -25,9 +30,9 @@ node_modules/next/dist/docs/
└── index.mdx └── index.mdx
``` ```
This means agents always have access to docs that match your installed version — no network request or external lookup required. This means agents always have access to docs that match your installed version, with no network request or external lookup required. [Upgrading Next.js](/docs/app/getting-started/upgrading) also upgrades the bundled docs, including new guidance for existing features.
The `AGENTS.md` file at the root of your project tells agents to read these bundled docs before writing any code. Most AI coding agents — including Claude Code, Cursor, GitHub Copilot, and others — automatically read `AGENTS.md` when they start a session. The `AGENTS.md` file at the root of your project tells agents to read these bundled docs before writing any code. Most AI coding agents, including Claude Code, Cursor, and GitHub Copilot, automatically read `AGENTS.md` when they start a session.
## Getting started ## Getting started
...@@ -59,7 +64,7 @@ npx create-next-app@canary --no-agents-md ...@@ -59,7 +64,7 @@ npx create-next-app@canary --no-agents-md
### Existing projects ### Existing projects
On Next.js 16.3 or later, just run `next dev`. When an AI coding agent is detected in the environment and no managed block is present, Next.js auto-generates `AGENTS.md` and `CLAUDE.md` at the project root. Existing `AGENTS.md` or `CLAUDE.md` files are upserted — content outside the managed block is preserved: On Next.js 16.3 or later, just run `next dev`. When an AI coding agent is detected in the environment and no managed block is present, Next.js auto-generates `AGENTS.md` and `CLAUDE.md` at the project root. Existing `AGENTS.md` or `CLAUDE.md` files are upserted, so content outside the managed block is preserved:
```md filename="AGENTS.md" ```md filename="AGENTS.md"
<!-- BEGIN:nextjs-agent-rules --> <!-- BEGIN:nextjs-agent-rules -->
...@@ -77,9 +82,11 @@ This block is written and re-added by `next dev` — verify at `node_modules/nex ...@@ -77,9 +82,11 @@ This block is written and re-added by `next dev` — verify at `node_modules/nex
@AGENTS.md @AGENTS.md
``` ```
Add your own project-specific instructions outside the `<!-- BEGIN:nextjs-agent-rules -->` and `<!-- END:nextjs-agent-rules -->` markers, and they're preserved when Next.js updates the managed block.
### Opting out ### Opting out
We believe leaving auto-generation on is a good default—[benchmark results on nextjs.org/evals](https://nextjs.org/evals) show agents do better when they read the bundled docs. If you really want to opt out, set `agentRules` to `false` in your config: We believe leaving auto-generation on is a good default. [Benchmark results on nextjs.org/evals](https://nextjs.org/evals) show agents do better when they read the bundled docs. If you really want to opt out, set `agentRules` to `false` in your config:
```ts filename="next.config.ts" ```ts filename="next.config.ts"
import type { NextConfig } from 'next' import type { NextConfig } from 'next'
...@@ -93,18 +100,43 @@ export default nextConfig ...@@ -93,18 +100,43 @@ export default nextConfig
### For earlier versions ### For earlier versions
On version 16.1 and earlier, use the legacy `agents-md` command, which downloads the docs to `.next-docs/` in the project root: On version 16.2, the docs are bundled but `AGENTS.md` is not auto-generated. Add the file yourself with an instruction to read the bundled docs at `node_modules/next/dist/docs/` before writing code.
On version 16.1 and earlier, the docs are not bundled either. Use the legacy `agents-md` command, which downloads a version-matched copy to `.next-docs/` in the project root and indexes it in `AGENTS.md`:
```bash ```bash
npx @next/codemod@canary agents-md npx @next/codemod@canary agents-md
``` ```
## Understanding AGENTS.md ## Runtime visibility
Agents also need to see what the running app is doing. Runtime errors, client-side warnings, and rendered output live in the browser, where agents can't look. Next.js surfaces two complementary views that an agent can read from the terminal.
First, `next dev` forwards browser console errors and warnings to the terminal (the [`logging.browserToTerminal`](/docs/app/api-reference/config/next-config-js/logging) config), so the output agents already read carries the client-side failures they're asked to fix.
The **framework's view** comes from the [Next.js MCP server](/docs/app/guides/mcp) at `/_next/mcp`: the running dev server's routes, server logs, and compilation issues. Its `get_compilation_issues` and `compile_route` tools report whether the code compiles straight from the dev server, so an agent doesn't have to run a full `next build` to find out.
The **browser's view** comes from [`agent-browser`](https://github.com/vercel-labs/agent-browser), a CLI that exposes the DOM, console, network, and Web Vitals as structured text. With React DevTools enabled, it also reports the component tree and which Suspense boundaries are still pending. An agent runs a command like `react tree`, reads the output, and decides what to inspect next, instead of looking at a DevTools panel it can't see.
The default `AGENTS.md` contains a single, focused instruction: **read the bundled docs before writing code**. This is intentionally minimal — the goal is to redirect agents from stale training data to the accurate, version-matched documentation in `node_modules/next/dist/docs/`. The [`next-dev-loop` skill](#skills-for-multi-step-workflows) builds on both views, combining the framework's and the browser's perspective into a single edit-and-verify loop.
The `<!-- BEGIN:nextjs-agent-rules -->` and `<!-- END:nextjs-agent-rules -->` comment markers delimit the Next.js-managed section. You can add your own project-specific instructions outside these markers without worrying about them being overwritten by future updates. > **Good to know:** For the story behind this tooling, see the [Next.js 16.2](https://nextjs.org/blog/next-16-2-ai) and [Next.js 16.3](https://nextjs.org/blog/next-16-3-ai-improvements) AI blog posts.
The bundled docs include guides, API references, and file conventions for the App Router and Pages Router. When an agent encounters a task involving routing, data fetching, or any other Next.js feature, it can look up the correct API in the bundled docs rather than relying on potentially outdated training data. ## Skills for multi-step workflows
> **Good to know:** To see how bundled docs and `AGENTS.md` improve agent performance on real-world Next.js tasks, visit the [benchmark results](https://nextjs.org/evals). Some tasks are workflows rather than lookups, such as adopting Cache Components or Partial Prefetching across an app. [Next.js skills](https://github.com/vercel/next.js/tree/canary/skills) package these as structured instructions an agent installs and follows, sequencing the work and pointing at the relevant docs at each step.
The available skills are:
| Skill | What it does |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`next-dev-loop`](https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop) | Verifies a change actually works at runtime against a running dev server, combining the [MCP server](/docs/app/guides/mcp)'s view with the browser's. |
| [`next-cache-components-adoption`](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-adoption) | Turns on [Cache Components](/docs/app/getting-started/caching) and walks the app to a passing build, resolving each blocking route the flag surfaces. |
| [`next-cache-components-optimizer`](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer) | Drives a route to instant navigation with a test-driven loop, growing its static shell under Cache Components until it commits immediately on both first load and client-side navigation. |
| [`next-partial-prefetching-adoption`](https://github.com/vercel/next.js/tree/canary/skills/next-partial-prefetching-adoption) | Turns on [Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) and works through the insights it surfaces until every link reuses a shared App Shell. |
Install a skill by passing its name to the `skills` CLI:
```bash
npx skills add vercel/next.js --skill next-cache-components-adoption
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment