Hydration mismatch pada UI game SSR terjadi ketika HTML yang dikirim server tidak sama dengan hasil render pertama di browser. Pada aplikasi game, arcade, quiz, atau concierge interaktif, masalah ini sering muncul karena komponen mencoba merender hal yang tidak deterministik seperti Math.random(), Date.now(), data dari localStorage, perbedaan timezone/locale, atau percabangan UI berdasarkan window dan API browser lain.

Intinya: jika output render awal harus di-hydrate dari SSR, maka server dan client harus menghasilkan markup yang sama. Jika tidak, Anda akan melihat warning hydration, flicker, state yang reset, elemen lompat posisi, atau UI yang tampak benar sesaat lalu berubah setelah JavaScript aktif. Pada UI game, bug ini terasa lebih parah karena banyak layar bergantung pada skor, seed, progress, rekomendasi acak, dan animasi kondisi awal.

Apa itu hydration mismatch dan kenapa sering terjadi pada UI game?

Pada arsitektur SSR, server lebih dulu menghasilkan HTML agar halaman bisa tampil cepat dan tetap ramah SEO. Setelah itu, JavaScript di browser melakukan hydration: framework memasang event handler dan menyambungkan state ke markup yang sudah ada. Proses ini mengasumsikan bahwa render awal di client identik dengan render dari server.

UI game sering melanggar asumsi tersebut karena:

  • ada pemilihan karakter, kartu, pertanyaan, atau rekomendasi secara acak saat render;
  • timer, countdown, dan label berbasis waktu dihitung langsung saat render;
  • progress pemain dibaca dari localStorage sebelum hydration selesai;
  • format tanggal, angka, atau teks bergantung locale browser;
  • komponen tertentu hanya muncul jika perangkat mendukung pointer, audio, viewport tertentu, atau API browser spesifik.

Prinsip dasarnya sederhana: jangan biarkan render SSR bergantung pada nilai yang hanya diketahui browser atau berubah dari waktu ke waktu, kecuali Anda sengaja menunda render bagian itu sampai di client.

Gejala hydration mismatch pada game SSR

Gejala yang umum tidak selalu berupa error besar. Sering kali hanya warning di console, tetapi dampaknya bisa nyata pada UX:

  • warning seperti Text content does not match server-rendered HTML;
  • pilihan kartu/hero/item pertama berbeda antara server dan browser;
  • skor awal atau progress level berubah setelah halaman selesai dimuat;
  • komponen seperti minimap, inventory, atau dialog muncul/hilang sesaat;
  • animasi dimulai dari frame atau state yang berbeda;
  • event handler terasa aneh karena framework terpaksa membuang DOM lama dan merender ulang.

Pada beberapa framework, mismatch kecil bisa dipulihkan otomatis. Namun tetap berbahaya karena menyebabkan re-render yang tidak perlu, flicker, dan bug yang sulit direproduksi.

Penyebab nyata yang paling sering

1. Math.random() dipanggil saat render

Ini penyebab klasik pada game. Misalnya server memilih satu dari enam challenge, sementara browser memilih challenge lain saat hydration.

// Sebelum: rentan mismatch
function DailyCard() {
  const card = cards[Math.floor(Math.random() * cards.length)]
  return <div>{card.title}</div>
}

Mengapa bermasalah? Karena server dan client hampir pasti menghasilkan angka acak yang berbeda.

2. Date.now() atau waktu saat ini dipakai langsung di render

Contohnya countdown, label “hari ini”, atau rotasi konten harian yang dihitung dari waktu saat render.

// Sebelum: timestamp bisa berbeda beberapa ms atau lebih
function DailySeed() {
  const seed = Math.floor(Date.now() / 86400000)
  return <div>Seed: {seed}</div>
}

Walau selisihnya kecil, hasil akhirnya bisa berbeda, apalagi jika ada pembulatan ke menit, hari, atau timezone.

3. Membaca localStorage pada initial render

Pada SSR, localStorage tidak tersedia. Developer lalu membuat fallback di server, tetapi browser membaca nilai asli saat hydration. Hasilnya, UI awal berbeda.

// Sebelum: server pakai default 0, client bisa baca skor lama 1200
function ScoreBadge() {
  const best = typeof window !== 'undefined'
    ? Number(localStorage.getItem('best-score') || 0)
    : 0

  return <span>Best score: {best}</span>
}

4. Perbedaan timezone dan locale

Format tanggal/jam dan bahkan beberapa hasil format angka bisa berbeda antara lingkungan server dan browser pengguna. Jika Anda merender teks terformat di server dan browser menghitung ulang dengan locale berbeda, mismatch bisa muncul.

