Hydration mismatch hatası nedir? En sık nedenleri ve çözümleri nelerdir?

SSR'da sunucu HTML üretir, tarayıcıda React aynı ağacı tekrar render edip mevcut DOM'a event handler'ları bağlar (hydration). İlk client render'ı sunucu HTML'iyle birebir aynı olmazsa "Hydration failed / text content does not match" hatası alınır; React o kısmı client'ta baştan render eder (performans kaybı, görsel zıplama).

Sık nedenler

• Render sırasında Date.now(), new Date().toLocaleString(), Math.random().
• typeof window !== "undefined" ile sunucuda ve client'ta farklı çıktı üretmek.
• localStorage, window.innerWidth, kullanıcının saat dilimi/locale'i.
• Geçersiz HTML iç içeliği: <p> içinde <div>, <a> içinde <a>, <table> içinde <tbody> olmadan <tr>.
• Tarayıcı eklentilerinin DOM'u değiştirmesi (ör. <html>/<body>'ye attribute eklemesi).

Çözümler

1. Tarayıcıya özgü değeri mount'tan sonra okuyun:

function LocalTime() {
  const [time, setTime] = useState<string | null>(null);
  useEffect(() => setTime(new Date().toLocaleTimeString("tr-TR")), []);
  return <span>{time ?? "--:--"}</span>;
}

1. Gerçekten farklı olması beklenen tek bir metin için suppressHydrationWarning (sadece bir seviye derinlikte çalışır; kaçamak olarak kullanmayın).
2. Bileşeni sadece client'ta render edin: Next.js'te dynamic(() => import("./Chart"), { ssr: false }) (Client Component içinde).
3. Rastgele id'ler için Math.random() yerine useId().
4. Tema (dark mode) için HTML'e script ile class eklemek ve <html suppressHydrationWarning> kullanmak yaygın bir desendir (next-themes).

React 19 hata mesajlarında artık farkın tam diff'ini gösterir; bu, kaynağı bulmayı kolaylaştırır.