hydration-safety · git:20260330.dc27980 · 2026-03-30 · sha256 ef153b39f3584743
hydration-safety git:20260330.dc27980A
Immutable. This exact content never changes and is served at /api/v1/blob/ef153b39f3584743.
---
description: React hydration mismatch prevention
globs: ["**/*.tsx", "**/*.ts"]
alwaysApply: false
---
# Hydration Mismatch Prevention
## The Problem
Hydration mismatches occur when server-rendered HTML doesn't match the client-rendered output, causing UI flickers, errors, and broken interactivity.
## Common AI Mistakes
### 1. Non-deterministic Values in Render
❌ WRONG — different value on server vs client:
```tsx
export default function Component() {
const id = Math.random() // Different on server vs client!
return <div id={`item-${id}`}>Content</div>
}
```
✅ CORRECT — use useId() for unique IDs:
```tsx
import { useId } from 'react'
export default function Component() {
const id = useId()
return <div id={id}>Content</div>
}
```
### 2. Browser APIs in Server-Rendered Code
❌ WRONG — window/document don't exist on server:
```tsx
export default function Component() {
const width = window.innerWidth // ReferenceError on server!
return <div>{width}</div>
}
```
✅ CORRECT — guard with useEffect:
```tsx
'use client'
import { useState, useEffect } from 'react'
export default function Component() {
const [width, setWidth] = useState(0)
useEffect(() => { setWidth(window.innerWidth) }, [])
return <div>{width}</div>
}
```
### 3. Date/Time Rendering
❌ WRONG — different timezone on server vs client:
```tsx
export default function Component() {
return <p>{new Date().toLocaleString()}</p> // Hydration mismatch!
}
```
✅ CORRECT — render dates client-side or use consistent formatting:
```tsx
'use client'
import { useState, useEffect } from 'react'
export default function DateDisplay({ date }: { date: string }) {
const [formatted, setFormatted] = useState(date)
useEffect(() => { setFormatted(new Date(date).toLocaleString()) }, [date])
return <p>{formatted}</p>
}
```
## Rule
- NEVER use Math.random(), crypto.randomUUID(), or Date.now() directly in render
- NEVER access window, document, localStorage, or navigator without checking typeof window !== 'undefined'
- Use React.useId() for dynamically generated IDs
- Wrap browser-only logic in useEffect