// Sebelum: locale/timezone mungkin berbeda
function EventTime({ startsAt }) {
  const text = new Date(startsAt).toLocaleString()
  return <p>Mulai: {text}</p>
}

5. State persisted yang langsung mengubah UI awal

Misalnya pemain terakhir memilih mode “hard”, tema tertentu, atau sudah membuka beberapa level. Jika state persisted di-load terlalu awal dan memengaruhi struktur DOM, server dan client akan menampilkan layout yang berbeda.

6. Conditional render berbasis browser API

Contohnya:

  • window.innerWidth untuk memilih layout mobile/desktop;
  • matchMedia('(prefers-reduced-motion)') untuk mengubah animasi;
  • navigator.userAgent, navigator.language, atau kemampuan perangkat;
  • API audio, canvas, pointer, vibration, atau gamepad.

Jika kondisi ini dievaluasi saat render SSR dan initial render client, hasilnya mudah berbeda.

Cara mereproduksi masalah dengan sengaja

Sebelum memperbaiki, pastikan Anda bisa memicu bug secara konsisten. Pada proyek game SSR, langkah ini jauh lebih efektif daripada menebak-nebak.

  1. Matikan cache dan buka console browser. Perhatikan warning hydration, bukan hanya tampilan visual.
  2. Reload berkali-kali. Bug berbasis Math.random() dan waktu sering muncul sporadis.
  3. Uji timezone dan locale berbeda. Jalankan server pada timezone default yang berbeda dari mesin lokal, atau ubah locale browser.
  4. Isi state persisted. Tambahkan data di localStorage agar UI client punya kondisi berbeda dari server.
  5. Throttle jaringan/CPU. Ini membantu melihat flicker antara HTML SSR dan UI sesudah hydration.
  6. Bandingkan View Source vs DOM akhir. HTML server dapat dilihat dari source, sedangkan DOM hasil hydration terlihat di devtools.

Jika perlu, buat komponen kecil yang hanya berisi satu sumber nondeterministik. Dengan begitu Anda bisa memverifikasi penyebab secara terisolasi sebelum menyentuh komponen besar seperti homepage arcade atau dashboard permainan.

Checklist debugging hydration mismatch

Gunakan checklist berikut saat mendiagnosis layar game yang bermasalah:

  • Apakah ada Math.random(), Date.now(), new Date(), atau generator ID di dalam fungsi render?
  • Apakah initial state mengambil data dari window, document, localStorage, sessionStorage, atau navigator?
  • Apakah ada format tanggal/angka yang bergantung locale browser?
  • Apakah ada percabangan seperti if (typeof window !== 'undefined') yang tetap mengubah markup awal?
  • Apakah persisted state mengubah urutan elemen, jumlah node, atau teks awal?
  • Apakah library pihak ketiga merender konten berbeda di client, misalnya chart, animation, canvas wrapper, atau komponen media?
  • Apakah key list berubah-ubah pada setiap render?

Prinsip penting: warning hydration biasanya bukan akar masalah, melainkan gejala dari render awal yang tidak deterministik.

Pola perbaikan yang aman dan framework-agnostik

1. Buat render awal deterministik

Perbaikan terbaik adalah memastikan server dan client menerima input awal yang sama. Jika Anda butuh konten acak, hasil acaknya harus ditentukan dari luar render, lalu dikirim sebagai data yang stabil.

// Sesudah: server menentukan seed atau cardId, client memakai nilai yang sama
function DailyCard({ initialCardId }) {
  const card = cards.find(c => c.id === initialCardId)
  return <div>{card.title}</div>
}

Seed bisa berasal dari backend, route loader, cookie, atau hash yang stabil. Keuntungannya:

  • markup SSR dan client sinkron;
  • mudah diuji;
  • hasil dapat direproduksi saat debugging atau replay.

Trade-off: Anda perlu sumber data awal yang eksplisit. Ini sedikit menambah kompleksitas dibanding memanggil Math.random() langsung.

2. Tunda akses browser-only state sampai komponen terpasang di client

Untuk data seperti localStorage, baca nilainya setelah mount, lalu tampilkan fallback SSR yang stabil.

// Pola generik sesudah
function ScoreBadge() {
  const [best, setBest] = useState(0)
  const [ready, setReady] = useState(false)

  useEffect(() => {
    const value = Number(localStorage.getItem('best-score') || 0)
    setBest(value)
    setReady(true)
  }, [])

  return <span>Best score: {ready ? best : 0}</span>
}

