Hydration mismatch pada dashboard paket atau listing dependency yang memakai SSR hampir selalu berarti satu hal: HTML yang dikirim server tidak sama dengan hasil render pertama di browser. Pada halaman seperti registry package, daftar crate, dependency explorer, atau dashboard paket internal, masalah ini sering muncul karena data berubah sangat cepat, sorting berbeda antara server dan client, state dari localStorage, locale yang tidak konsisten, atau komponen yang diam-diam bergantung pada API browser.

Solusi utamanya bukan sekadar “memindahkan kode ke client”, melainkan menjaga HTML awal tetap deterministik, memisahkan state server dan state client dengan jelas, serta memakai fallback loading yang konsisten saat ada data atau preferensi yang baru bisa diketahui setelah halaman terpasang di browser. Ini penting pada UI bergaya registry yang terus berevolusi, karena halaman daftar paket sering menggabungkan SSR, cache, filter, personalisasi, dan data async yang berubah cepat.

Mengapa hydration mismatch sering terjadi pada dashboard paket

Dashboard paket punya karakteristik yang rawan mismatch:

  • Data berubah di antara dua render: server merender daftar versi, unduhan, atau status audit; beberapa milidetik kemudian client mengambil data terbaru dan menghasilkan urutan yang berbeda.
  • Ada preferensi pengguna: mode tampilan grid/list, filter insecure package, atau urutan sort sering disimpan di localStorage dan baru tersedia di browser.
  • Locale dan format waktu: tanggal publikasi, “2 menit lalu”, atau format angka unduhan bisa berbeda antara environment server dan browser.
  • Feature flag: server dan client bisa membaca sumber flag yang berbeda, sehingga cabang UI yang dirender tidak sama.
  • Komponen browser-only: chart, virtualized list, observer, atau widget yang menyentuh window, document, atau ukuran viewport saat render.

Dalam konteks dashboard yang terinspirasi ekosistem package registry, mismatch sering tidak langsung terlihat sebagai error fatal. Kadang gejalanya hanya berupa tombol filter “meloncat”, badge jumlah paket berubah setelah mount, atau tabel tersusun ulang sesaat setelah halaman tampil.

Gejala yang perlu dikenali

Tanda yang umum muncul

  • Peringatan hydration mismatch di console browser.
  • Teks server berbeda dengan teks client, misalnya jumlah paket, waktu relatif, atau label filter aktif.
  • Urutan item berubah sesaat setelah halaman dimuat.
  • Checkbox, tab, atau select menunjukkan nilai default berbeda dari HTML awal.
  • Komponen chart atau browser-only kosong di server lalu muncul dengan struktur DOM yang berbeda di client.

Dampak praktis

Dampaknya bukan hanya warning. Mismatch dapat menyebabkan event binding tidak stabil, DOM dibuang dan dirender ulang, performa awal menurun, dan UI tampak berkedip. Pada dashboard paket, ini mengganggu karena pengguna sering langsung berinteraksi dengan pencarian, sort, dan filter sesaat setelah halaman terbuka.

Root cause utama hydration mismatch UI

1. Waktu render berbeda

Jangan merender nilai seperti Date.now(), new Date(), atau waktu relatif langsung di template SSR jika hasilnya bisa berbeda saat hydration.

Masalah umum: server merender “baru saja”, client merender “1 menit lalu”.

Lebih aman: kirim timestamp mentah dari server, tampilkan format stabil pada HTML awal, lalu jika perlu upgrade ke format relatif setelah mount.

2. Data async berubah antara server dan client

Misalnya server merender daftar paket berdasarkan snapshot query A, tetapi client langsung refetch dan menerima query result yang lebih baru atau urutan berbeda. Jika hasil refetch mengganti DOM sebelum hydration selesai, mismatch mudah terjadi.

Kasus yang sering muncul:

  • Jumlah unduhan berubah.
  • Status security/advisory bertambah.
  • Versi terbaru paket berubah.
  • Urutan hasil sort berubah karena field yang dipakai tidak stabil.

3. Membaca localStorage saat render awal

Jika mode tampilan, filter, atau tab aktif diambil dari localStorage langsung saat render pertama, maka server tidak punya nilai itu. Akibatnya, server merender default A, client merender nilai B.

4. Feature flag tidak sinkron

