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.