Agent DevTools di Next.js: il debug con l'AI nel 2026

Imposti tutto una volta e l'agente legge da solo gli errori di build di Next.js, i metadati delle rotte e l'albero dei componenti React. Niente stack trace incollate in chat. Il giro si chiude nel terminale, dove l'agente vive già, e la documentazione che legge corrisponde alla versione di Next.js installata nel progetto.

Ci vogliono una ventina di minuti. Servono Next.js 16.3, un agente che parli MCP e un dev server che puoi lasciare acceso. Tutto quello che segue è first-party: lo pubblica Vercel e non costa niente.

Ci sono volute due release. Next.js 16.2 ha aggiunto il Browser Log Forwarding, il file AGENTS.md dentro create-next-app e un Agent DevTools sperimentale basato su una CLI chiamata next-browser. Next.js 16.3, uscito il 3 agosto 2026, ha fatto confluire next-browser nella CLI generalista agent-browser e porta la documentazione agli agenti attraverso un blocco AGENTS.md gestito. Nella stessa release le Skills sono state ritirate.

Cosa serve prima di cominciare

• Next.js 16.3 o successiva. Con la 16.2 hai il log forwarding e AGENTS.md, ma l'introspezione di React si è spostata dentro agent-browser.
• Un agente che parli MCP: Claude Code, Cursor o qualsiasi client che legga un file di configurazione MCP.
• Un dev server che puoi tenere acceso. Gli strumenti MCP leggono un server vivo, non il codice sorgente.
• Accesso in scrittura a next.config.ts e alla radice del repository.

Passo 1: passare a Next.js 16.3

npm install next@latest react@latest react-dom@latest

Della 16.3 qui contano due cose oltre agli strumenti per gli agenti. Gli agenti leggono documentazione allineata alla versione senza nessuna configurazione, e le sessioni di sviluppo lunghe consumano fino al 90% di memoria in meno rispetto a prima. Il dato sulla memoria non è un numero da vetrina, in questo scenario. Un flusso guidato da un agente tiene acceso un solo dev server per ore, mentre interroga, modifica e interroga di nuovo: è proprio il caso in cui il processo di sviluppo si gonfiava.

Passo 2: dare all'agente la documentazione della tua versione

create-next-app ora crea un file AGENTS.md di default. È una direttiva breve in Markdown che dice all'agente di leggere la documentazione inclusa in node_modules/next/dist/docs/ prima di scrivere codice. Su un progetto già avviato non lo aggiunge nessuno, quindi crealo tu nella radice del repository.

Vercel ha misurato la differenza. Con la documentazione inclusa nel pacchetto gli agenti hanno raggiunto il 100% di test superati sugli eval di Next.js, mentre il recupero via skill si è fermato al 79%. La ragione è poco romantica: spesso l'agente non si accorge del momento in cui dovrebbe andare a cercare la documentazione, quindi un contesto sempre presente batte un contesto da richiedere.

Il prezzo è il budget di contesto. La documentazione occupa token che l'agente potrebbe spendere leggendo il codice, quindi tratta quel blocco come qualsiasi altra istruzione sempre caricata. È la stessa disciplina che abbiamo descritto per i file CLAUDE.md e per la gestione della context window.

Passo 3: portare i log del browser nel terminale

Dalla 16.2 Next.js manda gli errori del browser nel terminale durante lo sviluppo, e lo fa di default. Un agente non apre la console del browser. Il terminale è l'unica superficie che legge, e fino a questa aggiunta gli errori lato client per lui non esistevano.

// next.config.ts
export default {
  logging: {
    browserToTerminal: 'error',
  },
}

I livelli sono 'error' (il default), 'warn', true per tutto l'output della console e false per spegnere tutto. Parti da 'error' e restaci un po'. Mettere true su un'applicazione che scrive un log a ogni render riempie il terminale e brucia il contesto dell'agente in rumore.

Passo 4: collegare il server MCP dei DevTools

