Files

Jason Woltje f6bcc86881 feat: Add 5 curated skills for Mosaic Stack

New skills:
- next-best-practices: Next.js 15+ RSC, async patterns, self-hosting (vercel-labs)
- better-auth-best-practices: Official Better-Auth with Drizzle adapter (better-auth)
- verification-before-completion: Evidence-based completion claims (obra/superpowers)
- shadcn-ui: Component patterns with Tailwind v4 adaptation note (developer-kit)
- writing-skills: TDD methodology for skill authoring (obra/superpowers)

README reorganized by category with Mosaic Stack alignment section.
Total: 9 skills (4 existing + 5 new).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-16 16:17:40 -06:00

2.9 KiB

Raw Permalink 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 Permalink 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