Debug UI Terminal SSR sering menjadi masalah saat dashboard atau widget statistik live dirender di server, lalu langsung berubah ketika JavaScript aktif di browser. Gejalanya biasanya berupa warning hydration, angka yang “meloncat”, format waktu berbeda, atau layout terminal yang pecah sesaat setelah halaman dimuat.

Jika Anda menampilkan statistik live bergaya terminal, penyebab utamanya hampir selalu sama: HTML hasil SSR tidak identik dengan render pertama di client. Solusinya bukan sekadar “matikan SSR”, melainkan memastikan render awal stabil melalui server snapshot, client boundary, placeholder yang konsisten, dan pemisahan state yang benar-benar derivatif dari state utama.

Apa yang sebenarnya mismatch pada hydration?

Pada arsitektur SSR, server mengirim HTML awal agar halaman cepat tampil dan tetap ramah SEO. Setelah itu, framework di browser melakukan hydration: memasang event handler dan menyelaraskan tree komponen dengan HTML yang sudah ada.

Masalah muncul ketika render pertama di client menghasilkan output berbeda dari HTML server. Untuk UI statistik live bergaya terminal, perbedaan kecil pun cukup untuk memicu warning atau re-render penuh, misalnya:

  • timestamp server menampilkan 10:15:01, client menampilkan 10:15:02
  • format angka server memakai locale default server, client memakai locale browser
  • nilai acak untuk efek terminal berbeda antara server dan browser
  • komponen langsung polling sebelum hydration selesai
  • jumlah kolom terminal dihitung dari lebar viewport yang hanya diketahui di browser

Prinsip dasarnya: render pertama di client harus identik dengan hasil SSR. Data live boleh berubah, tetapi perubahan itu sebaiknya terjadi setelah hydration selesai.

Gejala umum pada UI terminal statistik live

1. Warning hydration di console

Pada React/Next.js, Anda bisa melihat pesan seperti teks konten tidak cocok atau hydration gagal. Pada Vue/Nuxt, gejalanya mirip: DOM dirender ulang karena hasil server dan client berbeda.

2. Angka atau teks berubah tepat setelah load

Contoh yang sering terlihat:

  • jumlah views naik 1-2 angka begitu aplikasi hidup
  • “updated 3s ago” berubah menjadi “updated 4s ago” sebelum interaksi apa pun
  • baris terminal yang tadinya sejajar menjadi bergeser

3. Layout terminal flicker

Efek terminal sering memakai font monospace, alignment berbasis jumlah karakter, dan pemotongan teks berdasarkan lebar. Jika server menebak layout secara berbeda dari client, tampilan akan flicker atau melompat.

Root cause yang paling sering

Waktu dan relative time

Ekspresi seperti Date.now(), new Date(), atau label relatif semacam “5 detik lalu” hampir pasti memicu mismatch jika dievaluasi saat SSR dan saat render pertama di client. Selisih satu detik saja sudah cukup.

Masalah: waktu terus bergerak, sedangkan SSR menghasilkan snapshot statis.

Perbaikan: kirim timestamp snapshot dari server, lalu hitung relative time di client hanya setelah hydration.

Locale dan format angka/tanggal

toLocaleString() dan Intl.DateTimeFormat dapat menghasilkan output berbeda tergantung locale, timezone, dan environment runtime. Server bisa berjalan pada locale tertentu, sementara browser mengikuti preferensi pengguna.

Masalah: format 1,234 vs 1.234, atau nama bulan yang berbeda.

Perbaikan: gunakan format deterministik saat SSR, atau kirim nilai mentah dari server dan format ulang setelah hydration jika memang harus mengikuti locale user.

Nilai acak

Efek terminal kadang memakai nilai acak untuk spinner, noise, ID unik, urutan pesan, atau dekorasi ASCII. Menggunakan Math.random() saat render hampir pasti tidak stabil.

Masalah: server dan client menghasilkan angka acak berbeda.

Perbaikan: jangan gunakan random pada render SSR, atau seed nilai acak dari server dan gunakan hasil yang sama di client.

Polling data terlalu cepat

Komponen statistik live sering langsung memanggil API untuk refresh data. Jika polling dimulai sebelum hydration stabil, UI bisa berubah sebelum framework selesai menyelaraskan DOM.

Masalah: data awal SSR berbeda dari data polling pertama.

Perbaikan: gunakan snapshot server sebagai state awal, lalu mulai polling setelah komponen mounted.

Ukuran viewport dan media query berbasis JavaScript

UI terminal sering menghitung jumlah kolom dari window.innerWidth, menentukan apakah panel diringkas, atau menyembunyikan kolom saat layar kecil.

Masalah: server tidak punya akses ke ukuran viewport nyata.

Perbaikan: buat layout SSR yang stabil dan responsif via CSS terlebih dahulu; jika perlu pengukuran JavaScript, lakukan setelah mount.

Akses API atau object yang hanya ada di client

Contoh klasik: window, document, localStorage, matchMedia, atau pembacaan token dari browser untuk memanggil API privat.

