Kebingungan render mismatch di SvelteKit muncul ketika output sisi server (SSR) berbeda dengan render awal klien (CSR). Langsung tinjau perbedaan tersebut agar tidak hanya menutupi gejala. Dalam bahasa sederhana, lihat apa yang di-serialize di HTML, bandingkan dengan state awal JavaScript, dan cari tahu di mana snapshot terakhir tidak sesuai.

Mempersiapkan perbandingan SSR vs CSR

Mulai dengan memperhatikan struktur HTML hasil SSR di View Source. Catat data dan atribut penting yang ikut di-render. Lalu buka aplikasi dari tab Elements di DevTools dan tangkap struktur DOM setelah hydration selesai. Jika keduanya berbeda, ada indikasi state CSR berubah sebelum hydration selesai.

Langkah praktis:

  1. Buka halaman yang bermasalah, klik kanan > "View Page Source" untuk melihat HTML SSR.
  2. Di DevTools, buka tab Elements lalu tekan refresh untuk melihat DOM hasil hydration.
  3. Gunakan highlight untuk menemukan atribut data-sveltekit-hydrate agar mengetahui node yang di-hydrate.

Perbedaan sederhana seperti nilai teks, class, atau atribut boolean bisa menjadi petunjuk awal.

Membuat Snapshot State Awal

Render mismatch sering terjadi karena state awal (snapshot) yang di-hydrate tidak sama dengan state SSR. Bila Anda menaruh data di load() dan menambahkan state lokal, pastikan snapshot pertama dicatat sebelum perubahan lain terjadi.

Contoh minimal:

export function load() {
  return {
    props: {
      count: 5
    }
  };
}

let count = data.count;

Gunakan console atau debugger untuk mencetak state di lifecycle seperti onMount:

import { onMount } from 'svelte';

onMount(() => {
  console.log('state awal', { count });
});

Jika count di SSR 5 tapi di CSR berubah menjadi 7 sebelum hydration selesai, berarti ada efek samping yang mengubah state terlalu awal.

Memastikan Hydration Konsisten

Hydration bekerja dengan menyamakan state JavaScript klien dengan HTML SSR. Ketidaksesuaian membuat DOM direkonsiliasi ulang dan UI berkedip. Pastikan:

  • Data async tidak ditulis langsung di component scope. Gunakan load() untuk data awal, lalu gunakan stores atau prop dalam component.
  • Efek samping dijalankan setelah hydration, misalnya dalam onMount, agar tidak mengubah DOM sebelum Svelte menyelesaikan proses dan men-trigger mismatch.
  • State lokal bersandar pada props, bukan langsung modifikasi global yang belum tersedia di SSR.

Jika Anda perlu menginisialisasi state dengan nilai dari localStorage, lakukan di onMount dan tampilkan placeholder statis hingga selesai.

Alat Observasi: Inspector, DevTools, dan Logging

Gunakan teknik berikut:

  • Inspector Svelte: Tunjukkan komponen dan state real-time saat debugging mismatch.
  • DevTools Console: Cetak snapshot state sebelum dan sesudah hydration.
  • Network Tab: Pastikan data SSR yang di-fetch konsisten dengan response API.

Timing mismatch sering terjadi saat data fetch selesai setelah render awal. Pastikan load() sudah menyelesaikan permintaan sebelum component dipasang.

Isolasi Perbedaan State

Jika mismatch tidak jelas, isolasi dengan langkah berikut:

  1. Komentari bagian component yang melakukan perubahan state (misal store update) lalu refresh untuk melihat apakah mismatch hilang.
  2. Ganti data awal dengan konstanta yang sederhana. Jika mismatch hilang, berarti logika berubah nilainya sebelum hydration selesai.
  3. Gunakan store terpisah untuk state yang berbeda, agar setiap bagian bisa diuji satu per satu.

Bila mismatch muncul hanya di satu halaman, pikirkan apakah halaman tersebut menuliskan <script> inline atau memanggil document.cookie yang merubah DOM sebelum hydration.

Checklist Sebelum Deploy

  • Bandingkan output SSR dan CSR secara manual di halaman utama sebelum release.
  • Pastikan semua efek samping berat dijalankan di onMount atau setelah hydration, bukan saat module di-import.
  • Verifikasi data awal yang dikirim ke client melalui load() sesuai dengan snapshot yang di-hydrate.
  • Jalankan alat linting dan testing (misal npm run check) untuk menangkap error SSR lain yang bisa menyebabkan mismatch.
  • Gunakan visual regression test jika UI berkedip masih terjadi di beberapa layar atau kondisi data berbeda.

Keberhasilan debugging render mismatch bukan hanya menyelesaikan satu kasus, tetapi memastikan pola state dan hydration konsisten di seluruh aplikasi.