Jika server mengambil flag dari cookie atau backend, tetapi client mengambil dari SDK browser atau cache lain, komponen yang tampil bisa berbeda. Hal ini sering terjadi saat meluncurkan layout baru untuk listing paket.

5. Locale dan formatting tidak konsisten

Intl, timezone, dan locale default bisa berbeda antara server dan browser. Dampaknya terlihat pada format tanggal, desimal, dan pemisah ribuan.

6. Sort/filter default tidak deterministik

Contoh sederhana: server mengurutkan berdasarkan updated_at desc, client mengurutkan berdasarkan “relevansi” atau preferensi yang tersimpan. Bahkan jika datanya sama, urutan DOM yang berbeda cukup untuk memicu mismatch.

7. Komponen browser-only ikut dirender di server

Komponen chart, virtual scroller, intersection observer, atau komponen yang menghitung ukuran viewport sebaiknya tidak menghasilkan markup SSR yang berbeda dari client. Jika tidak ada strategi khusus, lebih aman render fallback stabil di server.

Prinsip inti: buat HTML awal deterministik

Aturan paling penting untuk SSR stabil untuk dashboard paket adalah ini: render pertama di browser harus menghasilkan struktur dan isi yang sama dengan HTML server. Semua hal yang belum pasti saat SSR harus diperlakukan sebagai state lanjutan, bukan state awal.

Apa yang sebaiknya masuk ke HTML awal

  • Data hasil fetch server yang sudah dibekukan untuk request itu.
  • Default sort/filter yang eksplisit dan terdokumentasi.
  • Format teks yang stabil, misalnya tanggal ISO singkat atau string hasil formatting dari server yang tidak dihitung ulang di client.
  • Placeholder atau skeleton yang sama persis antara server dan client.

Apa yang sebaiknya ditunda sampai setelah mount

  • Preferensi dari localStorage.
  • Layout berbasis ukuran viewport.
  • Format waktu relatif yang terus berubah.
  • Feature flag yang hanya tersedia di SDK browser.
  • Komponen visual yang bergantung pada DOM API.

Checklist diagnosis cepat

  1. Bandingkan HTML server dan render awal client. Fokus pada teks, atribut, urutan list, dan kondisi if/v-if.
  2. Cari sumber nilai non-deterministik: waktu saat ini, random, locale default, ukuran layar, user preference browser.
  3. Audit fetch ganda: apakah client refetch terlalu cepat sebelum hydration selesai?
  4. Periksa default sort/filter: apakah server dan client memakai sumber default yang sama?
  5. Periksa feature flag: apakah flag dievaluasi dari sumber yang sama untuk request tersebut?
  6. Telusuri komponen browser-only: apakah ada akses ke window, document, atau observer saat render?
  7. Bekukan locale/timezone untuk output yang harus identik.

Debugging paling efektif biasanya dimulai dari komponen terkecil yang berubah, bukan dari keseluruhan halaman. Cari node DOM pertama yang berbeda, lalu telusuri data dan kondisi render yang membentuknya.

Pola perbaikan yang paling berguna

1. Pisahkan state server dan state client

Gunakan data SSR sebagai initial snapshot yang tidak diubah sebelum hydration selesai. Setelah mount, barulah sinkronkan state client seperti preferensi pengguna atau refetch background.

Pemisahan ini mencegah client mengganti isi DOM terlalu dini.

2. Gunakan fallback loading yang konsisten

Jika suatu informasi baru tersedia di browser, render placeholder yang sama di server dan client. Jangan menebak nilai browser-only di server.

Contoh yang baik:

  • Server dan client sama-sama menampilkan “Memuat preferensi tampilan...” sampai mount.
  • Server dan client sama-sama menampilkan tanggal absolut, lalu client meng-upgrade menjadi waktu relatif setelah mount.

3. Bekukan default sort/filter di server

Default sort/filter harus berasal dari satu sumber yang konsisten, misalnya query parameter request. Jika tidak ada query, pakai default server yang eksplisit, lalu biarkan client mengikuti nilai itu saat pertama kali render.

4. Serialisasikan keputusan server ke client

Jika server sudah memilih locale, feature flag, atau default tab, kirimkan keputusan itu sebagai bagian dari payload SSR agar client tidak menghitung ulang dengan aturan berbeda.

5. Tunda browser-only component

