Hydration Deterministik untuk UI Status Legal di SSR

Hydration deterministik untuk UI status legal di SSR berarti HTML awal dari server harus menghasilkan markup yang sama ketika framework melakukan hydration di browser. Jika status legal atau kebijakan dapat berubah cepat—misalnya label seperti allowed, pending review, atau not recognized—perbedaan kecil antara server dan client dapat memicu hydration mismatch, UI berkedip, atau state yang salah.

Masalah ini sering terjadi bukan karena framework-nya buruk, tetapi karena sumber kebenaran UI tidak konsisten: data SSR sudah basi, format tanggal bergantung timezone browser, feature flag berbeda antara edge/server dan client, komponen membaca localStorage saat render, atau state turunan dihitung dengan aturan yang tidak identik. Untuk kasus UI status legal, inkonsistensi ini berbahaya karena pengguna bisa melihat status yang berbeda dalam beberapa ratus milidetik pertama.

Artikel ini fokus pada pola frontend yang praktis, terinspirasi dari skenario status legal yang berubah karena keputusan regulator atau pengadilan. Fokusnya bukan pada beritanya, melainkan pada cara merender status yang sensitif secara benar dan deterministik di SSR.

Mengapa UI status legal rentan terhadap hydration mismatch

Status legal biasanya terlihat sederhana, tetapi sering bergantung pada beberapa input yang berubah cepat:

Data backend terbaru: status bisa berubah setelah server merender halaman tetapi sebelum browser selesai hydration.
Locale dan timezone: label seperti “berlaku sampai 6 Maret 2026” dapat diformat berbeda antara server dan client.
Feature flag: rollout teks atau komponen baru bisa berbeda jika evaluasi flag tidak konsisten.
Preferensi lokal pengguna: misalnya disclaimer tambahan dari localStorage.
State turunan: badge warna, prioritas status, atau pesan fallback dihitung dari beberapa field dan bisa berbeda jika logika tidak sama.

Pada SSR, framework mengirim HTML awal dari server. Saat browser memuat JavaScript, framework akan mencoba “menghubungkan” event handler dan state ke HTML itu. Jika hasil render pertama di client tidak identik dengan HTML server, muncullah warning hydration mismatch. Di beberapa kasus, framework akan memperbaiki DOM; di kasus lain, node akan diganti penuh, menyebabkan layout shift atau kehilangan state.

Penyebab umum mismatch pada status legal

1. Data SSR basi

Server merender status Recognized, tetapi beberapa detik kemudian API client mengambil data baru Under Appeal. Bila komponen client langsung merender hasil fetch terbaru pada pass pertama, markup tidak lagi sama dengan HTML server.

Ini masalah klasik ketika SSR dan CSR memakai sumber data yang sama tetapi timing-nya berbeda.

2. Locale dan timezone berbeda

Server bisa berjalan di UTC, sedangkan browser pengguna di Asia/Tokyo atau Asia/Jakarta. Jika Anda merender:

<span>Effective at: {new Date(status.effectiveAt).toLocaleString()}</span>

maka string hasil render server dan client bisa berbeda walau timestamp-nya sama. Akibatnya, hydration mismatch terjadi pada node teks.

3. Feature flag dievaluasi di tempat berbeda

Misalnya flag showLegalDisclaimerV2 aktif di browser karena context pengguna sudah tersedia, tetapi server belum punya context itu atau memakai snapshot flag lama. Server merender disclaimer versi lama, client langsung merender versi baru.

4. Mengakses `window` atau `localStorage` saat render

Kasus umum:

const dismissed = localStorage.getItem('dismissed-legal-banner') === '1';

Di server, localStorage tidak ada. Developer lalu menambahkan fallback seperti false. Hasilnya, server menampilkan banner, tetapi client langsung menyembunyikannya saat hydration pertama. Ini bukan sekadar warning; struktur DOM bisa berubah total.

5. State turunan dihitung berbeda

Contoh: server menghitung warna badge dari status.code, client menghitung dari status.code dan status.expiresAt. Atau server menggunakan normalisasi string berbeda dari client. Walaupun data mentah sama, hasil UI tetap bisa berbeda.

Prinsip utama: render pertama harus memakai snapshot yang sama

Solusi paling penting adalah ini: pass render pertama di client harus menggunakan snapshot yang sama persis dengan yang dipakai server. Setelah hydration selesai, barulah Anda boleh melakukan revalidation atau memperbarui status.

Untuk UI status legal, anggap SSR menghasilkan objek snapshot seperti berikut:

