Pada Rust Yew SSR, hydration error biasanya terjadi karena HTML yang dikirim server tidak identik dengan hasil render pertama di browser. Kasus yang paling sering adalah komponen yang menampilkan waktu sekarang, tanggal terformat berdasarkan timezone lokal, atau format yang bergantung pada locale browser. Akibatnya, Yew mencoba melakukan hydration pada DOM yang isinya sudah berbeda sejak awal.

Gejalanya cukup khas: muncul warning hydration di console, teks tanggal berubah sesaat setelah aplikasi mount, atau pengguna melihat konten yang awalnya satu format lalu berganti menjadi format lain. Solusinya bukan sekadar “format ulang tanggal”, tetapi memastikan render server dan render awal klien memakai input yang sama, atau menunda render nilai non-deterministik ke fase khusus klien.

Gejala umum hydration error pada nilai waktu dan locale

Sebelum masuk ke perbaikan, kenali pola masalahnya. Pada aplikasi SSR, browser menerima HTML hasil render server lalu Yew melakukan hydration agar event handler dan state aktif tanpa membuang DOM yang sudah ada. Proses ini mengasumsikan struktur dan isi HTML awal harus sama.

  • Warning hydration di console, biasanya terkait mismatch text node atau DOM yang tidak sesuai.
  • UI berubah setelah mount, misalnya server menampilkan 2025-06-19 10:00 UTC lalu browser mengubahnya menjadi 19/06/2025 17.00 WIB.
  • Teks tanggal tidak konsisten antar refresh, antar browser, atau antar region pengguna.
  • Snapshot test SSR lolos, tetapi di browser nyata muncul mismatch karena environment klien berbeda.

Intinya: hydration bukan hanya soal struktur DOM. Perbedaan teks kecil seperti spasi, nama bulan, zona waktu, atau format jam juga bisa memicu mismatch.

Root cause teknis: mengapa waktu dan locale memicu mismatch?

1. Nilai waktu bersifat non-deterministik

Jika komponen memanggil waktu saat render, misalnya now(), server dan klien hampir pasti menghasilkan nilai berbeda walaupun selisihnya hanya milidetik. Untuk SSR, itu sudah cukup membuat hasil HTML berbeda.

2. Timezone server dan browser berbeda

Server sering berjalan di UTC atau timezone container tertentu, sedangkan browser pengguna memakai timezone lokal. Jika render langsung memakai timezone default environment, hasil format tanggal akan berubah.

3. Locale server dan locale browser berbeda

Format seperti nama hari, nama bulan, urutan tanggal, separator, atau format 12/24 jam sering bergantung pada locale. Server bisa merender dengan locale sistem yang berbeda dari browser pengguna, sehingga teks akhir tidak identik.

4. Formatter tidak sama antara sisi server dan klien

Walaupun input timestamp sama, hasilnya bisa tetap berbeda jika sisi server dan klien memakai formatter, opsi, atau normalisasi yang tidak identik. Masalah ini umum saat satu sisi merender ISO string, sisi lain merender format lokal yang lebih ramah pengguna.

Contoh kode yang bermasalah

Masalah klasiknya adalah membuat nilai tanggal saat render komponen. Contoh berikut disederhanakan untuk menunjukkan polanya:

use yew::prelude::*;

#[function_component(TimeBadge)]
pub fn time_badge() -> Html {
    // Pseudocode: sumber waktu saat render
    let now_text = current_local_time_formatted();

    html! {
        <span class="timestamp">{ now_text }</span>
    }
}

fn current_local_time_formatted() -> String {
    // Contoh pseudocode: pada implementasi nyata bisa memakai crate waktu/formatter tertentu
    // Problem utamanya: nilai ini bergantung pada waktu dan environment lokal.
    "19/06/2025 17:00".to_string()
}

Pada SSR, fungsi itu dieksekusi di server. Saat hydration, komponen yang sama dirender lagi di browser. Jika hasil string berbeda, Yew mendeteksi mismatch.

Masalah serupa terjadi pada kode yang mengambil locale browser atau timezone lokal saat render awal, misalnya menampilkan nama bulan dalam bahasa pengguna. Server tidak selalu punya informasi yang sama, atau walaupun punya, belum tentu formatter-nya identik.

Perbaikan 1: tunda render nilai non-deterministik ke fase client-only

Jika sebuah elemen tidak kritikal untuk SEO dan tidak harus benar-benar ada pada HTML SSR, pendekatan paling aman adalah jangan render nilai non-deterministik saat SSR. Render placeholder yang stabil, lalu isi nilai sebenarnya setelah komponen ter-mount di browser.

Dengan pendekatan ini, HTML server dan render awal klien tetap sama. Nilai waktu baru dihitung setelah hydration selesai.

use yew::prelude::*;