Untuk chart atau widget yang sulit dibuat SSR-identik, render fallback sederhana di server lalu mount komponen aslinya di client. Trade-off-nya adalah interaktivitas datang sedikit lebih lambat, tetapi hydration jadi stabil.

6. Hindari formatting ulang yang tidak perlu

Jika server sudah menghasilkan string yang tampil di HTML awal, jangan format ulang pada render pertama client kecuali input dan aturan formatting benar-benar identik.

Contoh Next.js: localStorage, sort default, dan waktu relatif

Contoh berikut menunjukkan pola aman: server mengirim snapshot data dan default sort yang eksplisit; client baru membaca preferensi browser setelah mount.

// Server Component / page-level SSR pseudo-pattern
export default async function PackagesPage({ searchParams }) {
  const sort = searchParams.sort || 'latest';
  const packagesData = await fetchPackages({ sort });

  return (
    <PackagesScreen
      initialPackages={packagesData.items}
      initialSort={sort}
      generatedAt={packagesData.generatedAt}
    />
  );
}
'use client';

import { useEffect, useMemo, useState } from 'react';

export default function PackagesScreen({ initialPackages, initialSort, generatedAt }) {
  const [mounted, setMounted] = useState(false);
  const [viewMode, setViewMode] = useState('table'); // default SSR-safe
  const [sort, setSort] = useState(initialSort);

  useEffect(() => {
    setMounted(true);
    const saved = window.localStorage.getItem('pkg:view-mode');
    if (saved === 'table' || saved === 'grid') setViewMode(saved);
  }, []);

  useEffect(() => {
    if (mounted) {
      window.localStorage.setItem('pkg:view-mode', viewMode);
    }
  }, [mounted, viewMode]);

  const items = useMemo(() => {
    // render awal client tetap identik karena sort berasal dari server
    return [...initialPackages];
  }, [initialPackages]);

  return (
    <div>
      <header>
        <select value={sort} onChange={(e) => setSort(e.target.value)}>
          <option value="latest">Terbaru</option>
          <option value="downloads">Unduhan</option>
        </select>

        {mounted ? (
          <button onClick={() => setViewMode(viewMode === 'table' ? 'grid' : 'table')}>
            Mode: {viewMode}
          </button>
        ) : (
          <button disabled>Mode: table</button>
        )}
      </header>

      <p>Snapshot dibuat: {generatedAt}</p>

      <ul data-view={viewMode}>
        {items.map((pkg) => (
          <li key={pkg.name}>
            <strong>{pkg.name}</strong> — v{pkg.version}
          </li>
        ))}
      </ul>
    </div>
  );
}

Mengapa pola ini aman:

  • initialSort datang dari request server, jadi render awal identik.
  • viewMode dari localStorage tidak dipakai untuk mengubah HTML sebelum mount.
  • generatedAt ditampilkan sebagai string snapshot, bukan dihitung ulang dengan Date.now().

Varian untuk komponen browser-only di Next.js

Jika ada chart statistik unduhan yang butuh API browser, gunakan fallback SSR yang sederhana.

'use client';

import dynamic from 'next/dynamic';

const DownloadsChart = dynamic(() => import('./DownloadsChart'), {
  ssr: false,
  loading: () => <div>Memuat grafik unduhan...</div>
});

export function PackageInsights() {
  return <DownloadsChart />;
}

Trade-off pendekatan ini adalah chart tidak ikut SSR, tetapi Anda menghindari mismatch untuk komponen yang memang tidak stabil saat dirender di server.

Contoh Nuxt.js: data SSR, locale, dan client-only

Pada Nuxt.js, prinsipnya sama: data awal diambil di server, keputusan awal dipertahankan untuk hydration, dan hal browser-only dipisahkan dengan jelas.

<script setup>
const route = useRoute()
const sort = computed(() => route.query.sort || 'latest')

const { data } = await useAsyncData('packages', () =>
  $fetch('/api/packages', { params: { sort: sort.value } })
)

const mounted = ref(false)
const viewMode = ref('table')

onMounted(() => {
  mounted.value = true
  const saved = localStorage.getItem('pkg:view-mode')
  if (saved === 'table' || saved === 'grid') viewMode.value = saved
})
</script>

