Next.js DevTools Skill

Overview

This skill provides Next.js-specific development tools for analyzing routes, inspecting components, and optimizing builds. It achieves 90%+ context savings compared to raw MCP by providing focused, structured outputs specific to Next.js App Router and Pages Router architectures.

Context Savings: Instead of loading full Next.js build outputs (50k+ tokens), this skill provides targeted analysis (2-5k tokens) with actionable insights.

Use Cases:

• Route structure analysis and debugging
• Server vs Client component detection
• Bundle size optimization
• Middleware configuration validation
• Environment variable verification

Requirements

• Next.js project (13+ with App Router recommended, Pages Router supported)
• Node.js 18+
• Project root with next.config.js or next.config.mjs

Tools (Progressive Disclosure)

Route Analysis

Tool	Description	Output
list-routes	List all routes in the project (App Router & Pages Router)	JSON array of route paths with metadata
analyze-route	Analyze a specific route handler (params, layout, loading states)	Route structure with dependencies
check-middleware	Analyze middleware configuration and matcher patterns	Middleware config with route matches

Component Analysis

Tool	Description	Output
list-components	List server/client components with 'use client' detection	Component inventory with type classification
component-tree	Show component hierarchy and parent-child relationships	Tree structure with import paths
check-hydration	Identify potential hydration issues	List of components with hydration warnings

Build Analysis

Tool	Description	Output
analyze-bundle	Analyze bundle size by route and component	Bundle sizes with optimization suggestions
check-build	Validate build output and identify issues	Build validation report
list-static-paths	Show statically generated paths from getStaticPaths	Static path inventory

Configuration

Tool	Description	Output
validate-config	Validate next.config.js syntax and options	Config validation report
check-env	Check environment variables (.env files)	Env var inventory with missing vars
analyze-redirects	Analyze redirects and rewrites configuration	Redirect/rewrite rules

Quick Reference

List All Routes (App Router)

# Find all app directory routes
find app -type f \( -name "page.tsx" -o -name "page.js" -o -name "route.ts" -o -name "route.js" \) | sed 's|app||; s|/page\.[jt]sx\?||; s|/route\.[jt]s||' | sort

List All Routes (Pages Router)

# Find all pages directory routes
find pages -type f \( -name "*.tsx" -o -name "*.js" \) ! -name "_*.tsx" ! -name "_*.js" | sed 's|pages||; s|\.[jt]sx\?||' | sort

Detect Client Components

# Find all 'use client' components
grep -r "use client" app/ src/ --include="*.tsx" --include="*.js" --include="*.jsx" -l

Analyze Bundle Size

# Build and analyze bundle
ANALYZE=true npm run build
# Or with next-bundle-analyzer
npx @next/bundle-analyzer

Check Middleware

# Find middleware files
find . -name "middleware.ts" -o -name "middleware.js" | head -5

Validate Environment Variables

# List all .env files
ls -la .env* 2>/dev/null || echo "No .env files found"

Check Static Export Configuration

# Verify output: 'export' in next.config.js
grep -E "output:\s*['\"]export['\"]" next.config.js next.config.mjs 2>/dev/null

Configuration

Working Directory: Project root containing next.config.js/next.config.mjs and package.json

Environment Variables:

• NODE_ENV: development or production
• ANALYZE: Set to true for bundle analysis

Next.js Versions:

• App Router (Next.js 13+): Primary support with app/ directory
• Pages Router (Next.js 12+): Full support with pages/ directory
• Hybrid: Both routers can coexist

Agent Integration

Primary Agents

• developer: General Next.js development and debugging
• react-component-developer: Component-specific analysis and creation
• performance-engineer: Bundle optimization and performance tuning

Secondary Agents

• architect: Route architecture and App Router design
• devops: Build configuration and deployment optimization
• qa: Testing route handlers and API routes

Skill Triggers

• Keywords: "next.js", "app router", "pages router", "route handler", "server component", "client component"
• File patterns: app/**/*.tsx, pages/**/*.tsx, next.config.js, middleware.ts

Examples

Example 1: Route Analysis

Task: "List all routes in the Next.js app"

Skill Invocation:

# App Router
find app -type f \( -name "page.tsx" -o -name "page.js" \) | sed 's|app||; s|/page\.[jt]sx\?||' | sort

# Output:
# /
# /dashboard
# /dashboard/settings
# /api/users