Next.js 16 espone un endpoint MCP su /_next/mcp. Il pacchetto next-devtools-mcp trova i dev server accesi e fa da proxy verso quell'endpoint: così l'agente riceve errori di build, rotte e log dal vivo, invece del riassunto che gli hai scritto tu.

npx add-mcp next-devtools-mcp@latest

Per Claude Code in particolare:

claude mcp add next-devtools npx next-devtools-mcp@latest

Oppure scrivi la configurazione a mano, e vale per qualsiasi client:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

Arrivano quattro strumenti. nextjs_index trova i dev server Next.js 16+ attivi e dice quali strumenti runtime espone ciascuno. nextjs_call esegue get_errors, get_logs o get_page_metadata sulla porta trovata. nextjs_docs individua la documentazione allineata alla versione installata. Se hai già costruito un server MCP per il tuo SaaS, la forma ti sarà familiare.

Passo 5: aggiungere agent-browser per l'introspezione di React

npm install -g agent-browser@^0.27

La CLI gestisce un'istanza di Chromium con React DevTools già caricato, quindi non c'è niente da configurare nel browser. Ogni comando è una richiesta secca contro una sessione che resta aperta. L'agente interroga la pagina quante volte vuole senza portarsi dietro lo stato del browser.

I comandi React sono la metà che vale la pena imparare. react tree elenca l'albero dei componenti. react inspect <fiberId> restituisce props e hook di un singolo componente. react renders start e react renders stop profilano i re-render. react suspense --only-dynamic --json mostra cosa sta trattenendo un render, che è la strada più rapida dentro una shell di Partial Prerendering che non si risolve. Screenshot, richieste di rete, output della console e Web Vitals arrivano insieme. Dopo la fusione della 16.3 la stessa CLI funziona anche su applicazioni che non usano Next.js.

Come verificare che funzioni

1. Avvia il dev server e lascialo acceso.
2. Rompi qualcosa apposta. Basta un errore di tipo dentro un route handler.
3. Chiedi all'agente quali errori sta segnalando il dev server. Dovrebbe chiamare nextjs_call con get_errors e risponderti con file e riga, senza chiederti di incollare niente.
4. Chiedigli l'elenco delle rotte. get_page_metadata restituisce pagine e metadati dei componenti dall'applicazione accesa.
5. Lancia agent-browser react tree su una pagina. Devi ottenere un albero di componenti con i fiber id da rigirare subito a react inspect.

Cinque su cinque vuol dire che il giro è chiuso. Se qualcosa manca, il paragrafo seguente lo copre.

Guasti frequenti e come si risolvono

• Nessun server Next.js trovato. nextjs_index vuole un dev server acceso, su Next.js 16 o successiva. Una build di produzione non espone /_next/mcp, e nemmeno un server crashato tre minuti fa.
• Lo strumento della documentazione non restituisce niente. I file stanno in node_modules/next/dist/docs/. Qualsiasi passaggio di installazione che sfoltisce la documentazione dei pacchetti, cosa comune nei layer Docker snelli e in certe cache di CI, li porta via.
• L'agente cita un'API che non esiste più. La documentazione segue la versione installata, quindi dopo npm install next@latest riavvia la sessione dell'agente e lascia che rilegga il set nuovo.
• Il terminale è illeggibile. Riporta browserToTerminal da true a 'error'.
• Un secondo dev server non parte. La 16.2 ha aggiunto un file di lock del dev server che restituisce un messaggio comprensibile al posto di una collisione di porta da decifrare. Chiudi il primo server.

Dove andare da qui

Questo setup rende dove gli agenti sono più deboli: ragionare su uno stato runtime che non vedono. Sull'architettura non cambia niente. Un agente che legge get_errors alla perfezione mette lo stesso una query nel posto sbagliato, quindi le regole che imponi in revisione pesano come prima. Le nostre le teniamo scritte per le Server Actions in produzione e per i Core Web Vitals.

C'è un altro aggiornamento che sta bene insieme a questo. next build ora può fare il type check con TypeScript 7, e il compilatore in Go accorcia la distanza fra la modifica dell'agente e l'errore che quella modifica produce. Più corta è quella distanza, meno giri servono per ogni correzione.