Next.js 16.2: AI Improvements

Next.js 16.2 includes several improvements designed for AI-assisted development. These changes make it easier for agents to understand your project, debug issues from the terminal, and inspect running apps — all without requiring a browser.

• Agent-ready create-next-app: Scaffold AI-ready projects out of the box
• Browser Log Forwarding: Forward browser errors to the terminal for agent-powered debugging
• Dev Server Lock File: Actionable error messages when a second dev server tries to start
• Experimental Agent DevTools: Give AI agents terminal access to React DevTools and Next.js diagnostics

Agent-ready create-next-app

create-next-app now includes an AGENTS.md file by default, giving AI coding agents access to version-matched Next.js documentation from the start of your project.

This builds on our research into AGENTS.md, which found that giving agents access to bundled documentation achieved a 100% pass rate on Next.js evals — outperforming skill-based approaches that maxed out at 79%. The key insight: always-available context works better than on-demand retrieval, because agents often fail to recognize when they should search for documentation.

For existing projects, the setup depends on your Next.js version.

On 16.2 or later, the docs are already bundled in the next package. Add these two files to the root of your project:

<!-- BEGIN:nextjs-agent-rules -->
 
# Next.js: ALWAYS read docs before coding
 
Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.
 
<!-- END:nextjs-agent-rules -->

The comment markers delimit the Next.js-managed section. You can add your own project-specific instructions outside them — future updates will only replace content between the markers.

CLAUDE.md is the instruction file for Claude Code. The @ directive tells it to include AGENTS.md as additional context:

@AGENTS.md

On earlier versions, use the codemod to generate these files automatically:

npx @next/codemod@latest agents-md

For more details, see the AI agents setup guide.

Browser Log Forwarding

Next.js now forwards browser errors to the terminal by default during development, so you can see client-side errors without switching to the browser console. This is especially helpful for AI agents that operate primarily through the terminal and can't access a browser console.

By default, only errors are forwarded to the terminal. You can control the level of forwarding with logging.browserToTerminal in your next.config.ts:

const nextConfig = {
  logging: {
    browserToTerminal: true,
    // 'error' — errors only (default)
    // 'warn'  — warnings and errors
    // true    — all console output
    // false   — disabled
  },
};
 
export default nextConfig;

Dev Server Lock File

Next.js now writes the running dev server's PID, port, and URL into the .next/dev/lock file. When a second next dev process starts in the same project directory, Next.js reads the lock file and prints an actionable error:

Error: Another next dev server is already running.
 
- Local:        http://localhost:3000
- PID:          12345
- Dir:          /path/to/project
- Log:          .next/dev/logs/next-development.log
 
Run kill 12345 to stop it.

This is especially useful for AI coding agents, which frequently attempt to start next dev without knowing a server is already running. The structured error gives the agent the PID to kill the existing process or the URL to connect to it — no manual intervention required.

The lock file also prevents two next build processes from running simultaneously, which could otherwise corrupt build artifacts.

Experimental Agent DevTools

The features above help agents understand your project and debug issues. @vercel/next-browser extends this by letting agents inspect a running Next.js application.

next-browser is an experimental CLI that exposes browser-level data — screenshots, network requests, console logs — along with framework-specific insights from React DevTools and the Next.js dev overlay, like component trees, props, hooks, Partial Prerendering (PPR) shells, and errors. All returned as structured text via shell commands.

An LLM can't read a DevTools panel, but it can run next-browser tree, parse the output, and decide what to inspect next. Each command is a one-shot request against a persistent browser session, so agents can query the app repeatedly without managing browser state. This turns the browser into something an agent can reason about, instead of a UI it can't access.

What it can do today

The feature set is evolving quickly. As of this release, next-browser supports:

• Inspect React component trees — view props, hooks, state, and source-mapped file locations
• Analyze PPR shells — identify static vs dynamic regions and blocked Suspense boundaries
• Access errors and logs — retrieve build and runtime issues from the dev server
• Monitor network activity — track requests since navigation, including server actions
• Capture visuals — take screenshots or record loading filmstrips

Getting started

Install it as a skill (a reusable capability for AI agents):

npx skills add vercel-labs/next-browser

Then type /next-browser in Claude Code, Cursor, or any AI agent that supports skills. The CLI manages a Chromium instance with React DevTools pre-loaded — no browser configuration required.

Example: Growing the static shell

With Partial Prerendering (PPR), Next.js can serve a static shell instantly from the edge — the parts of your page that don't depend on per-request data — then stream in the rest. The more content that fits in the static shell, the faster users see a meaningful page.

In practice, a single per-request fetch can accidentally make an entire page dynamic. Consider a blog post with a visitor counter:

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}
 
export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  const views = await getVisitorCount(params.slug); // per-request
 
  return (
    <article>
      <h1>{post.title}</h1>
      <span>{views} views</span>
      <div>{post.content}</div>
    </article>
  );
}

Every slug is enumerated in generateStaticParams, so the post content could be prerendered at build time. But getVisitorCount runs on every request — and because it sits at the top level of the component, it makes the entire page dynamic. As a result, the entire page waits behind a loading skeleton instead of streaming in progressively.

An agent can use next-browser to diagnose this. Locking PPR mode shows only the static shell — in this case, the app/blog/[slug]/loading.tsx skeleton, because nothing in the page made it into the shell:

next-browser ppr lock          # Enter PPR mode
next-browser goto /blog/hello  # The entire page is a loading skeleton

The agent then runs ppr unlock to find out what went wrong:

next-browser ppr unlock

# PPR Shell Analysis
# 1 dynamic hole, 1 static
 
blocked by:
  - getVisitorCount (server-fetch)
    owner: BlogPost at app/blog/[slug]/page.tsx:5
    next step: Push the fetch into a smaller Suspense leaf

The report tells the agent exactly what to do: getVisitorCount is the blocker, it lives in BlogPost, and the fix is to push it into its own Suspense boundary. The agent wraps just the counter:

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
 
  return (
    <article>
      <h1>{post.title}</h1>
      <Suspense fallback={<span>— views</span>}>
        <VisitorCount slug={params.slug} />
      </Suspense>
      <div>{post.content}</div>
    </article>
  );
}

Running ppr lock again confirms the shell grew — the post content now prerenders instantly. Only the visitor count shows a fallback:

next-browser is still evolving, but it points toward a future where agents can debug and optimize apps with the same visibility as a developer.

Feedback and Community

Share your feedback and help shape the future of Next.js:

• GitHub Discussions
• GitHub Issues
• Discord Community