Hydration mismatch terjadi ketika HTML yang dirender di server tidak sama dengan apa yang dipasang di klien, dan bisa langsung memicu UI 'vibe sickness' ala Faulty Towers: elemen hilang, class berbeda, atau animasi aneh muncul begitu saja. Dalam beberapa paragraf berikut saya jelaskan langkah langsung untuk menelusuri, mereproduksi, dan memperbaiki ketidaksesuaian ini pada aplikasi seperti Next.js atau SvelteKit.

1. Diagnosis awal: kenali gejalanya

Langsung telusuri console browser. Pesan seperti "Hydration failed because the initial UI does not match what was rendered on the server" atau "Warning: Text content did not match" menandakan mismatch. Catat apakah perbedaan muncul di text, atribut, style, atau struktur DOM. Beberapa faktor umum yang memicu gejala serupa:

  • Data asinkron yang berbeda antara server dan klien.
  • Logika yang hanya berjalan di klien (misalnya memakai window atau Date.now() tanpa guard).
  • Animation/class yang ditentukan dari state berbeda saat SSR.

Catat pula apakah layout runtuh hanya di komponen tertentu atau keseluruhan halaman—ini membantu mengarahkan debug.

2. Langkah reproducible untuk memeriksa DOM/props

Ikuti checklist inspeksi berikut setiap kali merasa UI tidak konsisten:

  1. Snapshot HTML server: ambil output SSR (Next.js: lihat .next/server/app/**/page.js atau capture network response HTML). Simpan sebagai referensi.
  2. Inspect props/state di klien: pakai React DevTools atau Svelte DevTools untuk melihat props awal dari root component. Bandingkan nilai ini dengan data yang dipakai saat render server.
  3. Periksa class/tampilan: lihat atribut class dan inline styles yang dipasang selama SSR versus saat hydration. Gunakan panel Elements dan aktifkan toggle force element state untuk memeriksa perbedaan.
  4. Perhatikan animasi atau class transient: jika ada class yang muncul karena efek (misal class .is-animated), pastikan tidak secara otomatis ditambahkan di server.

Dokumentasikan temuan dalam bentuk snapshot: screenshot DOM, JSON props, atau log data. Ini berguna untuk membuktikan apakah mismatch tetap konsisten setelah perubahan.

3. Teknik state hydration yang konsisten

Untuk menjaga state tetap sinkron, gunakan pola eksplisit:

  • Gunakan getStaticProps/getServerSideProps (Next.js) atau load (SvelteKit) untuk memberikan data awal. Jangan buat fetch tambahan di komponen yang berjalan di klien kecuali memang diperlukan.
  • Guard nilai yang hanya tersedia di klien: bungkus akses ke window atau localStorage dengan pengecekan typeof window !== 'undefined' dan tampilkan placeholder selama SSR.
  • Normalisasi data tanggal/nilai acak: jika tanggal di-render di server, hindari menampilkan waktu lokal klien saat hydration tanpa sinkronisasi. Pertimbangkan menampilkan hanya tanggal tanpa jam jika tidak bisa disinkronisasi.

Sebuah contoh konkret untuk Next.js:

function Clock({ time }) {
  const [tick, setTick] = useState(time);

  useEffect(() => {
    const id = setInterval(() => setTick(new Date().toISOString()), 1000);
    return () => clearInterval(id);
  }, []);

  return <span>{tick}</span>;
}

export async function getServerSideProps() {
  return { props: { time: new Date().toISOString() } };
}

Dengan pola ini, server memberikan waktu awal, sedangkan client memperbarui clock setelah hydrate. Tanpa props ini, komponen menanggung mismatch karena state default berbeda.

4. Mitigasi perbedaan class/animasi

Masalah biasa: server dan klien menambahkan class berbeda, terutama buat animasi atau state transient.

  • Sinkronkan class melalui state tunggal. Alih-alih melekatkan class dalam useEffect, tentukan class berdasarkan prop/state yang dijamin sama di server dan klien.
  • Nonaktifkan animasi selama SSR. Misalnya, jangan beri class animasi saat prefers-reduced-motion belum diketahui. Gunakan hook custom yang menunggu hydration sebelum menambahkan class.
  • Terapkan fallback stabil. Jika detail tertentu hanya diketahui setelah fetch klien, tampilkan placeholder yang tidak memengaruhi layout utama, lalu gunakan transition halus agar tidak muncul ketidaksesuaian.

Contoh: animasi shimmer saat data belum siap tetapi muncul pada SSR membuat class berbeda. Solusinya adalah merender shimmer hanya jika state hydrated true:

const useHydrated = () => {
  const [hydrated, setHydrated] = useState(false);
  useEffect(() => setHydrated(true), []);
  return hydrated;
};

const Card = ({ title }) => {
  const hydrated = useHydrated();
  return (<div className={hydrated ? 'card animated' : 'card'}>{title}</div>);
};

Dengan demikian, SSR hanya mengeluarkan card tanpa animated, dan class tambahan hanya ditambahkan setelah hydration, sehingga tidak terjadi mismatch.

5. Debugging, alat, dan fallback

Berikut tooling yang membantu:

  • React/Svelte DevTools: bandingkan tree sebelum dan sesudah hydrate, lihat props/state yang berbeda.
  • Browser DevTools Network > Preview: ambil HTML hasil SSR dan lihat struktur/class yang dimuat awal.
  • Testing snapshot: gunakan jest dengan react-test-renderer atau @testing-library/react untuk memastikan SSR markup tidak berubah setelah hydration.
  • Linting hydratable: perpaduan rules seperti react-hooks/exhaustive-deps dan custom lint untuk membedakan logika yang hanya boleh berjalan di klien.

Jika mismatch tetap muncul, pertimbangkan fallback berikut:

  • Tingkatkan logging data SSR/klien untuk melihat nilai yang dipakai. Tambahkan console.log hanya saat environment development.
  • Gunakan key pada root component untuk memaksa re-render ketika data vital berubah.
  • Pertimbangkan render no-js yang minimal sehingga apakah hydrate berhasil atau tidak, layout utama tetap konsisten.

6. Kesimpulan dan tips debugging ala Faulty Towers

Hydration mismatch bisa terasa seperti kekacauan ala Faulty Towers—perbedaan kecil membuat UI teriak "Basil Fawlty!" namun kita tetap bisa mengatasinya dengan langkah sistematis. Mulai dari nabung snapshot HTML, memeriksa props/state, hingga memastikan class/animasi konsisten. Kunci utamanya: berikan satu sumber kebenaran untuk data dan class, menunda animasi sampai klien siap, serta menggunakan tooling yang menjembatani server dan klien.

Selalu dokumentasikan temuan agar tim tidak bingung ketika vibe coding terasa salah lagi. Dengan pendekatan ini, UI dapat kembali stabil dan pengembang tidak perlu menyiapkan jadwal inspeksi seperti Inspektorat Faulty Towers setiap kali ada deploy.