Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

2.9 KiB

Raw Blame History

Debug Tricks

Tricks to speed up debugging Next.js applications.

MCP Endpoint (Dev Server)

Next.js exposes a /_next/mcp endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).

Next.js 16+: Enabled by default, use next-devtools-mcp
Next.js < 16: Requires experimental.mcpServer: true in next.config.js

Reference: https://nextjs.org/docs/app/guides/mcp

Important: Find the actual port of the running Next.js dev server (check terminal output or package.json scripts). Don't assume port 3000.

Request Format

The endpoint uses JSON-RPC 2.0 over HTTP POST:

curl -X POST http://localhost:<port>/_next/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "<tool-name>",
      "arguments": {}
    }
  }'

Available Tools

`get_errors`

Get current errors from dev server (build errors, runtime errors with source-mapped stacks):

{ "name": "get_errors", "arguments": {} }

`get_routes`

Discover all routes by scanning filesystem:

{ "name": "get_routes", "arguments": {} }
// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }

Returns: { "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }

`get_project_metadata`

Get project path and dev server URL:

{ "name": "get_project_metadata", "arguments": {} }

Returns: { "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }

`get_page_metadata`

Get runtime metadata about current page render (requires active browser session):

{ "name": "get_page_metadata", "arguments": {} }

Returns segment trie data showing layouts, boundaries, and page components.

`get_logs`

Get path to Next.js development log file:

{ "name": "get_logs", "arguments": {} }

Returns path to <distDir>/logs/next-development.log

`get_server_action_by_id`

Locate a Server Action by ID:

{ "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } }

Example: Get Errors

curl -X POST http://localhost:<port>/_next/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'

Rebuild Specific Routes (Next.js 16+)

Use --debug-build-paths to rebuild only specific routes instead of the entire app:

# Rebuild a specific route
next build --debug-build-paths "/dashboard"

# Rebuild routes matching a glob
next build --debug-build-paths "/api/*"

# Dynamic routes
next build --debug-build-paths "/blog/[slug]"

Use this to:

Quickly verify a build fix without full rebuild
Debug static generation issues for specific pages
Iterate faster on build errors

2.9 KiB Raw Blame History

Debug Tricks

MCP Endpoint (Dev Server)

Request Format

Available Tools

get_errors

get_routes

get_project_metadata

get_page_metadata

get_logs

get_server_action_by_id