Mengapa ini bekerja? Karena HTML SSR dan render awal client sama-sama menampilkan nilai fallback yang identik. Setelah hydration selesai, state boleh diperbarui.

Trade-off: bisa muncul perubahan UI setelah mount. Untuk elemen penting, gunakan placeholder yang jelas atau skeleton kecil agar perubahan terasa wajar.

3. Pisahkan data presentasi dari data lingkungan

Jika label waktu harus ramah locale pengguna, ada dua opsi aman:

  • render format yang stabil di server, misalnya ISO atau UTC;
  • atau render placeholder di SSR lalu format lokal setelah mount.
// Sesudah: server kirim string stabil, client boleh mempercantik kemudian
function EventTime({ startsAtIso }) {
  return <p>Mulai: {startsAtIso}</p>
}

Jika Anda ingin format lokal pengguna, lakukan enhancement setelah hydration, bukan pada render SSR awal.

4. Jangan ubah struktur DOM berdasarkan browser API pada render awal

Jika Anda perlu perilaku berbeda untuk mobile, reduced motion, atau dukungan fitur, lebih aman:

  • gunakan CSS responsif untuk layout bila memungkinkan;
  • gunakan class yang diperbarui setelah mount, bukan mengganti seluruh subtree;
  • jika komponen memang tidak bermakna di server, jadikan client-only.
// Sebelum: struktur berbeda berdasarkan window
function Controls() {
  const mobile = typeof window !== 'undefined' && window.innerWidth < 768
  return mobile ? <MobilePad /> : <KeyboardHint />
}
// Sesudah: render shell stabil, lalu upgrade di client
function Controls() {
  const [mobile, setMobile] = useState(null)

  useEffect(() => {
    setMobile(window.innerWidth < 768)
  }, [])

  if (mobile === null) return <div>Memuat kontrol...</div>
  return mobile ? <MobilePad /> : <KeyboardHint />
}

5. Sinkronkan persisted state dengan hati-hati

Persisted state seperti progress level, inventory, atau pilihan mode sebaiknya tidak langsung menentukan markup SSR kecuali data itu juga tersedia di server. Jika tidak, gunakan salah satu pola berikut:

  • SSR fallback + rehydrate after mount untuk data non-kritis;
  • cookie/server session jika state perlu konsisten sejak SSR;
  • client-only island jika seluruh widget bergantung pada browser state.

Kapan memakai client-only atau dynamic import?

Tidak semua komponen layak dipaksa SSR. Pada game web, beberapa bagian memang lebih aman dijalankan hanya di client: canvas scene, particle engine, audio visualizer, drag-and-drop berat, atau widget yang sangat tergantung browser API.

Pilih client-only jika:

  • komponen tidak punya nilai SEO;
  • render awal hampir sepenuhnya bergantung pada browser state;
  • library pihak ketiga sulit dibuat deterministik di SSR;
  • memperbaiki mismatch akan lebih kompleks daripada manfaat SSR-nya.

Pilih SSR penuh jika:

  • kontennya penting untuk SEO atau share preview;
  • screen awal adalah landing, daftar game, deskripsi quiz, atau copy pemasaran;
  • bagian interaktif bisa di-upgrade setelah markup dasar tampil stabil.

Pada Next.js, Nuxt, maupun SvelteKit, idenya sama walau API berbeda: jadikan komponen tertentu client-only atau lakukan dynamic import untuk bagian yang tidak aman di SSR. Jangan bergantung pada nama API tertentu; fokus pada pemisahan antara SSR-safe shell dan client-enhanced widget.

Aturan praktis: jika komponen membutuhkan window, ukuran viewport, storage lokal, atau engine rendering browser untuk menentukan markup awal, pertimbangkan client-only.

Pola implementasi lintas framework

Next.js

Gunakan data dari server untuk nilai awal yang harus konsisten, dan tunda akses browser API ke effect. Untuk widget yang memang browser-only, pakai pola dynamic import atau komponen client-only sesuai arsitektur aplikasi Anda.

Nuxt

Pastikan state awal yang memengaruhi template tersedia dari sisi server bila ingin SSR konsisten. Untuk bagian browser-only, gunakan pembungkus atau pola client-only yang disediakan framework, lalu pastikan fallback SSR-nya tidak menipu pengguna.

SvelteKit

Pisahkan kode yang berjalan saat SSR dan saat browser aktif. Hindari membaca API browser di evaluasi awal komponen jika nilainya menentukan markup. Jika perlu, lakukan update setelah mount atau pindahkan widget ke jalur client-only.

