Rust Leptos: Diagnosa Hydration Mismatch dari State Browser pada SSR

Hydration mismatch pada aplikasi SSR Leptos biasanya terjadi ketika HTML yang dirender server tidak sama dengan hasil render awal di browser. Kasus yang paling sering adalah state awal komponen membaca browser-only state seperti localStorage, ukuran jendela, tema dari window, atau API browser lain yang memang tidak tersedia saat render di server.

Masalah ini bukan sekadar warning. Gejalanya bisa berupa teks yang berubah setelah halaman tampil, elemen yang "loncat", event handler yang terasa tidak konsisten, atau warning hydration di konsol. Kuncinya adalah memastikan render pertama di server dan render pertama di klien menghasilkan markup yang deterministik, lalu memindahkan pembacaan state browser ke tahap setelah komponen terpasang di klien.

Pemahaman dasar: apa itu hydration mismatch di Leptos

Pada SSR, server mengirim HTML awal agar halaman bisa tampil cepat dan ramah SEO. Setelah itu, Leptos di browser melakukan hydration: ia menghubungkan event listener dan state reaktif ke HTML yang sudah ada.

Hydration mengasumsikan bahwa struktur DOM dan nilai penting yang dirender pada fase awal cocok antara server dan klien. Jika server merender:

<p>Tema: light</p>

tetapi render awal di browser langsung menjadi:

<p>Tema: dark</p>

maka framework harus berusaha memperbaiki perbedaan itu. Tergantung kasusnya, hasilnya bisa sekadar warning, bisa juga menimbulkan perilaku UI yang membingungkan.

Gejala UI yang umum terlihat

Warning hydration di konsol tentang node atau teks yang tidak cocok.
Flash of incorrect content: pengguna melihat nilai default lebih dulu, lalu berubah cepat setelah mount.
Layout shift karena cabang render berbeda antara server dan klien.
Komponen kondisional muncul/hilang saat hydration selesai.
State awal terasa salah, misalnya tema, sidebar terbuka/tertutup, atau label berdasarkan ukuran layar.

Pada Leptos, masalah ini sering muncul saat state diinisialisasi terlalu dini dari API browser. Yang perlu diingat: server tidak punya window, document, atau localStorage.

Root cause: output HTML server dan render awal klien tidak identik

Akar masalahnya sederhana: server dan browser menjalankan konteks yang berbeda.

1. State awal bergantung pada localStorage

Contoh klasik adalah tema:

Server tidak bisa membaca localStorage, maka ia merender default light.
Klien langsung membaca localStorage dan menemukan dark.
Markup awal berbeda, hydration mismatch muncul.

2. State awal bergantung pada window size

Jika komponen merender label atau layout berdasarkan window.inner_width pada render pertama, server tidak punya informasi itu. Akibatnya server memakai fallback, sedangkan klien langsung memilih cabang render lain.

3. State awal bergantung pada nilai browser lain

Misalnya preferensi media query, timezone lokal yang hanya dihitung di klien, atau status API yang hanya ada setelah halaman dibuka. Selama nilai itu memengaruhi output HTML awal, mismatch bisa terjadi.

Reproduksi minimal hydration mismatch di Leptos

Berikut contoh yang sengaja bermasalah. Intinya adalah state awal mencoba diturunkan dari browser dan memengaruhi teks yang dirender.

use leptos::*;

#[component]
pub fn ThemeLabel() -> impl IntoView {
    // Contoh anti-pattern untuk SSR:
    // server tidak bisa membaca localStorage,
    // klien bisa, sehingga nilai awal berpotensi berbeda.
    let initial_theme = if cfg!(target_arch = "wasm32") {
        // Pseudocode: akses browser pada fase awal render
        // Bisa menghasilkan "dark"
        "dark".to_string()
    } else {
        // Server fallback ke default
        "light".to_string()
    };

    let (theme, _set_theme) = create_signal(initial_theme);

    view! {
        <p>"Tema aktif: " {move || theme.get()}</p>
    }
}

Contoh di atas menggambarkan masalahnya, walau detail akses browser nyata biasanya membutuhkan API web_sys atau helper lain. Masalah utamanya bukan pada API yang dipakai, tetapi pada waktu pembacaan state: ia dilakukan terlalu awal, sebelum hydration selesai, sehingga hasil render server dan klien bisa berbeda.

Skenario reproduksi yang mudah diuji

Buat halaman SSR Leptos dengan komponen yang menampilkan tema atau mode tampilan.
Di server, gunakan default light.
Di browser, simpan theme=dark di localStorage.
Biarkan render awal klien langsung membaca nilai tersebut.
Muat ulang halaman dan perhatikan warning hydration serta perubahan teks/kelas setelah halaman tampil.

Pola perbaikan yang aman untuk SSR

Untuk mencegah hydration mismatch, gunakan empat prinsip berikut:

State awal harus deterministik antara server dan klien.
Akses browser-only dipindah ke effect atau on_mount.
Gunakan placeholder yang stabil bila nilai asli belum tersedia.
Pakai guard SSR yang aman, tetapi jangan menjadikannya alasan untuk merender output awal yang berbeda.