#[function_component(ClientLocalTime)]
pub fn client_local_time() -> Html {
    let text = use_state(|| None::<String>);

    {
        let text = text.clone();
        use_effect(move || {
            let formatted = format_in_browser_locale();
            text.set(Some(formatted));
            || ()
        });
    }

    html! {
        <span class="timestamp">
            {
                if let Some(value) = &*text {
                    html! { value.clone() }
                } else {
                    html! { "-" }
                }
            }
        </span>
    }
}

fn format_in_browser_locale() -> String {
    // Pseudocode: lakukan formatting di browser setelah mount.
    "19/06/2025 17:00".to_string()
}

Mengapa ini bekerja? Karena placeholder seperti - dirender sama di server dan pada render pertama klien. Nilai aktual baru muncul setelah efek berjalan di browser, sehingga tidak mengganggu hydration.

Kapan cocok dipakai?

  • Tanggal/jam yang bersifat dekoratif atau sekunder.
  • UI personalisasi berdasarkan timezone pengguna.
  • Konten yang tidak penting untuk crawler atau preview awal.

Kekurangan

  • Pengguna melihat placeholder atau perubahan teks setelah mount.
  • Jika elemen penting untuk SEO, nilai itu tidak hadir penuh pada HTML SSR.
  • Bisa menimbulkan layout shift kecil jika placeholder tidak dirancang dengan baik.

Perbaikan 2: kirim state awal yang stabil dari server

Jika tanggal harus tersedia sejak HTML awal, gunakan data mentah yang stabil dari server, misalnya timestamp Unix atau ISO 8601 dalam UTC, lalu pastikan render pertama di klien memakai nilai yang sama persis.

Prinsipnya: server dan klien harus menerima input identik untuk render awal. Jangan panggil waktu baru di klien saat hydration jika server sudah mengirim satu nilai tertentu.

use yew::prelude::*;

#[derive(Properties, PartialEq)]
pub struct PublishedAtProps {
    pub published_at_iso_utc: AttrValue,
}

#[function_component(PublishedAt)]
pub fn published_at(props: &PublishedAtProps) -> Html {
    let stable_text = props.published_at_iso_utc.clone();

    html! {
        <time datetime={props.published_at_iso_utc.clone()}>
            { stable_text }
        </time>
    }
}

Pada contoh ini, server dan klien sama-sama merender string ISO UTC yang sama. Setelah hydration, Anda bisa memilih untuk tetap mempertahankannya, atau menggantinya ke format lokal melalui fase client-only jika memang perlu.

Pola yang lebih aman

  1. Server mengirim nilai canonical, misalnya 2025-06-19T10:00:00Z.
  2. Render awal SSR dan render awal klien memakai string canonical yang sama.
  3. Setelah mount, browser boleh meng-upgrade tampilan ke format lokal pengguna.

Pola ini memisahkan kebenaran data dari cara presentasi. Untuk hydration, yang penting render awal tetap stabil.

Perbaikan 3: samakan formatter, timezone, dan locale

Jika Anda benar-benar ingin hasil SSR sudah dalam format manusiawi dan tidak berubah setelah mount, maka formatter di server dan klien harus konsisten. Ini lebih sulit, tetapi kadang dibutuhkan.

Prinsip implementasi

  • Gunakan timezone eksplisit, jangan bergantung pada default environment.
  • Gunakan locale eksplisit, jangan mengandalkan locale sistem yang bisa berbeda.
  • Gunakan input timestamp yang sama di kedua sisi.
  • Pastikan aturan formatnya sama, termasuk urutan tanggal, nama bulan, dan jam 12/24.

Contohnya, jika halaman harus selalu menampilkan tanggal dalam bahasa Indonesia dan timezone UTC+7 tertentu, maka jangan ambil timezone dari browser di satu sisi dan timezone server di sisi lain. Tentukan satu aturan tetap untuk kedua sisi.

Perlu dicatat: menyeragamkan formatter cocok untuk format yang memang universal dalam aplikasi. Jika tujuan Anda adalah personalisasi berdasarkan locale pengguna, pendekatan ini justru membatasi fleksibilitas.

Strategi praktis: SSR stabil dulu, lalu upgrade ke format lokal

Untuk banyak aplikasi, solusi paling seimbang adalah:

  1. Render SSR dengan format stabil, misalnya ISO UTC atau format baku aplikasi.
  2. Sertakan atribut seperti datetime agar data mentah tetap tersedia dan semantik HTML bagus.
  3. Setelah mount, jika perlu, ubah hanya teks tampilannya ke locale pengguna.

Contoh HTML target:

<time datetime="2025-06-19T10:00:00Z">2025-06-19 10:00 UTC</time>

