SSR’de Hydration Mismatch Hatalarının Kök Sebebi

Hydration completed but contains mismatches.💥

SSR (Server-Side Rendering) modern framework’lerin sunduğu en büyük avantajlardan biridir -- hızlı yükleme, SEO uyumluluğu ve ilk render performansı. Ancak bu gücün bir yan etkisi vardır: Hydration Mismatch.
Eğer Vue veya Nuxt projesinde terminalde şöyle bir uyarı gördüysen, yalnız değilsin:

Hydration completed but contains mismatches.

Bu hata gizemli görünür ama aslında çok mantıklıdır. Bu yazıda “hydration” sürecinin tam olarak ne olduğunu, neden “mismatch” oluştuğunu ve bunu nasıl önleyebileceğini anlatacağız.

Hydration Nedir?

SSR sayfası oluşturduğunda, kullanıcıya şu akış gerçekleşir:

1. Server Render: Nuxt, sayfayı HTML olarak üretir ve tarayıcıya gönderir.
2. Client Hydration: Tarayıcı bu HTML’i alır, Vue uygulamasını yeniden başlatır ve aynı sanal DOM yapısını oluşturur.
3. Vue, HTML ve sanal DOM’u karşılaştırır → her şey aynıysa “hydration başarılı” der.

Özetle: SSR HTML ≠ Client render sonucu → Hydration Mismatch.

En Yaygın Sebepler

1. Zamana veya Tarayıcıya Bağımlı Kod

<p>{{ new Date().toLocaleTimeString() }}</p>

✅ Çözüm: Tarayıcıya özel kodu onMounted() içine al.

<script setup>
import { ref, onMounted } from 'vue'
const time = ref('')
onMounted(() => time.value = new Date().toLocaleTimeString())
</script>

2. Random (Rastgele) Değerler

<p>{{ Math.random() }}</p>

✅ Çözüm: Random değeri ya serverda üretip prop olarak geçir, ya da client-side oluştur.

3. Window veya Document Erişimi

const width = window.innerWidth // ❌ SSR patlar

✅ Çözüm:

if (process.client) {
  const width = window.innerWidth
}

onMounted(() => {
  console.log(window.innerWidth)
})

4. Koşullu Render Farkları

<div v-if="isClient">Tarayıcı Render</div>

✅ Çözüm: SSR ile client arasında aynı başlangıç state’ini koru. Gerekirse useState() kullan.

5. Async Veri Uyuşmazlığı

✅ Çözüm: Her useAsyncData çağrısına unique key ver.

await useAsyncData('posts', () => $fetch('/api/posts'))

Hydration Akışını Anlamak

1. SSR sırasında HTML oluşturulur.
2. Tarayıcıda Vue app yeniden başlatılır.
3. Vue, SSR HTML ile kendi render’ını karşılaştırır.
4. Fark varsa, konsola hydration mismatch uyarısı yazar.
5. Ardından Vue DOM’u yeniden oluşturur (görsel fark olmasa da performans kaybı oluşur).

Hataların Tespitinde Yardımcı Araçlar

• console.warn’da detaylı mesajlar: Vue genellikle hangi node’un uyuşmadığını belirtir.
• nuxt dev --debug modu: Hydration farklarını satır bazında gösterir.
• Vue Devtools: SSR’den gelen HTML ile client-render arasındaki farkları inceleyebilirsin.

Çözüm Önerileri

Bonus: isHydrating & onHydrated

const nuxtApp = useNuxtApp()
nuxtApp.hook('app:hydrated', () => {
  console.log('Hydration tamamlandı!')
})

Hydration ile Suspense Uyumsuzluğu

✅ Çözüm: Suspense altındaki async bileşenlerin suspensible: false olarak ayarlanması veya v-if="hydrated" kontrolüyle yüklenmesi.

Sonuç

Kısaca:

• window, document, Math.random(), Date() = dikkat!
• SSR ve client state’leri aynı olmalı.
• onMounted ve process.client kurtarıcıdır.