Debug hydration dari cookie consent yang mengubah DOM SSR berfokus pada satu masalah inti: server merender HTML awal yang berbeda dari render pertama di browser. Saat komponen cookie consent membaca cookie hanya di sisi client, memakai default state yang berbeda, atau menjalankan side effect terlalu cepat, proses hydration bisa gagal atau menghasilkan UI yang berkedip.

Gejalanya biasanya mudah dikenali: muncul warning hydration di console, banner consent sempat tampil lalu hilang, layout bergeser, atau tombol consent berada pada state yang tidak konsisten. Solusinya bukan sekadar “cek cookie lebih cepat”, melainkan memastikan markup awal dari server dan client pertama kali identik, lalu memindahkan logika yang bergantung pada browser ke fase yang aman.

Mengapa cookie consent sering memicu bug hydration

Pada aplikasi SSR modern, server menghasilkan HTML awal lebih dulu. Browser kemudian melakukan hydration dengan mengaitkan event listener dan state ke DOM yang sudah ada. Masalah muncul jika render awal di browser tidak cocok dengan HTML dari server.

Komponen cookie consent termasuk kandidat kuat penyebab mismatch karena statusnya sering bergantung pada:

  • Cookie yang hanya tersedia di browser pada saat tertentu.
  • Akses ke API browser seperti document.cookie, window, atau localStorage.
  • Conditional rendering yang langsung menyembunyikan atau menampilkan banner.
  • Side effect yang mengubah DOM atau state sebelum hydration stabil.

Secara sederhana, jika server merender banner terlihat tetapi browser pada render pertama memutuskan banner disembunyikan, maka struktur DOM berbeda. Dari sini muncul warning hydration, patch DOM mendadak, dan efek visual yang terlihat oleh pengguna.

Gejala yang paling sering muncul

1. UI berkedip saat halaman dimuat

Banner cookie consent tampil sesaat lalu menghilang, atau sebaliknya. Ini biasanya terjadi karena state default pada server berbeda dengan state setelah cookie dibaca di browser.

2. Warning hydration di console

Framework SSR umumnya memberi peringatan ketika teks, atribut, atau struktur elemen tidak sama antara output server dan render awal client. Pesan detailnya berbeda-beda, tetapi intinya sama: DOM awal tidak cocok.

3. Banner muncul-hilang secara acak

Pada koneksi lambat atau perangkat yang lebih lemah, perbedaan timing menjadi lebih terlihat. Banner bisa muncul sebelum state consent selesai diputuskan, lalu dirender ulang.

4. State awal tidak sinkron

Tombol “Terima”, “Tolak”, atau status panel preferensi bisa tampak tidak sesuai dengan cookie sebenarnya. Ini terjadi ketika state inisialisasi memakai asumsi yang berbeda antara server dan browser.

Akar masalah utama

Akses cookie hanya di browser

Jika komponen membaca document.cookie saat inisialisasi render client, server tidak punya informasi yang sama kecuali cookie itu juga diteruskan dan dibaca di layer SSR. Akibatnya, server dan client bisa mengambil jalur render berbeda.

Default state berbeda

Pola yang sering keliru adalah server menganggap showBanner = true, tetapi client langsung menghitung showBanner = false karena cookie ditemukan. Ini hampir pasti menimbulkan mismatch visual atau warning hydration.

Conditional rendering terlalu dini

Komponen seperti berikut tampak sederhana, tetapi berisiko tinggi pada SSR:

// Pola bermasalah (framework-agnostic pseudocode)
function CookieConsent() {
  const hasConsent = readCookieFromBrowser('cookie_consent') === 'yes';

  if (hasConsent) {
    return null;
  }

  return '<div class="cookie-banner">Kami memakai cookie...</div>';
}

Masalahnya, readCookieFromBrowser tidak dapat diandalkan pada sisi server. Jika server tetap merender banner, tetapi client pertama kali langsung mengembalikan null, struktur DOM berubah total.

Side effect mengubah state sebelum hydration stabil

Contoh lain adalah komponen yang langsung menambah class pada body, mengunci scroll, atau memindahkan elemen modal/banner ke portal sebelum hydration selesai. Walau markup utamanya tampak sama, perubahan DOM global ini bisa memicu perilaku aneh dan flicker.

Pola bermasalah yang perlu dihindari

Membaca browser state di fase render awal

// Bermasalah: render awal bergantung pada browser API
function CookieConsent() {
  const initialVisible = !document.cookie.includes('cookie_consent=yes');

  return initialVisible
    ? '<aside class="cookie-banner">...</aside>'
    : null;
}

Pola ini gagal pada SSR karena document tidak tersedia di server. Bahkan jika dibungkus pengecekan environment, hasil render server dan client pertama bisa tetap berbeda.

Inisialisasi state dengan nilai berbeda di server dan client

// Bermasalah: lazy initializer berbeda hasilnya
function createInitialConsentState() {
  if (typeof window === 'undefined') {
    return { visible: true };
  }

  return {
    visible: !document.cookie.includes('cookie_consent=yes')
  };
}

