hydration-safety

Prevent Next.js hydration mismatches with isMounted patterns and conditional rendering.

1|Updated Oct 9, 2025
One-click install
npx skills add https://github.com/omerakben/omer-akben --skill hydration-safety
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hydration-safety
Source: https://github.com/omerakben/omer-akben/tree/main/.claude/skills/hydration-safety-skill
Command: npx skills add https://github.com/omerakben/omer-akben --skill hydration-safety

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Next.js applications render both on the server and in the browser, which can lead to hydration mismatches when browser-only APIs are accessed during server rendering. This Skill provides patterns to keep SSR and client hydration in sync, preventing runtime errors.

Core Features & Use Cases

  • IsMounted pattern: safe client-only access by delaying browser API usage until after mount.
  • Hydration-safe components: practices for conditional rendering and avoiding window/document access on the server.
  • Practical examples: applying these patterns in common components (auth, localStorage, time-based UI) to ensure stable hydration across routes.

Quick Start

  • Add "use client" to the component that uses browser APIs.
  • Implement the isMounted pattern using useEffect and conditional rendering.
  • Verify SSR and client render parity by comparing initial output and subsequent hydration.

Frequently Asked Questions about hydration-safety

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

FAQPage Schema
How do I fix hydration mismatches in Next.js when accessing browser APIs?

Fix Next.js hydration mismatches by adding 'use client' to components accessing browser APIs and implementing the isMounted pattern with useEffect to delay client-only rendering until after mount.

Why does Next.js SSR throw hydration errors with localStorage?

Next.js SSR throws hydration errors with localStorage because the server cannot access browser APIs, causing a mismatch between server-rendered HTML and client output. Use conditional rendering and the isMounted pattern to keep them in sync.

What is the best way to use window object safely in Next.js client-side rendering?

The best way to use the window object in Next.js client-side rendering is applying the isMounted pattern via useEffect, ensuring window access only occurs post-mount to align SSR and client hydration output.

How do I prevent hydration errors for time-based UI components in Next.js?

Prevent hydration errors for time-based UI components in Next.js by using 'use client' and conditional rendering with the isMounted pattern, ensuring dynamic client-only features align server and client renders across routes.

Can I use useEffect to delay browser API access during Next.js SSR?

Yes, you can use useEffect to delay browser API access during Next.js SSR by implementing the isMounted pattern, which defers dynamic client-only features until after the component mounts to prevent hydration mismatches.

When do I need 'use client' for Next.js hydration safety?

You need 'use client' for Next.js hydration safety when a component accesses browser-only APIs like window or localStorage, requiring the isMounted pattern and safe defaults to prevent runtime hydration mismatches.