Hydration mismatch SSR terjadi ketika HTML server-rendered berbeda dengan apa yang dirender ulang di klien, sehingga menimbulkan warning dan perilaku UI tidak konsisten. Dokumentasi investigasi membantu tim frontend memahami akar masalah dan mereproduksi solusi. Artikel ini langsung menjelaskan langkah-langkah observasi, strategi penyempitan komponen, metode penyimpanan snapshot state, dan cara mengkomunikasikan temuan berdasarkan semangat learn in public.

Catat Observasi State Awal dan Perbedaan yang Terlihat

Mulai dengan mencatat konteks saat mismatch terjadi. Sertakan URL atau nama route, state awal yang diberikan dari server, dan error/console warning lengkap. Jangan hanya menuliskan “ada mismatch” — tulis data yang bisa dibandingkan. Contoh log:

route: /dashboard/pengaturan
SSR props: { user: { name: 'Bayu', roles: ['admin'] }, theme: 'dark' }
Client render: user.name missing, theme default 'light'
Console: Warning: Text content did not match.

Lampirkan juga langkah manual yang memicu mismatch: klik menu, refresh halaman dengan cache bersih, atau login token tertentu. Catatan ini membantu rekan lain mengulang kasus yang sama.

Strategi Mempersempit Komponen yang Bermasalah

Pertanyaan pertama: apakah mismatch berasal dari props/children yang tidak konsisten, atau dari hook efek yang mengubah state setelah mount? Gunakan pendekatan bertahap:

  1. Matikan fitur satu per satu. Tulis di dokumentasi komponen: “Hapus <UserAvatar> dan warning hilang” — ini mengisyaratkan bahwa internals komponen tersebut problematik.
  2. Bandingkan props yang diterima. Tambahkan log sementara atau debugger pada console.log('props hydrated', props) di komponen suspect. Catat nilai awal di dokumentasi untuk membandingkan dengan SSR.
  3. Periksa hook efek. Tulis di dokumen: “useEffect di useUserStatus men-set state berdasarkan waktu lokal, mengakibatkan nilai berbeda antara server dan klien, terutama untuk role null.”

Setiap percobaan disertai hasil eksperimental: apa yang berubah, apakah warning hilang, dan apakah UI tetap valid. Format tabel atau bullet membantu pembaca cepat memahami temuan.

Menyimpan Snapshot State untuk Analisis dan Reproduksi

Sekali mismatch teridentifikasi, simpan snapshot state sebagai referensi: props dari server, state lokal yang ter-render, dan event/browser state. Pilih format yang mudah dibaca dan di-diff, seperti JSON terformat atau Markdown table.

## Snapshot: 2024-03-18 10:21
- Route: /dashboard/pengaturan
- SSR props:
  {
    "user": {"name": "Bayu", "roles": ["admin"]},
    "theme": "dark"
  }
- Hydrated client state (after useEffect):
  {
    "user": {"name": "Bayu", "roles": []},
    "theme": "light"
  }
- Triggers: login token A, cookie prefer-theme default.

Gunakan tools seperti Redux DevTools atau React Developer Tools untuk menyalin state aktual. Jika aplikasi menggunakan state manager (Redux, Zustand, atau context), sertakan snapshot action/reducer yang memicu perubahan. Simpan file snapshot di folder docs/hydration-investigations atau wiki tim agar mudah diakses.

Mengomunikasikan Temuan agar Tim Bisa Belajar dan Mereplikasi

Dokumentasi tidak lengkap tanpa narasi hasil akhir. Sertakan ringkasan pendek tentang lapisan yang diperbaiki dan alasan perubahan berhasil. Gunakan struktur:

  • Masalah: mismatch karena useMediaQuery menginisialisasi state berdasarkan window.
  • Penemuan: SSR tidak memiliki window; nilai default berbeda.
  • Solusi percobaan: perkenalkan guard if (typeof window === 'undefined') atau gunakan no-ssr wrapper.
  • Action plan: perbarui komponen dengan nilai default konsisten, dokumentasikan test manual yang sudah dilakukan.

Tambahkan bagian “Catatan untuk replikasi” yang mencakup command build/test (misalnya: npm run dev:ssr + mode incognito), serta timing (misalnya: terjadi hanya di mode production build). Jika perbaikan menuntut perubahan di sisi server atau backend, sebutkan dependensi tersebut agar menjadi referensi lintas tim.

Mengabadikan Learnings di Tempat yang Bisa Dicari dan Dibagikan

Supaya investigasi bermanfaat untuk proyek berikutnya, gunakan format dokumentasi standar: judul, tanggal, langkah, screenshot/log, hasil akhir. Taruh di wiki tim, repository docs, atau catatan publik. Sertakan tag seperti #hydration, #SSR, #mismatch supaya mudah dicari.

Gunakan format ringkas namun lengkap agar engineer lain bisa meniru debug berikutnya: “Saya menjalankan npm run dev:ssr, memperhatikan warning di console, dan menemukan mismatch antara theme. Setelah menyamakan default value, warning hilang.” Dokumentasi semacam ini memenuhi semangat learn in public dengan membagikan proses dan keputusan teknis.