Ini terlihat aman karena tidak mengakses window di server. Namun hasilnya tetap bisa berbeda: server menghasilkan banner terlihat, client langsung menyembunyikannya pada render pertama.

Merender elemen yang benar-benar berbeda

Jika satu sisi merender null dan sisi lain merender <div>, mismatch menjadi lebih besar daripada sekadar teks atau atribut. Semakin berbeda struktur DOM, semakin besar potensi warning dan patch ulang.

Strategi aman untuk memperbaiki hydration

1. Samakan initial markup antara SSR dan render pertama client

Prinsip terpenting: HTML awal dari server harus sama dengan HTML saat client pertama kali merender komponen. Setelah hydration selesai, barulah state dari browser boleh dipakai untuk memperbarui tampilan.

Pendekatan paling aman adalah memakai state awal netral, lalu membaca cookie setelah komponen terpasang di browser.

// Pola lebih aman: initial markup stabil, browser state dibaca setelah mount
function CookieConsent() {
  const state = {
    mounted: false,
    visible: false
  };

  // render awal server dan client: sama-sama placeholder / hidden shell
  if (!state.mounted) {
    return '<div class="cookie-banner-placeholder" aria-hidden="true"></div>';
  }

  if (!state.visible) {
    return '<div class="cookie-banner-placeholder" aria-hidden="true"></div>';
  }

  return '<aside class="cookie-banner" role="dialog">Kami memakai cookie...</aside>';
}

// Setelah mount di browser:
// 1. baca cookie
// 2. tentukan visible
// 3. update UI

Intinya bukan bentuk API-nya, tetapi urutannya: render awal stabil dulu, keputusan berbasis browser belakangan.

2. Gunakan placeholder yang stabil

Jika banner dapat memengaruhi layout, placeholder membantu mengurangi layout shift dan flicker. Placeholder bisa berupa container kosong dengan tinggi minimum, bukan langsung menghilangkan elemen dari DOM.

<div class="cookie-banner-slot" aria-live="polite">
  <!-- isi setelah status consent selesai ditentukan di client -->
</div>

Dengan pola ini, server dan client sama-sama memiliki titik mount yang konsisten. Setelah state browser diketahui, isi slot dapat diperbarui tanpa mengubah struktur utama halaman secara drastis.

3. Pisahkan logika client-only dari komponen SSR

Jika pembacaan cookie, integrasi analytics, atau manipulasi DOM cukup kompleks, lebih aman memisahkan bagian client-only dari shell SSR. Shell tetap stabil di SSR, sedangkan logika browser berjalan setelah mount.

Contohnya:

  • Komponen SSR hanya merender container atau placeholder.
  • Komponen client-only menangani pembacaan cookie, event klik, penyimpanan preferensi, dan side effect seperti mengaktifkan script analytics.

Pemisahan ini mengurangi risiko komponen SSR ikut berubah berdasarkan state browser yang belum tersedia di server.

4. Tunda side effect yang memodifikasi DOM global

Menambah class pada body, membuka modal, mengunci scroll, atau memindahkan node ke portal sebaiknya dilakukan setelah hydration dan setelah keputusan visibilitas final dibuat. Jangan lakukan side effect global pada fase render.

Jika banner consent harus mengunci scroll, pastikan logika lock/unlock berjalan setelah status visibilitas benar-benar stabil di browser. Jika dilakukan terlalu dini, pengguna bisa melihat halaman “meloncat” atau kehilangan scroll tanpa sebab yang jelas.

5. Jika memungkinkan, kirim status consent dari server

Pendekatan yang paling rapi secara SSR adalah membuat server mengetahui cookie consent lalu meneruskannya ke render awal. Dengan begitu, server dan client sama-sama memulai dari state yang sama.

Trade-off-nya:

  • Perlu integrasi di layer request/server rendering.
  • Lebih kompleks jika aplikasi Anda tersebar di edge, CDN, atau arsitektur hybrid.
  • Tetap perlu kehati-hatian agar state yang di-serialize ke client sesuai dengan cookie yang dibaca saat request itu dibuat.

Jika arsitektur memungkinkan, ini sering menjadi solusi terbaik karena menghindari tebakan state awal.

Contoh perbaikan yang lebih praktis

Berikut pola framework-agnostic yang menunjukkan alur yang lebih aman:

// Tujuan:
// - SSR dan render pertama client selalu menghasilkan markup yang sama
// - cookie hanya dibaca setelah mount di browser
// - banner tidak langsung mengubah struktur DOM utama secara liar

function renderCookieConsent(state) {
  // state awal yang sama di server dan client pertama kali
  if (!state.ready) {
    return `
      <div class="cookie-consent-slot" data-state="loading" aria-hidden="true">
      </div>
    `;
  }

  if (!state.visible) {
    return `
      <div class="cookie-consent-slot" data-state="hidden" aria-hidden="true">
      </div>
    `;
  }

  return `
    <aside class="cookie-banner" role="dialog" aria-label="Persetujuan cookie">
      <p>Kami memakai cookie untuk fungsi dasar dan analitik sesuai pilihan Anda.</p>
      <button data-action="accept">Terima</button>
      <button data-action="reject">Tolak</button>
    </aside>
  `;
}