{
  "id": "ai-inventorship-jp",
  "status": "pending_review",
  "updatedAt": "2026-03-06T08:30:00Z",
  "effectiveAt": "2026-03-06T00:00:00Z",
  "disclaimerVersion": "v1"
}

Snapshot ini harus menjadi input render awal di server dan client. Jangan biarkan client menghitung ulang dari sumber lain sebelum hydration selesai.

Anti-pattern yang sering memicu masalah

Anti-pattern React/Next.js

function LegalStatusCard() {
  const [status, setStatus] = useState(null);

  if (typeof window !== 'undefined') {
    const cached = window.localStorage.getItem('legal-status');
    if (cached) {
      return <StatusView data={JSON.parse(cached)} />;
    }
  }

  useEffect(() => {
    fetch('/api/legal-status')
      .then((r) => r.json())
      .then(setStatus);
  }, []);

  return <StatusView data={status} />;
}

Masalah pada contoh ini:

Render awal di client bergantung pada localStorage, tetapi server tidak.
Data awal null bisa berbeda dari HTML SSR.
Komponen bisa menampilkan struktur DOM berbeda sebelum hydration selesai.

Anti-pattern Nuxt/Vue

<script setup>
const dismissed = localStorage.getItem('dismissed-legal-banner') === '1'
const { data } = await useFetch('/api/legal-status')
</script>

<template>
  <LegalBanner v-if="!dismissed" :status="data" />
</template>

Masalahnya sama: localStorage dipakai di fase render yang tidak identik antara server dan client.

Pola perbaikan yang aman

1. Gunakan snapshot data SSR sebagai sumber kebenaran render pertama

Di React/Next.js, oper data hasil SSR sebagai initial props, lalu gunakan sebagai state awal yang stabil.

function LegalStatusCard({ initialStatus }) {
  const [status, setStatus] = useState(initialStatus);

  useEffect(() => {
    let active = true;
    fetch('/api/legal-status')
      .then((r) => r.json())
      .then((fresh) => {
        if (active) setStatus(fresh);
      })
      .catch(() => {});
    return () => {
      active = false;
    };
  }, []);

  return <StatusView data={status} />;
}

Mengapa ini bekerja:

HTML server dan render awal client sama-sama memakai initialStatus.
Update dari API terjadi setelah hydration, sehingga mismatch tidak terjadi pada pass pertama.
Anda tetap mendapat data terbaru lewat revalidation.

Di Nuxt/Vue, prinsipnya sama: pastikan data awal berasal dari payload SSR yang sama, lalu refresh setelah mounted atau melalui mekanisme revalidation yang tidak mengubah markup sebelum hydration selesai.

2. Pindahkan akses browser-only ke fase client-only

Untuk preferensi lokal seperti banner sudah ditutup atau belum, jangan baca localStorage saat render SSR. Render shell yang stabil dulu, lalu sinkronkan sesudah mounted.

Contoh React:

function LegalBanner({ initialStatus }) {
  const [dismissed, setDismissed] = useState(false);
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
    const value = window.localStorage.getItem('dismissed-legal-banner') === '1';
    setDismissed(value);
  }, []);

  if (!mounted) {
    return <div className="legal-banner-shell" aria-hidden="true" />;
  }

  if (dismissed) return null;

  return (
    <div className="legal-banner">
      <StatusView data={initialStatus} />
      <button
        onClick={() => {
          window.localStorage.setItem('dismissed-legal-banner', '1');
          setDismissed(true);
        }}
      >
        Tutup
      </button>
    </div>
  );
}

Poin pentingnya bukan sekadar memakai useEffect, tetapi menjaga struktur awal tetap stabil. Shell kosong dengan tinggi yang konsisten sering lebih aman daripada langsung menambah/menghapus node saat hydration.

3. Buat loading shell yang stabil

Jika status legal bisa sangat sering berubah, jangan menebak-nebak isi UI saat server belum yakin. Tampilkan shell yang konsisten pada server dan client, lalu isi kontennya setelah data siap.

Contoh yang aman:

function StatusView({ data }) {
  if (!data) {
    return (
      <div className="status-card skeleton">
        <div className="badge-skeleton" />
        <div className="line-skeleton" />
      </div>
    );
  }

  return (
    <div className="status-card">
      <span className={`badge badge-${data.status}`}>{data.status}</span>
      <p>Diperbarui: {data.updatedAtLabel}</p>
    </div>
  );
}