1. Gunakan state awal yang deterministik

Jika nilai browser belum bisa diketahui di server, pilih nilai awal yang sama di kedua sisi. Misalnya:

use leptos::*;

#[component]
pub fn ThemeLabel() -> impl IntoView {
    let (theme, set_theme) = create_signal(String::from("unknown"));

    on_mount(move || {
        // Di sini baru aman membaca localStorage / window.
        // Contoh disederhanakan; implementasi nyata dapat memakai web_sys.
        let browser_theme = "dark".to_string();
        set_theme.set(browser_theme);
    });

    view! {
        <p>"Tema aktif: " {move || theme.get()}</p>
    }
}

Pendekatan ini bekerja karena server dan klien sama-sama merender unknown pada fase awal. Setelah komponen terpasang di browser, nilai diperbarui secara reaktif tanpa melanggar asumsi hydration.

2. Pindahkan akses browser-only ke on_mount atau effect

on_mount cocok untuk pembacaan state browser yang hanya valid setelah komponen hidup di klien. Ini termasuk:

localStorage dan sessionStorage
window.inner_width
matchMedia
API DOM atau event listener browser

Contoh untuk ukuran jendela:

use leptos::*;

#[component]
pub fn ResponsiveLabel() -> impl IntoView {
    let (is_mobile, set_is_mobile) = create_signal(false);

    on_mount(move || {
        // Pseudocode: baca ukuran window di klien
        let width = 480;
        set_is_mobile.set(width < 768);
    });

    view! {
        <p>
            {move || if is_mobile.get() { "Mode mobile" } else { "Mode desktop" }}
        </p>
    }
}

Jika label Mode desktop menjadi fallback awal, maka render awal server dan klien tetap sama. Perubahan terjadi setelah mount, bukan saat hydration awal.

3. Pakai placeholder yang stabil bila perlu

Jika default seperti desktop atau light berisiko menyesatkan pengguna, lebih baik tampilkan placeholder netral:

use leptos::*;

#[component]
pub fn SafeThemeBanner() -> impl IntoView {
    let (theme, set_theme) = create_signal(Option::<String>::None);

    on_mount(move || {
        let browser_theme = "dark".to_string();
        set_theme.set(Some(browser_theme));
    });

    view! {
        <p>
            {move || match theme.get() {
                Some(t) => format!("Tema aktif: {}", t),
                None => "Tema aktif: memuat...".to_string(),
            }}
        </p>
    }
}

Ini membantu menghindari pesan yang salah pada render awal. Placeholder stabil juga berguna saat bagian UI sangat dipengaruhi state browser.

4. Gunakan guard SSR dengan benar

Guard SSR berarti memeriksa apakah kode berjalan di browser sebelum memakai API browser. Ini penting untuk mencegah panic atau error, tetapi tidak otomatis menyelesaikan hydration mismatch.

Kesalahan umum adalah:

let initial = if running_in_browser() {
    read_local_storage_theme()
} else {
    "light".to_string()
};

Kode di atas mungkin aman dari sisi runtime, tetapi tetap berisiko mismatch karena output awal server dan klien berbeda.

Guard SSR yang benar sebaiknya dipakai untuk menunda akses browser, bukan untuk membedakan hasil render awal. Artinya:

render awal tetap sama di server dan klien,
lalu di on_mount atau effect, baru lakukan pembacaan browser-only.

Contoh praktis: perbaikan komponen tema dari localStorage

Berikut pola yang lebih realistis. Tujuannya bukan menunjukkan detail API browser secara lengkap, tetapi struktur solusi yang aman untuk SSR Leptos.

use leptos::*;

#[component]
pub fn ThemeSwitcher() -> impl IntoView {
    // Nilai awal deterministik untuk SSR + hydration.
    let (theme, set_theme) = create_signal(String::from("system"));
    let (ready, set_ready) = create_signal(false);

    on_mount(move || {
        // Pseudocode:
        // 1. baca localStorage jika ada
        // 2. fallback ke preferensi sistem jika perlu
        // 3. update signal setelah mount
        let stored_theme = Some("dark".to_string());
        let resolved = stored_theme.unwrap_or_else(|| "system".to_string());
        set_theme.set(resolved);
        set_ready.set(true);
    });

    view! {
        <section>
            <p>
                {move || {
                    if ready.get() {
                        format!("Tema aktif: {}", theme.get())
                    } else {
                        "Tema aktif: memuat...".to_string()
                    }
                }}
            </p>
        </section>
    }
}

Mengapa pola ini aman?

Server dan klien sama-sama merender placeholder pada awalnya.
Pembacaan browser terjadi setelah mount, sehingga tidak ikut menentukan markup hydration awal.
Perubahan state sesudahnya normal dalam model reaktif, dan bukan hydration mismatch.

Kapan sebaiknya memakai placeholder, fallback default, atau render tertunda?

Pilih fallback default jika