Agent: developer or architect

Example 2: Component Inspection

Task: "Identify all client components"

Skill Invocation:

# Find 'use client' directives
grep -r "use client" app/ --include="*.tsx" -l | sort

# Output:
# app/components/Button.tsx
# app/components/Modal.tsx
# app/dashboard/ClientWrapper.tsx

Agent: react-component-developer

Example 3: Bundle Optimization

Task: "Analyze bundle size and identify large dependencies"

Skill Invocation:

# Build with analysis
npm run build 2>&1 | grep -A 20 "Route (app)"

# Output shows route sizes:
# ┌ ○ /                    1.2 kB
# ├ ○ /dashboard          45.3 kB  ← Large bundle
# └ ○ /api/users         890 B

Agent: performance-engineer

Example 4: Middleware Validation

Task: "Check middleware configuration"

Skill Invocation:

# Find and read middleware
find . -name "middleware.ts" -exec cat {} \;

# Look for matcher config
grep -A 5 "export const config" middleware.ts

Agent: developer or security-architect

Example 5: Environment Variable Check

Task: "Verify all required environment variables are set"

Skill Invocation:

# List .env files
ls -la .env*

# Check for specific vars
grep -h "^[A-Z_]*=" .env.local .env 2>/dev/null | cut -d= -f1 | sort -u

Agent: devops

Example 6: Static Path Generation

Task: "List all statically generated paths"

Skill Invocation:

# Find generateStaticParams functions
grep -r "generateStaticParams" app/ --include="*.tsx" --include="*.ts" -B 2 -A 10

Agent: developer

Troubleshooting

Issue: Routes not found

Symptom: find command returns no results

Solution:

# Verify project structure
ls -la app/ pages/ 2>/dev/null

# Check for TypeScript vs JavaScript
find app pages -type f -name "*.tsx" -o -name "*.jsx" -o -name "*.ts" -o -name "*.js" | head -10

Issue: Build analysis not working

Symptom: ANALYZE=true npm run build doesn't show bundle analyzer

Solution:

# Install @next/bundle-analyzer
npm install --save-dev @next/bundle-analyzer

# Update next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer(nextConfig)

Issue: Middleware not applying to routes

Symptom: Middleware doesn't execute on expected routes

Solution:

# Check matcher configuration
cat middleware.ts | grep -A 10 "config"

# Verify matcher patterns
# Correct: matcher: ['/dashboard/:path*']
# Wrong: matcher: ['/dashboard/*']  (invalid glob syntax)

Issue: Client component hydration errors

Symptom: Hydration mismatch warnings in browser console

Solution:

# Find components with 'use client'
grep -r "use client" app/ --include="*.tsx" -l

# Check for server-only imports in client components
# Look for 'fs', 'path', 'next/headers' in client components

Issue: Environment variables not loading

Symptom: process.env.VARIABLE is undefined

Solution:

# Check .env file exists and has correct prefix
cat .env.local | grep "NEXT_PUBLIC_"

# Public vars MUST start with NEXT_PUBLIC_
# Server-only vars don't need prefix

Issue: Dynamic route params not typed

Symptom: TypeScript errors on params in route handlers

Solution:

// Add proper types to route handlers
type Params = { params: { id: string } }

export async function GET(request: Request, { params }: Params) {
  // params.id is now typed
}

Performance Tips

1. Lazy Load Client Components: Use React.lazy() and Suspense for client components
2. Optimize Images: Use next/image with proper sizes prop
3. Route Segment Config: Add export const dynamic = 'force-static' where possible
4. Minimize Client JS: Keep client boundaries minimal; prefer server components
5. Parallel Routes: Use parallel routes (@slot) for simultaneous data fetching

Related Skills

• repo-rag: Search codebase for Next.js patterns
• scaffolder: Generate Next.js route boilerplate
• rule-auditor: Validate Next.js coding standards
• test-generator: Generate route handler tests
• performance-engineer: Advanced bundle optimization

Version Support

Next.js Version	Support Level	Notes
15.x	Full	Latest App Router features
14.x	Full	Stable App Router, Turbopack
13.x	Full	App Router introduced
12.x	Partial	Pages Router only
<12.x	Limited	Legacy features only

Additional Resources

• Next.js Documentation
• App Router Migration Guide
• Bundle Analyzer Plugin
• Next.js Performance Patterns