Jika shell ini dirender identik di server dan client, hydration akan stabil. Yang penting, jangan membuat server merender data lengkap sementara client pertama kali merender skeleton, atau sebaliknya.

4. Format tanggal dan angka di server, kirim hasilnya sebagai string final

Untuk konten legal, teks tanggal sering harus presisi dan konsisten. Daripada memanggil toLocaleString() di dua lingkungan yang berbeda, lebih aman membentuk string final di server atau di layer API:

{
  "status": "pending_review",
  "updatedAt": "2026-03-06T08:30:00Z",
  "updatedAtLabel": "6 Maret 2026, 17.30 JST"
}

Dengan pendekatan ini, server dan client merender string yang sama. Jika Anda memang perlu personalisasi timezone pengguna, lakukan setelah hydration dan anggap itu sebagai enhancement, bukan bagian dari render awal SSR.

5. Samakan evaluasi feature flag

Jika status legal atau disclaimer dipengaruhi feature flag, ada dua pola aman:

Evaluasi flag di server dan kirim hasilnya sebagai bagian dari snapshot SSR.
Tunda render bagian yang bergantung pada flag client-only sampai context browser tersedia.

Yang berbahaya adalah server merender berdasarkan satu set flag, sementara client merender berdasarkan evaluasi lain pada pass pertama.

6. Pusatkan logika state turunan dalam fungsi murni yang dipakai dua sisi

Jangan hitung badge, prioritas, dan teks fallback dengan logika tersebar. Buat fungsi deterministik yang menerima snapshot mentah dan mengembalikan model UI.

function deriveLegalStatusViewModel(snapshot) {
  const expired = snapshot.expiresAt
    ? new Date(snapshot.expiresAt).getTime() <= Date.now()
    : false;

  if (expired) {
    return { tone: 'warning', label: 'expired' };
  }

  switch (snapshot.status) {
    case 'recognized':
      return { tone: 'success', label: 'recognized' };
    case 'pending_review':
      return { tone: 'neutral', label: 'pending review' };
    default:
      return { tone: 'danger', label: 'not recognized' };
  }
}

Namun hati-hati: fungsi di atas masih memakai Date.now(), yang bisa berbeda antara server dan client. Untuk render pertama yang benar-benar deterministik, kirim juga nilai waktu referensi dari server:

function deriveLegalStatusViewModel(snapshot, nowEpochMs) {
  const expired = snapshot.expiresAt
    ? new Date(snapshot.expiresAt).getTime() <= nowEpochMs
    : false;

  if (expired) return { tone: 'warning', label: 'expired' };
  if (snapshot.status === 'recognized') return { tone: 'success', label: 'recognized' };
  if (snapshot.status === 'pending_review') return { tone: 'neutral', label: 'pending review' };
  return { tone: 'danger', label: 'not recognized' };
}

Dengan begitu, keputusan UI pada render awal tidak berubah hanya karena milidetik berjalan.

Strategi revalidation tanpa merusak hydration

UI status legal sering perlu diperbarui cepat, tetapi SSR yang deterministik tetap penting. Maka, pisahkan dua fase:

Fase 1: render awal deterministik memakai snapshot SSR.
Fase 2: revalidation setelah hydration untuk mengecek apakah status berubah.

Pola praktis

Gunakan data SSR sebagai initial cache atau initial state.
Lakukan fetch ulang di client setelah mounted.
Jika data berubah, perbarui UI secara eksplisit.
Untuk perubahan yang sensitif, tampilkan indikator seperti “status diperbarui baru saja” agar pergeseran status tidak membingungkan pengguna.

Trade-off-nya jelas: semakin agresif revalidation, semakin cepat UI akurat, tetapi risiko flicker setelah hydration juga meningkat. Untuk informasi legal, sering lebih baik menampilkan snapshot yang jelas dengan cap waktu pembaruan daripada mengejar update instan pada milidetik pertama.

Catatan: Jika status benar-benar kritis dan harus selalu terbaru sebelum terlihat oleh pengguna, SSR penuh mungkin bukan pilihan terbaik. Pertimbangkan halaman client-rendered dengan loading state eksplisit, atau komponen client-only untuk bagian status yang sangat dinamis.

Kapan memilih SSR, CSR, atau partial hydration

Pilih SSR jika

Status legal perlu terlihat cepat untuk SEO atau akses langsung tanpa menunggu JavaScript penuh.
Ada manfaat dari HTML awal yang lengkap, misalnya halaman kebijakan publik.
Anda bisa menjamin snapshot data awal cukup konsisten untuk beberapa detik pertama.

