debug:nextjs

Diagnose and fix Next.js SSR, hydration, routing, and build-time issues.

9|1|Updated Jan 12, 2026
One-click install
npx skills add https://github.com/SnakeO/claude-debug-and-refactor-skills-plugin --skill debug-nextjs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug:nextjs
Source: https://github.com/SnakeO/claude-debug-and-refactor-skills-plugin/tree/main/plugins/debug-and-refactor/skills/debug-nextjs
Command: npx skills add https://github.com/SnakeO/claude-debug-and-refactor-skills-plugin --skill debug-nextjs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps developers systematically diagnose and fix Next.js issues across SSR, hydration, routing, API routes, and middleware, covering both App Router and Pages Router.

Core Features & Use Cases

  • Hydration and SSR debugging for hydration mismatch errors like "Text content did not match".
  • Server/Client Component boundary checks and fix patterns for App Router and Pages Router.
  • Dynamic import troubleshooting, server/client split, and API route middleware debugging.
  • Build, caching, and ISR-related issues, including revalidation, error overlays, and deployment caveats.
  • Real-world workflows for incremental debugging from reproduction to verification.

Quick Start

Identify the issue type (server, client, or build-time) and follow the Next.js debugging guide to reproduce, isolate, and apply a fix.

Frequently Asked Questions about debug:nextjs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix Next.js hydration mismatch errors like 'Text content did not match'?

Fix Next.js hydration mismatch errors by systematically debugging server/client component boundaries to detect SSR/CSR rendering conflicts and apply targeted fix patterns. This isolates mismatches caused by dynamic content or browser-only APIs during server-side rendering.

What is the best way to debug Next.js dynamic import failures?

Debug Next.js dynamic import failures by troubleshooting the server/client component split and verifying build-time configurations. This resolves module loading issues by identifying incorrect boundaries and resolving API route middleware problems.

Why does my Next.js App Router throw server/client component errors?

Next.js App Router throws server/client component errors when boundary checks fail between server and client rendering contexts. Diagnose these issues by validating component imports, applying SSR/CSR boundary best practices, and correcting invalid directive usage.

How do I resolve Next.js ISR caching and revalidation glitches?

Resolve Next.js ISR caching and revalidation glitches by debugging build-time configurations and verifying deployment caveats. This fixes stale data issues by checking revalidation endpoints and correcting invalid cache headers.

Does this debugging workflow support both App Router and Pages Router?

Yes, the debugging workflow supports both App Router and Pages Router across development environments. It handles hydration warnings, server/client boundaries, dynamic imports, API routes, and middleware issues for both routing architectures.

What should I do when Next.js API route middleware is not working?

When Next.js API route middleware is not working, debug the server/client split and inspect error overlays to isolate the faulty logic. Follow structured workflows to reproduce the routing failure, apply middleware fix patterns, and verify the request lifecycle.