Mencegah hydration drift pada SSR untuk suite dokumen web berarti memastikan HTML yang dikirim server sama dengan hasil render awal di client, terutama pada area sensitif seperti toolbar editor, preview dokumen, status kolaborasi, dan posisi elemen interaktif. Jika output awal berbeda, framework akan memunculkan hydration mismatch, membuang subtree tertentu, atau melakukan patch DOM yang membuat UI terlihat meloncat, tombol toolbar berubah status, atau preview dokumen tidak stabil.

Dalam konteks aplikasi office atau document editor, masalah ini lebih terasa dibanding aplikasi biasa. Pengguna mengharapkan dokumen terlihat sama saat pertama dibuka, baik dari server maupun setelah JavaScript aktif. Tren narasi open letter to office suite users dapat dibaca sebagai tuntutan UX: pengguna ingin antarmuka dokumen yang konsisten, dapat diprediksi, dan tidak berubah sendiri beberapa ratus milidetik setelah halaman tampil. Di situlah disiplin SSR dan hydration menjadi penting.

Apa itu hydration drift dan mengapa berbahaya untuk editor dokumen

Hydration drift adalah kondisi ketika render awal di client tidak identik dengan markup SSR. Framework modern memang berusaha merekonsiliasi perbedaan, tetapi pada editor dokumen efeknya sering merusak persepsi kualitas:

  • Toolbar berubah status: tombol bold/italic awalnya nonaktif lalu tiba-tiba aktif.
  • Preview dokumen bergeser: line break, heading, atau daftar berubah setelah hydration.
  • Cursor atau selection overlay salah posisi: terutama jika overlay dihitung memakai ukuran DOM yang hanya tersedia di browser.
  • Panel komentar atau presence berubah urutan: jika data awal berbeda antara server dan client.
  • Peringatan hydration mismatch di console, lalu subtree dirender ulang secara paksa.

Pada aplikasi dokumen, drift kecil pun terasa besar karena pengguna sedang membaca atau menulis konten. Bahkan perubahan satu ikon toolbar atau satu paragraf preview setelah hydration bisa merusak kepercayaan pengguna terhadap isi dokumen.

Penyebab umum hydration drift pada SSR

1. State awal berbeda antara server dan client

Ini penyebab paling umum. Server merender dokumen dengan state A, tetapi client memulai dengan state B karena membaca data dari sumber lain, menghitung ulang default, atau melakukan fetch tambahan sebelum hydration selesai.

Contoh gejala:

  • Server menganggap mode editor adalah read, client langsung mengubah ke edit.
  • Server merender dokumen versi cache, client membaca versi terbaru dari storage lokal.
  • Server belum tahu panel samping terbuka, client memulihkan preferensi user dari browser.

Prinsip perbaikan: state pertama yang dipakai client harus berasal dari payload SSR yang sama, bukan dihitung ulang dengan logika berbeda.

2. Waktu, zona waktu, dan locale tidak konsisten

Format tanggal dan angka sering terlihat sepele, tetapi sangat sering memicu mismatch. Server bisa berjalan di locale atau timezone berbeda dari browser pengguna.

Contoh:

  • 21/03/2026 di server berubah menjadi 3/21/2026 di client.
  • Teks Edited 1 minute ago berubah menjadi Edited just now saat hydration.
  • Nomor halaman, ukuran, atau format mata uang di template dokumen berubah karena locale berbeda.

Prinsip perbaikan: jangan merender nilai berbasis waktu yang berubah cepat pada SSR jika tidak ada kebutuhan mutlak. Jika harus, serialisasikan nilai mentah dan format secara deterministik dengan locale yang sama, atau tampilkan placeholder stabil dulu.

3. ID acak atau nilai non-deterministik

Editor kaya fitur sering membuat ID untuk node, annotation, toolbar item, portal target, atau marker selection. Jika ID dibuat dengan Math.random(), timestamp, atau urutan yang berbeda antara server dan client, maka atribut DOM dan relasi komponen akan menyimpang.

Contoh gejala:

  • aria-controls toolbar tidak cocok dengan elemen target.
  • Komponen tab, menu, atau popover gagal terhubung.
  • Key daftar berubah, menyebabkan node dipasang ulang.

Prinsip perbaikan: gunakan ID deterministik dari data dokumen, hasil hash stabil, atau generator yang disuplai dari state SSR.

4. Hasil parsing konten kaya berbeda