Masalah: kode SSR tidak bisa mengakses API tersebut, sehingga fallback server berbeda dari hasil client.

Perbaikan: pindahkan logika ini ke boundary khusus client.

Pola perbaikan yang paling efektif

1. Gunakan snapshot data dari server sebagai sumber render awal

Untuk statistik live, anggap SSR sebagai snapshot, bukan stream. Server mengambil data sekali, merender HTML dari snapshot tersebut, lalu client memakai snapshot yang sama sebagai initial state.

Kenapa ini bekerja? Karena server dan client memulai dari data identik. Perubahan live baru masuk setelah hydration selesai.

// Contoh pola umum: data awal dari server dipakai apa adanya saat render pertama
const initialStats = {
  views: 12840,
  likes: 532,
  updatedAt: "2026-08-10T10:15:00.000Z"
};

Jika Anda memakai Next.js, Nuxt, atau Inertia, prinsipnya sama: jangan fetch ulang data yang sama di render pertama client dengan hasil yang bisa berbeda.

2. Pisahkan area interaktif ke client boundary

Jika sebagian UI benar-benar bergantung pada browser, jangan paksa SSR penuh untuk bagian itu. Render shell terminal secara server-side, lalu letakkan area live di boundary client.

Ini cocok untuk:

  • relative time yang berubah tiap detik
  • grafik kecil yang butuh ukuran container aktual
  • efek terminal berbasis animasi browser
  • akses token/API yang hanya ada di client

Trade-off-nya, semakin banyak area yang dipindahkan ke client-only, semakin kecil manfaat SSR untuk konten tersebut.

3. Tampilkan placeholder yang stabil

Placeholder bukan sekadar loading spinner. Dalam konteks SSR, placeholder harus deterministik: server dan client menampilkan hal yang sama sebelum data live aktif.

Contoh yang baik:

  • Updated: -- sampai komponen mounted
  • kolom terminal dengan lebar tetap dan teks placeholder
  • angka snapshot tanpa animasi count-up pada render awal

Contoh yang buruk:

  • placeholder yang sendiri memakai timestamp berjalan
  • skeleton yang berubah berdasarkan viewport JS sebelum mount

4. Gunakan suppress hydration warning hanya bila mismatch memang tidak berbahaya

Pada beberapa kasus, Anda tahu ada bagian kecil yang akan berbeda, misalnya timestamp relatif yang hanya dekoratif. Menyembunyikan warning bisa diterima jika elemen tersebut kecil, terisolasi, dan tidak memengaruhi struktur DOM atau makna utama halaman.

Namun ini bukan solusi utama. Jika warning disembunyikan terlalu dini, Anda bisa menutupi bug arsitektur yang lebih besar, seperti fetch ganda atau render yang nondeterministik.

5. Pisahkan state utama dan state derivatif

Ini salah satu perbaikan yang sering terlewat. State utama adalah data snapshot atau hasil polling. State derivatif adalah presentasi yang dihitung dari state utama, misalnya:

  • label “3 detik lalu”
  • format angka singkat seperti 12.8k
  • warna indikator naik/turun
  • bar terminal yang panjangnya dihitung dari container

Jika state derivatif dihitung saat SSR menggunakan context yang berbeda dari browser, mismatch mudah terjadi. Simpan data mentah sebagai sumber kebenaran, lalu hitung derivatif di tempat yang aman.

Contoh praktis pada Next.js, Nuxt, dan Inertia

Next.js: snapshot server + polling setelah mount

import { useEffect, useState } from 'react';

function TerminalStats({ initialStats }) {
  const [stats, setStats] = useState(initialStats);
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  useEffect(() => {
    if (!mounted) return;

    const id = setInterval(async () => {
      const res = await fetch('/api/stats');
      const next = await res.json();
      setStats(next);
    }, 10000);

    return () => clearInterval(id);
  }, [mounted]);

  return (
    <pre>
      <code>
{`views     ${stats.views}
likes     ${stats.likes}
updated   ${mounted ? formatRelative(stats.updatedAt) : '---'}`}
      </code>
    </pre>
  );
}

function formatRelative(iso) {
  const diff = Math.max(0, Math.floor((Date.now() - new Date(iso).getTime()) / 1000));
  return `${diff}s ago`;
}

export default TerminalStats;

Yang penting dari contoh ini:

  • initialStats dipakai sebagai render awal
  • polling baru dimulai setelah mount
  • relative time tidak dihitung saat render SSR

Nuxt/Vue: hindari pembacaan viewport saat SSR

<script setup>
import { ref, computed, onMounted, onBeforeUnmount } from 'vue'

const props = defineProps({ initialStats: Object })
const stats = ref(props.initialStats)
const width = ref(null)

const compact = computed(() => width.value !== null && width.value < 640)

function onResize() {
  width.value = window.innerWidth
}

onMounted(() => {
  onResize()
  window.addEventListener('resize', onResize)
})

onBeforeUnmount(() => {
  window.removeEventListener('resize', onResize)
})
</script>

