Co powoduje hydration mismatch w React/Next.js i jak to naprawić?

Głębiej

Hydration to moment, gdy React „podczepia” event listenery i porównuje HTML z SSR z pierwszym renderem w przeglądarce. Mismatch pojawia się, gdy HTML z serwera nie zgadza się z tym, co klient renderuje na start.

Najczęstsze przyczyny

• Niedeterministyczne wartości w renderze: `Math.random()`, `Date.now()`, `crypto.randomUUID()`.
• Gałęzie zależne od przeglądarki: `typeof window !== 'undefined'` w trakcie renderu.
• Różnice locale/strefy czasowej (formatowanie dat/liczb).
• Zmiany layoutu po stronie klienta (pomiar DOM, odczyt `localStorage`) wykonywane w renderze.

Wzorce naprawy

• Pierwszy render ma być deterministyczny; odczyty client-only przenieś do `useEffect`.
• Renderuj placeholder na serwerze, a dopiero na kliencie wypełnij wartość.
• Jeśli widget jest stricte client-only, wczytaj go dynamicznie z wyłączonym SSR.

Przykład

'use client'
import { useEffect, useState } from 'react'

export function Clock() {
  const [now, setNow] = useState<string>('')
  useEffect(() => setNow(new Date().toISOString()), [])
  return <span>{now || '...'}</span>
}

Typowe pułapki

• `suppressHydrationWarning` jako „uniwersalna naprawa” (maskuje bugi).
• Formatowanie dat bez ustalonego locale/timezone.