Dokumen sering berasal dari HTML, Markdown, JSON editor schema, atau format internal lain. Mismatch muncul jika server dan client memakai parser, sanitizer, plugin, atau urutan transformasi yang tidak identik.

Contoh:

  • Server menghapus tag tertentu, client masih mempertahankannya.
  • Whitespace, entity HTML, atau line break diproses berbeda.
  • Plugin syntax highlight atau embed hanya aktif di client.

Prinsip perbaikan: pipeline parsing harus sama di kedua sisi, atau hasil transformasi final harus diserialisasikan dari server ke client tanpa dihitung ulang saat render awal.

5. Akses browser-only API saat SSR

Penggunaan window, document, localStorage, ResizeObserver, ukuran viewport, atau selection API dalam jalur render akan menghasilkan output berbeda atau memaksa fallback yang tidak sama.

Contoh:

  • Toolbar compact/expanded dihitung dari lebar viewport pada client, tetapi server tidak tahu ukuran layar.
  • Preview dokumen memutuskan jumlah halaman dari tinggi elemen DOM.
  • State panel dipulihkan dari localStorage sebelum hydration selesai.

Prinsip perbaikan: semua logika yang bergantung pada browser harus digeser ke fase client-only, dengan placeholder SSR yang stabil.

6. Perbedaan feature flag atau eksperimen

Jika server dan client mengevaluasi flag dengan sumber berbeda, pengguna bisa menerima HTML untuk varian A lalu client mengaktifkan varian B.

Ini sering terjadi pada:

  • toolbar baru vs toolbar lama,
  • preview panel eksperimen,
  • mode komentar baru,
  • fitur AI assist atau contextual action.

Prinsip perbaikan: evaluasi flag di server, serialisasikan hasilnya, lalu pakai nilai yang sama di client sampai hydration selesai.

Pola perbaikan yang aman untuk Next.js, Nuxt, dan SvelteKit secara umum

1. Serialisasi state SSR sebagai sumber kebenaran tunggal

Jangan biarkan client menghitung ulang state awal dari banyak sumber. Dokumen, preferensi render, locale, dan feature flag yang memengaruhi markup awal harus dikirim sebagai payload SSR yang sama dipakai client.

// Pseudocode lintas framework
const ssrPayload = {
  documentId: doc.id,
  revision: doc.revision,
  locale: user.locale,
  timezone: user.timezone,
  featureFlags: resolvedFlags,
  initialView: {
    mode: 'read',
    sidebarOpen: false,
    toolbarVariant: 'stable'
  },
  renderedDocument: normalizedDocumentJson
}

// Client memakai payload ini apa adanya untuk render awal,
// baru melakukan sinkronisasi tambahan setelah mounted.

Jika ada preferensi user dari browser, terapkan setelah mount dan usahakan tidak mengubah struktur DOM utama secara drastis. Misalnya, jangan mengganti seluruh toolbar; cukup aktifkan panel sekunder atau transisi non-destruktif.

2. Guard client-only untuk API browser dan editor interaktif

Editor WYSIWYG, selection overlay, drag handle, spellcheck helper, atau pengukur layout biasanya tidak cocok untuk SSR penuh. Pisahkan bagian yang harus interaktif dari bagian yang harus stabil.

Pola umumnya:

  • SSR untuk shell stabil: header dokumen, metadata, toolbar dasar, preview statis.
  • Client-only untuk interaksi berat: cursor overlay, floating menu, IME helper, measurement layer.
// Pseudocode pola umum
function DocumentPage({ ssrPayload }) {
  return (
    <div>
      <ToolbarShell state={ssrPayload.initialView} />
      <DocumentPreview content={ssrPayload.renderedDocument} />
      <ClientOnly>
        <InteractiveEditor document={ssrPayload.renderedDocument} />
      </ClientOnly>
    </div>
  )
}

Di Next.js ini biasanya berarti memisahkan komponen yang tidak aman untuk SSR. Di Nuxt dan SvelteKit, prinsipnya sama: render area stabil di server, lalu pasang fitur interaktif setelah client siap.

3. Gunakan placeholder yang stabil, bukan placeholder yang berubah-ubah

Placeholder SSR harus memiliki struktur dan dimensi yang konsisten dengan hasil client, terutama untuk toolbar, preview halaman, dan sidebar komentar.

Baik:

  • Skeleton toolbar dengan jumlah tombol tetap.
  • Container preview dengan ukuran halaman tetap.
  • Placeholder komentar dengan tinggi yang diperkirakan stabil.