<template>
  <pre><code>
views   {{ stats.views }}
mode    {{ compact ? 'compact' : 'default' }}
  </code></pre>
</template>

Pola di atas masih perlu perhatian: sebelum mounted, compact akan bernilai default. Agar SSR tetap stabil, pastikan mode default memang aman dirender di server. Jika perbedaan mode akan mengubah struktur markup besar, lebih baik tunda bagian itu sampai client siap.

Inertia: props server sebagai single source of truth awal

Pada Inertia, masalahnya sering muncul ketika props dari server sudah ada, tetapi komponen frontend langsung fetch lagi di setup atau mount dan mengganti nilai terlalu cepat.

// Prinsip umum, bukan bergantung pada adapter tertentu
const props = usePage().props
const stats = ref(props.stats)
const hydrated = ref(false)

onMounted(() => {
  hydrated.value = true
  refreshStats()
})

Gunakan props server sebagai data awal. Jika perlu refresh, lakukan setelah komponen aktif, bukan saat render pertama masih menyelaraskan hasil SSR.

Kesalahan yang sering dilakukan

  • Memanggil Date.now() langsung di template/render. Ini nyaris selalu nondeterministik.
  • Menggunakan Math.random() untuk key atau dekorasi UI. Key harus stabil, dekorasi acak harus ditunda atau diseed.
  • Format locale di server tanpa kontrol locale/timezone. Hasil bisa berbeda dari browser pengguna.
  • Memulai polling terlalu dini. Data berubah sebelum hydration selesai.
  • Membaca window.innerWidth untuk menentukan struktur markup SSR. Server tidak tahu viewport sebenarnya.
  • Menyembunyikan warning tanpa memahami penyebabnya. Ini membuat bug lebih sulit dilacak.

Checklist debugging hydration mismatch

  1. Bandingkan HTML SSR dengan render pertama client. Fokus pada teks, atribut, dan urutan node.
  2. Cari sumber nilai nondeterministik. Audit penggunaan waktu, random, locale, timezone, dan viewport.
  3. Nonaktifkan polling sementara. Jika mismatch hilang, berarti data live masuk terlalu cepat.
  4. Log initial props dan state awal. Pastikan client benar-benar memakai snapshot yang sama dari server.
  5. Periksa format angka/tanggal. Gunakan format mentah dulu untuk mengisolasi masalah locale.
  6. Uji pada timezone dan browser berbeda. Bug locale sering tidak muncul di mesin pengembang sendiri.
  7. Isolasi komponen terminal. Render versi minimal tanpa animasi, tanpa relative time, tanpa viewport logic.
  8. Periksa key list. Key yang berubah antar-render dapat memicu DOM bergeser.
  9. Gunakan boundary client untuk bagian yang memang browser-only. Jangan paksa SSR pada blok yang tidak deterministik.
  10. Baru pertimbangkan suppress warning. Hanya setelah penyebab dipahami dan risikonya kecil.

Kapan suppress hydration warning masuk akal?

Gunakan hanya untuk konten kecil yang memang boleh berbeda dan tidak memengaruhi struktur utama, misalnya label waktu relatif dekoratif. Hindari untuk:

  • angka statistik utama
  • markup list atau tabel
  • struktur panel terminal
  • elemen yang memengaruhi aksesibilitas atau SEO

Jika perbedaan menyentuh data inti, perbaiki arsitekturnya, bukan warning-nya.

Trade-off SEO vs interaktivitas

Untuk statistik live bergaya terminal, ada kompromi nyata antara SSR yang kaya dan interaktivitas penuh di client.

Pilih SSR penuh bila:

  • angka utama penting untuk indeksasi atau preview HTML awal
  • konten harus tampil cepat tanpa menunggu JavaScript
  • Anda bisa menyediakan snapshot yang stabil

Pilih client boundary lebih luas bila:

  • UI sangat bergantung pada viewport, animasi, atau API browser
  • data berubah sangat cepat dan snapshot cepat basi
  • bagian live lebih penting daripada keterbacaan HTML awal

Pendekatan yang paling seimbang biasanya adalah SSR untuk shell dan snapshot utama, lalu client untuk pembaruan live dan presentasi derivatif. Dengan begitu, halaman tetap cepat, indeksabel, dan tidak rapuh saat hydration.

Penutup

Pada UI terminal statistik live, mismatch SSR hampir selalu berakar pada render yang tidak deterministik. Waktu, locale, random value, polling, viewport, dan API client-only adalah penyebab paling umum. Cara paling aman untuk mencegahnya adalah memulai dari snapshot server yang stabil, menunda bagian browser-only ke client boundary, memakai placeholder yang konsisten, dan memisahkan state mentah dari state derivatif.

Jika Anda sedang debug UI Terminal SSR, jangan langsung mematikan SSR atau membungkam warning. Mulailah dari pertanyaan sederhana: apakah server dan client benar-benar merender hal yang sama pada render pertama? Hampir selalu, jawaban dari pertanyaan itu akan membawa Anda ke akar masalahnya.