debug-hydration

Diagnose and fix Next.js hydration mismatches between server and client rendering.

Updated Mar 24, 2026
One-click install
npx skills add https://github.com/SumitRajpal/nextjs-claude-architecture --skill debug-hydration
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-hydration
Source: https://github.com/SumitRajpal/nextjs-claude-architecture/tree/main/.claude/skills/debug-hydration
Command: npx skills add https://github.com/SumitRajpal/nextjs-claude-architecture --skill debug-hydration

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps identify root causes of Next.js hydration mismatches by comparing server-rendered output with client rendering and guiding fixes.

Core Features & Use Cases

  • Systematic diagnosis of common hydration culprits such as date rendering in render paths, random values, typeof window guards, browser APIs used outside effects, and conditional rendering based on client state.
  • Directed fixes and guidance with exact file and line references, explanations of why the mismatch occurs, and recommended code changes.
  • Use Case: When a Next.js app shows hydration warnings after a deployment or during SSR/CSR switch, use this skill to locate and resolve the offending render paths.

Quick Start

Provide the component name or file path to focus the hydration analysis.

Frequently Asked Questions about debug-hydration

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

FAQPage Schema
How do I fix Next.js hydration mismatches between server-rendered HTML and client rendering?

Fix Next.js hydration mismatches by analyzing component render paths to locate non-deterministic code like dynamic dates, random values, or browser APIs, then applying targeted fixes such as conditional client-side rendering or useEffect guards.

Why does my Next.js SSR hydration warning occur after deployment?

Next.js SSR hydration warnings occur after deployment because the server-rendered HTML differs from the client's initial render, often caused by browser APIs used outside effects or conditional rendering based on client state.

What is the best way to debug date rendering issues causing hydration errors in Next.js?

Debug date rendering hydration errors by tracing the component render path to identify non-deterministic date formatting, then applying useEffect guards to ensure dates only render on the client side.

Can I use typeof window checks to prevent Next.js hydration mismatches?

Using typeof window checks outside of useEffect can cause Next.js hydration mismatches because the server renders a different output than the client, requiring conditional client-side rendering to align them.

How do I diagnose random value generation causing hydration mismatches in a Next.js SSG project?

Diagnose random value hydration mismatches in Next.js SSG projects by analyzing the component render path to locate non-deterministic random generation, then moving the logic into a useEffect hook.

Does this hydration fix approach work for both Next.js SSR and SSG projects?

Yes, this hydration mismatch diagnosis and fix approach applies to both Next.js SSR and SSG projects, systematically comparing server-rendered output with client rendering across pages and components.