Buruk:

  • Teks Loading... yang nantinya berubah menjadi toolbar penuh dengan tinggi berbeda.
  • Menampilkan waktu relatif yang langsung berubah saat hydration.
  • Menyembunyikan blok besar di SSR lalu memunculkannya penuh di client.

4. Pastikan rendering deterministik

Render deterministik berarti input yang sama selalu menghasilkan output HTML yang sama. Untuk suite dokumen, ini mencakup:

  • urutan node dokumen konsisten,
  • sorting komentar atau annotation stabil,
  • ID elemen diturunkan dari data tetap,
  • format locale menggunakan parameter eksplisit,
  • tidak ada new Date() atau nilai acak di jalur render.
// Hindari
const elementId = `toolbar-${Math.random()}`
const relative = formatRelative(new Date(updatedAt), new Date())

// Lebih aman
const elementId = `toolbar-${documentId}`
const updatedAtIso = ssrPayload.updatedAtIso
const formatted = formatDate(updatedAtIso, ssrPayload.locale, ssrPayload.timezone)

5. Isolasi komponen interaktif dari markup utama dokumen

Selection highlight, cursor kolaborasi, drag handle tabel, atau menu konteks sebaiknya tidak ikut menentukan struktur DOM SSR dokumen utama. Letakkan sebagai layer terpisah yang hanya aktif di client.

Keuntungannya:

  • HTML dokumen inti tetap stabil.
  • Hydration error pada overlay tidak merusak isi dokumen.
  • Lebih mudah melakukan debugging antara masalah konten dan masalah interaksi.

Contoh anti-pattern yang sering memicu toolbar, cursor, atau preview berubah saat hydration

Anti-pattern 1: membaca localStorage saat render awal

// Bermasalah: output awal client bisa berbeda dari SSR
const sidebarOpen = localStorage.getItem('sidebarOpen') === '1'

Perbaikan: pakai nilai dari SSR untuk render pertama, lalu sinkronkan preferensi browser setelah mount.

Anti-pattern 2: menghitung responsive toolbar dari window.innerWidth di jalur render

// Bermasalah
const compact = window.innerWidth < 960

Ini membuat jumlah tombol toolbar berbeda antara server dan client. Lebih aman memakai CSS responsif untuk layout awal, atau aktifkan mode terukur setelah mount tanpa mengubah struktur dasar.

Anti-pattern 3: memformat waktu relatif secara langsung

// Bermasalah karena berubah tiap detik/menit
const label = timeAgo(updatedAt)

Perbaikan: render waktu absolut atau placeholder stabil di SSR, lalu perbarui label relatif di client jika diperlukan.

Anti-pattern 4: parsing konten kaya dua kali dengan konfigurasi berbeda

Misalnya server memakai sanitizer ketat, client memakai plugin embed tambahan. Akibatnya isi preview bisa berbeda satu blok atau satu atribut dan memicu patch DOM.

Perbaikan: simpan hasil normalisasi final dari server, lalu render representasi yang sama di client saat hydration awal.

Anti-pattern 5: key list tidak stabil

// Bermasalah jika index berubah atau urutan data tidak sama
items.map((item, index) => <Button key={index} ... />)

Pada toolbar atau daftar komentar, key yang tidak stabil membuat node dipasang ulang dan status internal berpindah.

Anti-pattern 6: feature flag dievaluasi ulang di client dari sumber lain

Server merender toolbar A, client langsung mengganti ke toolbar B. Secara visual ini tampak seperti flicker, tetapi akar masalahnya adalah mismatch kontrak render.

Strategi implementasi praktis per area UI dokumen

Toolbar editor

  • SSR hanya tombol dasar yang pasti ada.
  • Status aktif/nonaktif awal berasal dari state dokumen yang diserialisasikan.
  • Overflow, measurement, dan floating toolbar dilakukan setelah mount.
  • Gunakan ID deterministik untuk relasi menu, tab, dan popover.

Preview dokumen

  • Normalisasi konten di server.
  • Gunakan font, whitespace rule, dan formatter yang konsisten.
  • Jangan hitung pagination final dari DOM pada SSR jika hasilnya akan berubah di client.
  • Jika pagination bergantung pada ukuran nyata, SSR-kan versi stabil non-final lalu aktifkan pagination client-only.

Cursor dan kolaborasi realtime

  • Jangan SSR cursor user lain atau selection overlay yang bergantung pada layout aktual.
  • Render layer kosong yang stabil di SSR.
  • Aktifkan overlay setelah editor mounted dan ukuran DOM tersedia.