Meski sintaks berbeda, resepnya tetap sama:

  1. buat input render awal stabil;
  2. tunda browser-only state;
  3. gunakan client-only untuk widget yang benar-benar tidak SSR-friendly;
  4. jangan campurkan concern SEO dengan engine interaktif berat dalam subtree yang sama.

Contoh sebelum dan sesudah: kartu rekomendasi game acak

Kasus umum pada homepage arcade: server menampilkan “rekomendasi untukmu”, tetapi pilihan kartu dihitung dengan acak saat render.

// Sebelum
function Recommendation() {
  const item = games[Math.floor(Math.random() * games.length)]
  const label = new Date().toLocaleDateString()
  return (
    <section>
      <h2>Rekomendasi hari ini</h2>
      <p>{label}</p>
      <article>{item.title}</article>
    </section>
  )
}

Masalahnya ada dua: pemilihan game acak dan label tanggal lokal.

// Sesudah
function Recommendation({ featuredGameId, serverDateLabel }) {
  const item = games.find(g => g.id === featuredGameId)
  return (
    <section>
      <h2>Rekomendasi hari ini</h2>
      <p>{serverDateLabel}</p>
      <article>{item.title}</article>
    </section>
  )
}

Jika nanti Anda ingin menampilkan format tanggal lokal pengguna, lakukan pembaruan setelah hydration. Dengan begitu SSR tetap stabil, tetapi UX tetap bisa dipersonalisasi.

Trade-off UX dan SEO yang perlu dipahami

Menunda render sampai client

  • Kelebihan: menghilangkan mismatch untuk widget yang sulit dideterministikkan.
  • Kekurangan: HTML awal jadi minim, interaksi tertunda, dan manfaat SEO berkurang untuk bagian itu.

Memaksa SSR deterministik

  • Kelebihan: performa persepsi dan SEO lebih baik, tidak ada flicker jika dilakukan benar.
  • Kekurangan: butuh arsitektur data awal yang lebih rapi, kadang perlu sinkronisasi state lintas server-client.

Hybrid: SSR shell + client enhancement

  • Kelebihan: biasanya paling seimbang untuk homepage game, katalog, deskripsi permainan, dan panel ringan.
  • Kekurangan: tetap perlu mendesain fallback yang jujur dan tidak menyebabkan layout shift besar.

Untuk UI game, pendekatan hybrid sering paling masuk akal: server merender shell yang stabil, lalu browser mengaktifkan elemen interaktif, audio, animasi berat, dan state personal setelah hydration.

Kesalahan yang sering terjadi

  • Mengira typeof window !== 'undefined' otomatis aman. Aman dari crash, belum tentu aman dari mismatch, karena markup bisa tetap berbeda.
  • Memformat waktu/angka langsung di template. Ini mudah terlupakan saat testing lokal karena locale server dan browser kebetulan sama.
  • Menyimpan terlalu banyak UI state di localStorage. Persisted state yang mengubah struktur DOM sering jadi sumber masalah.
  • Mencampur landing content dengan game engine dalam satu komponen SSR. Akibatnya seluruh halaman ikut rapuh.
  • Menangani warning dengan menyembunyikan error, bukan memperbaiki determinisme render.

Checklist perbaikan cepat

  1. Hapus semua sumber nondeterministik dari render awal.
  2. Pastikan server dan client memakai data awal identik untuk konten yang di-SSR.
  3. Tunda pembacaan localStorage, ukuran viewport, dan browser API lain sampai mount.
  4. Format locale-sensitive di server secara stabil, atau lakukan enhancement setelah hydration.
  5. Gunakan client-only/dynamic import untuk widget yang memang browser-bound.
  6. Uji di locale, timezone, dan state storage yang berbeda.

Penutup

Debug hydration mismatch pada UI game SSR yang acak pada dasarnya adalah pekerjaan membuat render awal menjadi deterministik. Jika server mengirim kartu A tetapi browser menghitung kartu B, atau server menampilkan skor default sementara browser langsung membaca progress lama dari storage, mismatch hampir pasti terjadi.

Solusi yang paling tahan lama bukan sekadar membungkus kode dengan pengecekan browser, melainkan memisahkan apa yang harus konsisten saat SSR dari apa yang boleh dipersonalisasi setelah mount. Untuk halaman game interaktif, pola paling aman biasanya adalah SSR shell yang stabil, lalu enhancement di client untuk state personal, animasi berat, dan komponen yang bergantung pada browser API.