<template>
  <section>
    <p>Sort awal: {{ sort }}</p>

    <button v-if="mounted">Mode: {{ viewMode }}</button>
    <button v-else disabled>Mode: table</button>

    <ul>
      <li v-for="pkg in data.items" :key="pkg.name">
        <strong>{{ pkg.name }}</strong> — v{{ pkg.version }}
      </li>
    </ul>

    <ClientOnly fallback-tag="div" fallback="Memuat grafik unduhan...">
      <DownloadsChart :series="data.downloadSeries" />
    </ClientOnly>
  </section>
</template>

Catatan penting: jika locale dipakai untuk format tanggal atau angka, usahakan locale awal berasal dari request yang sama dan dipakai baik di server maupun client. Jangan biarkan server memakai locale default environment, lalu client memakai locale browser tanpa sinkronisasi.

Pola khusus untuk sumber mismatch yang sering diabaikan

Feature flag

Jangan evaluasi flag dua kali dengan sumber berbeda pada render awal. Jika server sudah memutuskan bahwa kolom “advisory status” aktif, kirim hasil keputusan itu ke client sebagai bagian dari payload. Client boleh refresh flag kemudian, tetapi jangan mengubah cabang UI sebelum hydration selesai tanpa fallback yang konsisten.

Locale dan timezone

Untuk HTML awal, lebih aman gunakan salah satu dari dua pendekatan:

  • Server-authored string: server mengirim string final yang ditampilkan apa adanya.
  • Locale terserialisasi: server mengirim locale dan timezone yang dipakai, lalu client memakai parameter yang sama saat render pertama.

Hindari mengandalkan timezone lokal browser untuk elemen yang ikut SSR jika hasilnya bisa berbeda.

Sorting yang tidak stabil

Jika dua paket punya nilai sort utama yang sama, tambahkan tie-breaker yang stabil, misalnya nama paket. Tanpa tie-breaker, urutan item bisa berubah antar environment atau antar fetch, dan itu cukup untuk memicu mismatch visual maupun DOM.

Refetch terlalu agresif

Refetch background tetap berguna, tetapi lakukan setelah hydration stabil. Jika data memang harus real-time, gunakan indikator “data diperbarui” dan biarkan update terjadi sebagai transisi state yang jelas, bukan mengganti snapshot awal sebelum mount selesai.

Kesalahan umum yang sering membuat perbaikan gagal

  • Menyembunyikan warning tanpa memperbaiki penyebab. Ini hanya menutupi mismatch, bukan menghilangkan DOM yang tidak konsisten.
  • Menggunakan nilai browser di default state render. Misalnya useState(() => localStorage.getItem(...)) untuk komponen yang juga di-SSR.
  • Menghitung waktu relatif saat render di kedua sisi.
  • Mengubah urutan list dengan efek samping client sebelum hydration selesai.
  • Mencampur sumber kebenaran untuk sort/filter antara URL, cache client, dan storage tanpa prioritas yang jelas.

Checklist implementasi untuk SSR stabil

  1. Tentukan sumber kebenaran render awal: request URL, payload SSR, dan keputusan server.
  2. Pastikan sort/filter default eksplisit dan sama di server-client.
  3. Jangan baca localStorage, viewport, atau waktu berjalan untuk membentuk HTML awal.
  4. Render fallback yang identik untuk state yang baru diketahui di browser.
  5. Gunakan snapshot data server untuk hydration, lalu refetch setelah mount bila perlu.
  6. Serialisasikan locale, flag, dan keputusan tampilan awal bila digunakan pada SSR.
  7. Pisahkan komponen browser-only dengan boundary yang jelas.
  8. Tambahkan tie-breaker pada sorting agar urutan list stabil.

Penutup

Pada dashboard paket, hydration mismatch UI hampir selalu berakar pada render awal yang tidak deterministik. Cara paling andal untuk mencegahnya adalah menjaga HTML SSR sebagai snapshot yang stabil, memisahkan state server dari preferensi client, dan menunda hal-hal browser-only sampai setelah mount dengan fallback yang konsisten.

Jika Anda mengelola halaman listing dependency, package registry, atau dashboard internal yang datanya cepat berubah, anggap SSR bukan sekadar optimasi render, tetapi kontrak konsistensi antara server dan browser. Selama render pertama mematuhi kontrak itu, hydration akan jauh lebih stabil dan debugging menjadi lebih sederhana.