Pilih CSR jika

Status terlalu dinamis atau sangat personal per pengguna.
Konten bergantung berat pada browser state, session lokal, atau evaluasi flag client-side.
Anda lebih memilih loading state eksplisit daripada risiko mismatch.

Pilih partial hydration atau client-only islands jika

Sebagian besar halaman bisa stabil di SSR, tetapi widget status legal sangat dinamis.
Anda ingin mengisolasi area rawan mismatch tanpa mengorbankan keseluruhan halaman.
Disclaimer interaktif, banner dismissible, atau panel status real-time hanya perlu hidup di client.

Prinsip pemilihannya sederhana: SSR untuk bagian yang bisa dipastikan deterministik, CSR/client-only untuk bagian yang tidak bisa.

Contoh arsitektur render yang lebih aman

Alur yang disarankan

Server mengambil snapshot status legal dari API internal.
Server juga menentukan string final yang sensitif locale, seperti label tanggal.
Server mengirim snapshot itu bersama halaman SSR.
Client melakukan hydration memakai snapshot yang sama, tanpa membaca sumber data lain saat pass pertama.
Setelah mounted, client menjalankan revalidation.
Preferensi lokal seperti banner ditutup dibaca setelah mounted, dengan shell yang stabil.

Arsitektur ini meminimalkan sumber nondeterminisme pada render awal.

Checklist debugging hydration mismatch

Jika Anda melihat warning hydration pada UI status legal, periksa daftar berikut:

Apakah render awal client memakai data yang sama persis dengan SSR?
Apakah ada pemanggilan Date.now(), Math.random(), atau generator ID saat render?
Apakah ada toLocaleString(), format mata uang, atau format tanggal yang bergantung lingkungan?
Apakah komponen membaca window, document, matchMedia, atau localStorage saat render?
Apakah feature flag dievaluasi konsisten di server dan client?
Apakah urutan list, key React/Vue, atau kondisi v-if/conditional render berubah pada pass pertama?
Apakah state turunan dihitung dari fungsi yang sama di dua sisi?
Apakah ada fetch client yang mengganti data sebelum hydration selesai?
Apakah shell/loading di server dan client memiliki struktur DOM yang sama?

Tips praktis saat men-debug

Log payload snapshot SSR dan payload render awal client, lalu bandingkan byte-per-byte bila perlu.
Mulai dari menonaktifkan revalidation sementara untuk memastikan mismatch memang terjadi sebelum update client.
Ganti semua format tanggal dinamis dengan string statis sementara untuk mengisolasi masalah timezone/locale.
Pindahkan bagian yang mencurigakan ke komponen client-only untuk membuktikan sumber mismatch.
Periksa apakah warning muncul pada node teks, atribut class, atau struktur elemen; masing-masing biasanya menunjukkan penyebab berbeda.

Kesalahan desain yang sering diremehkan

Menganggap warning hydration hanya masalah kosmetik

Pada UI status legal, perbedaan singkat antara server dan client bisa menyesatkan. Badge hijau yang berubah menjadi merah sesaat kemudian bukan hanya flicker visual; itu bisa mengubah makna informasi.

Mencampur data resmi dan preferensi lokal dalam satu render awal

Status legal resmi sebaiknya dipisah dari state lokal seperti banner ditutup, ekspansi panel, atau preferensi presentasi. Data resmi cocok untuk SSR; preferensi lokal biasanya lebih aman diterapkan setelah mounted.

Memaksa semua bagian tetap SSR

Tidak semua komponen perlu SSR. Jika sebuah widget sangat dipengaruhi browser state dan berubah cepat, menjadikannya client-only sering lebih jujur dan lebih stabil.

Penutup

Hydration deterministik untuk UI status legal di SSR pada dasarnya adalah disiplin menjaga render pertama tetap identik antara server dan client. Cara paling efektif adalah memakai snapshot SSR yang sama, menunda akses browser-only sampai mounted, memakai loading shell yang stabil, dan melakukan revalidation setelah hydration.

Untuk status legal atau kebijakan yang bisa berubah cepat, fokus utamanya bukan sekadar “menghilangkan warning”, tetapi memastikan pengguna tidak melihat informasi yang kontradiktif pada momen pertama halaman dibuka. Jika sebuah bagian tidak bisa dijamin deterministik, lebih baik isolasi sebagai client-only atau gunakan CSR secara sadar daripada memaksakan SSR yang rapuh.

Quick Search

shopping_cart Keranjang