Perbedaan nilai awal tidak kritis bagi pengguna.
Anda bisa menerima sedikit perubahan setelah mount.
Konten tetap bermakna untuk SEO dan aksesibilitas.

Contoh: label kecil yang berubah dari desktop ke mobile.

Pilih placeholder stabil jika

Nilai browser sangat menentukan isi UI.
Default berisiko salah secara semantik.
Anda ingin menghindari flash konten yang keliru.

Contoh: tema personal, status panel yang disimpan pengguna, atau konten yang bergantung izin browser.

Tunda render bagian tertentu jika

Subtree UI hampir seluruhnya bergantung pada browser state.
Biaya mismatch lebih besar daripada biaya menunggu setelah mount.

Namun ada trade-off yang perlu dipertimbangkan.

Trade-off UX dan SEO saat menunda render

Dampak ke UX

Pro: menghindari konten salah dan mengurangi warning hydration.
Pro: UI menjadi lebih konsisten, terutama untuk preferensi pengguna.
Kontra: pengguna bisa melihat placeholder atau area kosong sesaat.
Kontra: jika terlalu banyak bagian ditunda, halaman terasa lambat walau HTML sudah terkirim.

Dampak ke SEO

Konten yang tidak dirender di server bisa kurang ideal untuk mesin pencari jika bagian itu penting secara semantik.
Untuk elemen non-kritis seperti tema visual atau layout adaptif, dampak SEO biasanya kecil.
Untuk konten utama halaman, usahakan tetap ada versi SSR yang stabil dan bermakna.

Aturan praktisnya: jangan menunda render konten utama hanya karena butuh sedikit browser state. Tunda hanya bagian yang memang tidak bisa ditentukan secara aman di server.

Checklist debugging hydration mismatch di Leptos

Cek konsol browser untuk warning hydration dan komponen yang terlibat.
Bandingkan output awal server vs render awal klien. Fokus pada teks, atribut, kelas CSS, dan cabang kondisional.
Cari akses browser-only di dalam inisialisasi signal, memo, atau ekspresi yang dievaluasi saat render awal.
Audit penggunaan localStorage, window, document, matchMedia, dan ukuran viewport.
Pastikan nilai awal signal deterministik di server dan klien.
Pindahkan pembacaan browser ke on_mount/effect lalu update signal setelah hydration.
Periksa cabang render bersyarat seperti if is_mobile, if dark_mode, atau if logged_in_from_storage.
Gunakan placeholder stabil bila belum ada nilai yang aman untuk SSR.
Uji dengan refresh penuh, bukan hanya navigasi klien, karena mismatch biasanya muncul pada SSR awal.
Uji beberapa kondisi browser: localStorage kosong, nilai tersimpan berbeda, viewport kecil/besar, preferensi sistem berbeda.

Kesalahan umum yang sering terjadi

Menganggap guard SSR saja sudah cukup

Guard memang mencegah akses API browser di server, tetapi tidak menjamin output awal sama. Jika fallback server dan hasil klien berbeda, mismatch tetap terjadi.

Menyimpan state browser ke signal pada saat deklarasi awal

Jika deklarasi awal memengaruhi HTML yang dirender, Anda sedang mengambil risiko mismatch. Inisialisasi state awal sebaiknya netral dan deterministik.

Merender subtree yang berbeda total berdasarkan viewport

Jika SSR menghasilkan struktur DOM A, tetapi klien langsung memilih struktur DOM B, mismatch menjadi lebih mungkin dan lebih sulit dilacak. Lebih aman menggunakan CSS responsif untuk banyak kasus, lalu browser state dipakai hanya untuk peningkatan perilaku setelah mount.

Mengandalkan browser state untuk konten utama

Bila konten utama hanya tersedia setelah mount, Anda mungkin menyelesaikan mismatch tetapi mengorbankan SSR dan SEO tanpa perlu.

Strategi praktis yang paling aman

Jika Anda perlu aturan singkat yang bisa diterapkan konsisten pada proyek Leptos SSR, gunakan urutan berikut:

Tentukan markup awal yang bisa dirender sama di server dan klien.
Jangan baca localStorage/window saat menentukan output awal.
Setelah on_mount, baca nilai browser dan sinkronkan ke signal.
Jika perlu, tampilkan placeholder stabil sampai nilai tersedia.
Untuk layout responsif, prioritaskan CSS daripada mengganti subtree saat hydration.

Penutup

Diagnosa hydration mismatch dari state browser pada Leptos hampir selalu kembali ke satu prinsip: render pertama harus deterministik. Saat state awal bergantung pada localStorage, ukuran window, atau nilai browser lain, jangan biarkan nilai itu menentukan HTML SSR maupun render awal klien.

Solusi yang paling aman adalah memulai dari state netral yang sama di kedua sisi, memindahkan akses browser-only ke on_mount atau effect, dan memakai placeholder stabil bila diperlukan. Dengan pola ini, Anda mengurangi warning hydration, menjaga perilaku UI tetap konsisten, dan tetap mendapat manfaat SSR tanpa mengorbankan maintainability.

Quick Search

shopping_cart Keranjang