Lalu setelah mount di browser, teks di dalam elemen bisa diubah menjadi 19 Juni 2025, 17.00 berdasarkan locale dan timezone pengguna. Dengan pola ini, crawler dan pengguna sama-sama mendapat markup awal yang stabil, sementara UI tetap bisa dipersonalisasi.

Langkah reproduksi bug agar mudah diuji

Jika Anda ingin memastikan bahwa masalah hydration memang berasal dari waktu/locale, reproduksi bug secara terkontrol:

  1. Buat komponen SSR yang menampilkan waktu saat render.
  2. Jalankan server dengan timezone tertentu, misalnya UTC.
  3. Buka halaman dari browser dengan timezone berbeda.
  4. Tambahkan format yang bergantung pada locale, seperti nama bulan atau urutan tanggal.
  5. Perhatikan console browser saat hydration dan lihat apakah teks berubah setelah mount.

Reproduksi minimal biasanya cukup untuk mengisolasi masalah tanpa noise dari komponen lain.

Checklist debugging hydration error di Yew SSR

Checklist cepat

  • Apakah ada pemanggilan waktu sekarang saat render komponen?
  • Apakah ada formatting tanggal yang memakai timezone default environment?
  • Apakah locale di server dan browser bisa berbeda?
  • Apakah render awal klien mengambil data baru yang tidak sama dengan SSR?
  • Apakah placeholder SSR berbeda dengan state awal klien?
  • Apakah ada conditional render berdasarkan API browser yang hanya tersedia di klien?

Teknik debug yang membantu

  • Log nilai mentah: cetak timestamp/input asli di server dan di klien, bukan hanya hasil formatnya.
  • Bandingkan HTML awal: lihat source dari server lalu bandingkan dengan teks yang muncul setelah mount.
  • Bekukan input: ganti sementara now() dengan timestamp hardcoded untuk melihat apakah warning hilang.
  • Paksa timezone/locale tertentu: uji dengan environment yang terkontrol agar selisih mudah dilacak.
  • Isolasi komponen: pindahkan komponen tanggal ke halaman minimal agar jelas sumber mismatch-nya.

Kesalahan umum yang sering terjadi

  • Menganggap selisih kecil tidak masalah. Dalam hydration, satu karakter berbeda pun bisa memicu mismatch.
  • Menggunakan placeholder berbeda antara SSR dan state awal klien.
  • Mencampur data dan presentasi, misalnya langsung menyimpan hasil format lokal sebagai state canonical.
  • Mengandalkan default sistem untuk timezone atau locale di server.
  • Memperbaiki gejala, bukan akar masalah, misalnya mematikan warning tanpa menjamin render awal identik.

Trade-off SEO dan UX: SSR vs client-only untuk elemen tanggal

Pilih SSR stabil jika:

  • Tanggal penting untuk SEO, misalnya artikel, berita, atau metadata konten.
  • Anda ingin crawler dan pengguna melihat informasi yang sama sejak respons awal.
  • Anda butuh markup semantik seperti <time datetime="..."> yang langsung tersedia.

Pilih client-only untuk elemen tertentu jika:

  • Format harus benar-benar mengikuti locale/timezone pengguna.
  • Elemen tersebut bukan konten utama untuk mesin pencari.
  • Anda ingin menghindari kompleksitas penyamaan formatter server dan klien.

Kompromi yang sering paling masuk akal

Gunakan SSR untuk nilai canonical yang stabil, lalu lakukan enhancement di klien untuk format lokal. Ini memberi keseimbangan antara SEO, kestabilan hydration, dan pengalaman pengguna.

Namun, jika perubahan tampilan setelah mount terasa mengganggu, pertimbangkan untuk tetap menampilkan format SSR yang baku dan tidak mengubahnya sama sekali. Tidak semua data waktu harus dipersonalisasi.

Rekomendasi implementasi yang aman

  1. Simpan waktu sebagai timestamp atau ISO UTC, bukan string format lokal.
  2. Pada SSR, render hanya nilai yang deterministik.
  3. Jika butuh locale pengguna, lakukan formatting setelah hydration.
  4. Jika ingin SSR langsung final, gunakan locale dan timezone eksplisit yang sama di kedua sisi.
  5. Gunakan elemen time dengan atribut datetime untuk semantik dan fallback yang jelas.

Penutup

Bug hydration pada Rust Yew SSR yang melibatkan waktu, timezone, locale, atau format tanggal hampir selalu berakar pada render yang tidak deterministik. Selama server dan render awal klien tidak identik, warning hydration dan perubahan UI setelah mount akan terus muncul.

Pendekatan yang paling praktis biasanya salah satu dari tiga ini: tunda render ke client-only phase, kirim state awal yang stabil dari server, atau samakan formatter secara eksplisit. Pilih berdasarkan kebutuhan SEO, UX, dan tingkat personalisasi yang memang dibutuhkan oleh elemen tersebut.