Panel komentar dan activity

  • Urutkan data di server dengan aturan yang sama seperti client.
  • Hindari label waktu relatif pada render awal.
  • Jika unread state dari browser memengaruhi tampilan, tunda sampai setelah hydration.

Langkah debugging hydration drift

1. Reproduksi dengan data tetap

Gunakan satu dokumen contoh yang sama, satu locale yang sama, dan nonaktifkan variabel acak sementara. Tujuannya agar mismatch bisa diulang secara konsisten.

2. Bandingkan payload SSR dengan state awal client

Periksa apakah dokumen, revision, locale, timezone, feature flag, dan preferensi view identik. Jika state awal client berasal dari store yang langsung membaca browser storage, itu kandidat utama.

3. Cari nilai non-deterministik di jalur render

Lakukan pencarian untuk pola berikut:

  • Math.random
  • Date.now
  • new Date()
  • window, document, localStorage
  • formatter locale tanpa parameter eksplisit

4. Bandingkan HTML server dengan DOM awal sebelum efek client berjalan

Gunakan DevTools dan log internal untuk melihat apakah struktur node berbeda, bukan hanya teks. Pada editor dokumen, selisih satu wrapper <span> atau satu atribut data bisa cukup untuk memicu masalah.

5. Isolasi subtree yang bermasalah

Matikan sementara komponen interaktif seperti floating toolbar, cursor layer, mention menu, atau preview enhancement. Jika mismatch hilang, Anda tahu area masalahnya.

6. Audit parser dan transformasi konten

Pastikan sanitizer, serializer, parser Markdown/HTML, dan plugin konten yang dipakai server sama dengan client, atau setidaknya menghasilkan representasi awal yang identik.

Catatan: jika warning hydration hanya muncul pada dokumen tertentu, kemungkinan besar masalah ada pada bentuk data atau transformasi konten, bukan pada shell aplikasi secara umum.

Checklist verifikasi sebelum rilis

  1. Apakah state awal client sepenuhnya berasal dari payload SSR untuk area yang dirender di server?
  2. Apakah ada penggunaan waktu relatif, nilai acak, atau locale implisit dalam render awal?
  3. Apakah feature flag yang memengaruhi markup dievaluasi sekali di server dan diserialisasikan ke client?
  4. Apakah komponen yang butuh window, ukuran DOM, atau selection API diisolasi sebagai client-only?
  5. Apakah parser, sanitizer, dan serializer konten kaya konsisten antara server dan client?
  6. Apakah placeholder SSR memiliki struktur dan tinggi yang stabil?
  7. Apakah key list, ID elemen, dan atribut ARIA deterministik?
  8. Apakah toolbar, preview, komentar, dan panel samping diuji pada locale serta timezone berbeda?
  9. Apakah perilaku sudah dicek saat JavaScript lambat, koneksi lambat, atau hydration tertunda?
  10. Apakah warning hydration di console benar-benar nol pada jalur utama pembukaan dokumen?

Panduan umum untuk Next.js, Nuxt, dan SvelteKit

Walau API detail tiap framework berbeda, pola pencegahan tetap sama:

  • Next.js: pastikan data SSR dan komponen client dipisahkan dengan jelas; hindari editor berat pada render server jika output awalnya tidak deterministik.
  • Nuxt: jaga agar state dari server store tidak ditimpa terlalu dini oleh plugin client; gunakan komponen client-only hanya untuk bagian yang memang bergantung pada browser.
  • SvelteKit: render data dokumen dari load server secara konsisten; tunda akses DOM dan API browser sampai fase client aktif.

Fokusnya bukan pada framework tertentu, melainkan pada kontrak render: input SSR dan input render awal client harus sama untuk semua bagian UI yang ingin di-hydrate tanpa drift.

Kesimpulan

Mencegah hydration drift pada SSR untuk suite dokumen web bukan sekadar menghilangkan warning di console. Ini tentang menjaga agar dokumen, toolbar, preview, dan interaksi awal tampil konsisten dari byte pertama yang dikirim server sampai aplikasi benar-benar interaktif di browser.

Jika ingin hasil yang stabil, pegang lima aturan utama: serialisasi state sebagai sumber tunggal, guard client-only untuk API browser, placeholder SSR yang stabil, rendering deterministik, dan isolasi komponen interaktif. Untuk aplikasi office atau document editor, pendekatan ini jauh lebih penting daripada memaksakan semua fitur ikut SSR. UI dokumen yang konsisten hampir selalu lebih berharga daripada hydration yang agresif tetapi rapuh.