// state awal
const state = {
  ready: false,
  visible: false
};

// setelah mount di browser
function onClientMounted() {
  const hasConsent = document.cookie.includes('cookie_consent=yes');
  state.ready = true;
  state.visible = !hasConsent;
  rerender();
}

Kenapa pendekatan ini bekerja?

  • SSR dan render awal client konsisten: keduanya sama-sama merender slot kosong yang stabil.
  • Pembacaan cookie ditunda: tidak ada ketergantungan pada browser API saat HTML awal dibentuk.
  • DOM tidak berubah secara liar saat hydration: perubahan hanya terjadi setelah client benar-benar siap.

Kapan client-only rendering lebih masuk akal

Tidak semua komponen cookie consent harus dipaksa SSR penuh. Client-only rendering layak dipilih jika:

  • Banner sangat bergantung pada API browser atau SDK pihak ketiga.
  • Komponen memakai portal, modal manager, atau manipulasi DOM global yang sulit distabilkan.
  • Anda tidak butuh konten banner muncul di HTML SSR untuk SEO.
  • Tujuan utamanya adalah menghindari mismatch pada UI tambahan, bukan konten utama halaman.

Trade-off client-only rendering:

  • Banner mungkin muncul sedikit lebih lambat.
  • Perlu placeholder agar layout tidak bergeser.
  • Jika implementasinya ceroboh, tetap bisa memicu flicker meski bukan hydration mismatch murni.

Gunakan pendekatan ini saat biaya membuat state SSR dan client sinkron lebih tinggi daripada manfaatnya.

Checklist debugging hydration untuk cookie consent

  1. Bandingkan HTML SSR dengan render awal client. Jangan fokus dulu ke state setelah effect berjalan; lihat hasil render pertama.
  2. Cari akses browser API di fase render, seperti document.cookie, window, localStorage, atau ukuran viewport.
  3. Periksa default state. Apakah server mulai dari visible=true sementara client mulai dari visible=false?
  4. Audit conditional rendering. Apakah satu sisi mengembalikan null dan sisi lain menghasilkan elemen nyata?
  5. Nonaktifkan side effect global sementara seperti body scroll lock, portal, animasi awal, atau penambahan class ke root.
  6. Uji pada koneksi dan perangkat lambat. Flicker sering lebih jelas terlihat ketika hydration tertunda.
  7. Tambahkan logging terpisah untuk server dan client agar terlihat nilai state awal masing-masing.
  8. Pastikan cookie yang dipakai benar-benar tersedia saat request SSR jika Anda mencoba menyelaraskan state dari server.
  9. Periksa animasi CSS. Kadang mismatch sudah diperbaiki, tetapi transisi opacity atau transform membuat banner tampak seperti berkedip.
  10. Validasi struktur DOM akhir jika komponen memakai portal atau memindahkan node ke lokasi lain.

Kesalahan umum yang sering disangka bukan penyebab

Menganggap warning hydration hanya masalah console

Warning hydration sering disertai dampak UI nyata: event tidak terpasang seperti yang diharapkan, elemen di-patch ulang, atau state visual meloncat. Jangan menganggapnya masalah kosmetik semata.

Mengandalkan pengecekan typeof window saja

Pengecekan ini mencegah error runtime di server, tetapi tidak otomatis mencegah mismatch markup. Jika hasil render tetap berbeda, bug hydration tetap ada.

Langsung menyembunyikan banner dengan CSS tanpa memperbaiki state

CSS kadang menutupi gejala, bukan akar masalah. Warning hydration dan patch DOM masih bisa terjadi meskipun banner secara visual tidak terlalu terlihat.

Rekomendasi implementasi yang paling aman

Jika Anda ingin solusi yang umumnya aman untuk SSR modern, urutannya seperti ini:

  1. Render markup awal yang stabil baik di server maupun client pertama kali.
  2. Tunda pembacaan cookie atau browser state hingga komponen benar-benar berjalan di browser.
  3. Gunakan placeholder atau slot agar struktur DOM tetap konsisten.
  4. Pisahkan logika client-only jika ada manipulasi DOM, SDK pihak ketiga, atau side effect global.
  5. Jika memungkinkan, kirim status consent dari server agar initial state benar-benar sinkron.

Untuk banyak kasus, kombinasi placeholder stabil + pembacaan cookie setelah mount sudah cukup menghilangkan warning hydration, banner muncul-hilang, dan UI berkedip.

Penutup

Bug hydration pada cookie consent hampir selalu berakar pada satu hal: server dan client tidak sepakat tentang DOM awal. Cookie yang hanya dibaca di browser, default state yang berbeda, conditional rendering terlalu cepat, dan side effect dini adalah pemicu paling umum.

Saat melakukan debug hydration dari cookie consent yang mengubah DOM SSR, fokuslah pada konsistensi render pertama, bukan hanya pada hasil akhir setelah semua effect selesai. Jika markup awal sudah sinkron, sebagian besar gejala seperti warning hydration, flicker, dan banner muncul-hilang akan ikut hilang.