Rust Dioxus SSR: Debug UI Flicker dan State Hydration Tidak Stabil

Rust Dioxus SSR sering menimbulkan masalah yang terlihat sepele tetapi dampaknya mengganggu: UI berkedip setelah mount, isi komponen berubah tiba-tiba, atau event handler terasa tidak konsisten. Dalam banyak kasus, akar masalahnya bukan pada event itu sendiri, melainkan pada hydration mismatch antara HTML hasil render server dan state awal saat aplikasi hidup di klien.

Jika markup awal dari server tidak identik dengan markup yang diharapkan klien saat hydration, framework harus menyesuaikan DOM. Penyesuaian ini bisa terlihat sebagai UI flicker, teks yang berubah sesaat setelah halaman tampil, atau state yang terasa “reset”. Solusinya adalah memastikan render awal bersifat deterministik, memindahkan akses API browser ke fase klien yang aman, dan membuat initial state tetap konsisten antara server dan klien.

Memahami sumber masalah pada Dioxus SSR

Pada SSR, server menghasilkan HTML awal agar halaman cepat tampil. Setelah itu, sisi klien melakukan hydration: ia menghubungkan komponen Rust/WASM ke DOM yang sudah ada. Proses ini mengasumsikan bahwa hasil render pertama di klien sama dengan hasil render di server.

Masalah muncul ketika komponen membuat keputusan render berdasarkan data yang hanya tersedia di klien, nilai yang berubah-ubah, atau state awal yang dihitung berbeda. Ketika kondisi ini terjadi, klien merender struktur atau isi yang tidak sama dengan HTML server. Akibatnya:

konten tampak berubah sesaat setelah halaman muncul,
elemen berpindah atau diganti ulang,
state interaktif terasa aneh karena node DOM yang diharapkan ternyata sudah diganti,
debugging menjadi sulit karena bug hanya muncul di kombinasi SSR + hydration.

Gejala nyata yang perlu dicurigai

1. Konten berubah setelah mount

Gejala paling umum adalah teks atau komponen yang semula tampil dari server lalu berubah setelah aplikasi aktif di browser. Contohnya: label tema, status login, waktu “sekarang”, angka acak, atau hasil pembacaan localStorage.

2. Event handler terasa aneh

Klik tidak bekerja pada render pertama, elemen harus diklik dua kali, atau handler seolah terpasang ke node yang salah. Sering kali ini bukan bug event murni, tetapi efek samping dari DOM yang direkonsiliasi ulang karena mismatch saat hydration.

3. Komponen membaca state browser terlalu dini

Komponen mencoba mengakses window, document, localStorage, ukuran viewport, atau preferensi browser saat render awal. Pada server, objek ini tidak ada. Bahkan jika diberi fallback, hasil akhirnya sering tetap berbeda dengan render klien pertama.

Penyebab umum hydration mismatch

Nilai yang tidak deterministik saat render

Jangan gunakan nilai yang berubah setiap kali render awal, seperti:

waktu saat ini,
angka acak,
ID yang dibangkitkan secara acak,
hasil pembacaan environment yang berbeda antara server dan browser.

Jika nilai tersebut langsung memengaruhi markup awal, hasil server dan klien hampir pasti berbeda.

Akses API browser saat render awal

SSR tidak memiliki window atau localStorage. Walaupun kode bisa dibuat “aman” dengan pemeriksaan kondisi, hasil render tetap bisa berbeda. Misalnya server menampilkan tema light, sedangkan klien membaca dark dari localStorage pada render pertama. Ini memicu flicker.

Initial state berbeda antara server dan klien

Masalah ini sering muncul saat state diinisialisasi dari sumber yang tidak identik. Misalnya:

server menganggap pengguna belum login, klien langsung membaca token lokal,
server memakai default pagination 10 item, klien mengambil preferensi 25 item dari storage,
server merender placeholder kosong, klien langsung memiliki data sinkron dari cache browser.

Contoh kode yang salah dan dampaknya

Kasus 1: menggunakan waktu saat render

Contoh berikut tampak sederhana, tetapi berisiko mismatch karena waktu server dan klien tidak identik.

use dioxus::prelude::*;
use std::time::{SystemTime, UNIX_EPOCH};

#[component]
fn ClockLabel() -> Element {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs();

    rsx! {
        p { "Timestamp: {now}" }
    }
}

Server merender satu nilai, klien merender nilai lain beberapa milidetik atau detik kemudian. Akibatnya, hydration harus memperbarui teks segera setelah mount.

Perbaikan: kirim nilai deterministik atau render setelah mount

Pilih salah satu strategi berikut:

Server menentukan nilai dan mempertahankannya untuk render awal.
Jangan tampilkan nilai dinamis saat SSR; isi nilainya setelah komponen hidup di klien.

use dioxus::prelude::*;

#[component]
fn ClockLabel() -> Element {
    let mut ts = use_signal(|| None::<String>);

    use_effect(move || {
        #[cfg(target_arch = "wasm32")]
        {
            let value = js_sys::Date::new_0().toISOString().into();
            ts.set(Some(value));
        }
    });

    rsx! {
        p {
            match ts() {
                Some(value) => format!("Timestamp: {value}"),
                None => "Timestamp: -".to_string(),
            }
        }
    }
}

Mengapa ini lebih aman? Karena markup awal server dan klien sama-sama menampilkan placeholder yang sama. Nilai dinamis baru diisi setelah fase klien, sehingga tidak mengacaukan hydration.

Trade-off

Pendekatan ini menghilangkan mismatch, tetapi ada konsekuensi: pengguna melihat placeholder sementara. Jika nilai itu penting untuk SEO atau tampilan awal, lebih baik kirim nilainya dari server secara eksplisit daripada menghitung ulang di klien.

Kasus 2: membaca localStorage terlalu dini

Contoh berikut sering menjadi penyebab tema atau preferensi UI berkedip.

use dioxus::prelude::*;

#[component]
fn ThemeBanner() -> Element {
    let theme = {
        #[cfg(target_arch = "wasm32")]
        {
            web_sys::window()
                .and_then(|w| w.local_storage().ok().flatten())
                .and_then(|s| s.get_item("theme").ok().flatten())
                .unwrap_or_else(|| "light".to_string())
        }
        #[cfg(not(target_arch = "wasm32"))]
        {
            "light".to_string()
        }
    };

    rsx! {
        div { class: "theme-{theme}", "Tema aktif: {theme}" }
    }
}

Pada server, tema selalu light. Di browser, bisa jadi dark. Hasilnya: banner dan class CSS berubah sesaat setelah hydration, menimbulkan flicker yang jelas.

Perbaikan: gunakan state awal deterministik lalu sinkronkan di klien

use dioxus::prelude::*;

#[component]
fn ThemeBanner() -> Element {
    let mut theme = use_signal(|| "light".to_string());

    use_effect(move || {
        #[cfg(target_arch = "wasm32")]
        {
            if let Some(value) = web_sys::window()
                .and_then(|w| w.local_storage().ok().flatten())
                .and_then(|s| s.get_item("theme").ok().flatten())
            {
                theme.set(value);
            }
        }
    });

    rsx! {
        div { class: "theme-{theme()}", "Tema aktif: {theme()}" }
    }
}

Di sini, server dan klien sama-sama memulai dari light. Setelah mount, klien boleh menyesuaikan ke nilai aktual dari browser.

Catatan: jika Anda ingin menghindari perubahan visual tema setelah mount, pertimbangkan menerapkan tema melalui mekanisme terpisah sebelum aplikasi ter-hydrate, misalnya lewat script awal atau atribut HTML yang sudah disiapkan server. Namun, ini perlu desain yang konsisten agar SSR dan hydration tetap sinkron.

Kasus 3: state login atau preferensi yang berbeda

Kesalahan umum lainnya adalah menjadikan storage browser sebagai sumber kebenaran utama saat render pertama.

use dioxus::prelude::*;

#[component]
fn UserMenu() -> Element {
    let is_logged_in = {
        #[cfg(target_arch = "wasm32")]
        {
            web_sys::window()
                .and_then(|w| w.local_storage().ok().flatten())
                .and_then(|s| s.get_item("token").ok().flatten())
                .is_some()
        }
        #[cfg(not(target_arch = "wasm32"))]
        {
            false
        }
    };

    rsx! {
        if is_logged_in {
            button { "Logout" }
        } else {
            button { "Login" }
        }
    }
}

Server selalu merender tombol Login, klien mungkin langsung merender Logout. Ini mismatch klasik.

Perbaikan: pastikan sumber state awal sama

Pola yang lebih stabil:

gunakan informasi autentikasi yang juga diketahui server, misalnya cookie atau data request yang disuntikkan ke SSR,
jika itu tidak memungkinkan, render status netral dulu, lalu verifikasi di klien setelah mount,
jangan jadikan storage browser sebagai sumber render awal SSR.

use dioxus::prelude::*;

#[derive(Clone, PartialEq)]
enum AuthState {
    Unknown,
    LoggedOut,
    LoggedIn,
}

#[component]
fn UserMenu() -> Element {
    let mut auth = use_signal(|| AuthState::Unknown);

    use_effect(move || {
        #[cfg(target_arch = "wasm32")]
        {
            let has_token = web_sys::window()
                .and_then(|w| w.local_storage().ok().flatten())
                .and_then(|s| s.get_item("token").ok().flatten())
                .is_some();

            auth.set(if has_token {
                AuthState::LoggedIn
            } else {
                AuthState::LoggedOut
            });
        }
    });

    rsx! {
        match auth() {
            AuthState::Unknown => rsx! { button { disabled: true, "Memuat..." } },
            AuthState::LoggedOut => rsx! { button { "Login" } },
            AuthState::LoggedIn => rsx! { button { "Logout" } },
        }
    }
}

Pendekatan ini menghindari asumsi palsu pada tahap SSR. Jika autentikasi memang harus akurat sejak HTML awal, server harus menerima informasi yang sama dengan yang dipakai klien.

Pola aman untuk logika yang hanya boleh jalan di klien

1. Pisahkan render awal dari sinkronisasi klien

Aturan praktisnya: render pertama harus bisa dijalankan tanpa window, tanpa waktu lokal, tanpa random, dan tanpa data yang hanya ada di browser. Setelah itu, baru sinkronkan state di hook/effect yang berjalan di klien.

2. Gunakan placeholder yang stabil

Placeholder bukan sekadar kosmetik. Dalam SSR, placeholder berfungsi menjaga output awal tetap identik. Contohnya:

Memuat... untuk data browser,
tema default yang konsisten,
struktur HTML tetap, hanya isi teks yang diperbarui kemudian.

3. Hindari cabang render yang sangat berbeda di server dan klien

Semakin besar perbedaan struktur DOM, semakin besar peluang event dan state terasa janggal. Jika perubahan hanya pada teks atau class, dampaknya biasanya lebih kecil daripada mengganti seluruh subtree komponen.

4. Buat initial state deterministik

Deterministik berarti input yang sama menghasilkan output render yang sama. Untuk SSR, ini berarti server dan klien harus memulai dari nilai yang identik. Beberapa cara mencapainya:

server menyuntikkan state awal ke halaman,
komponen menerima props yang sudah diputuskan server,
klien memakai nilai default yang sama lalu melakukan update setelah mount.

Mengapa event handler bisa terasa bermasalah

Ketika hydration mismatch terjadi, framework mungkin perlu menyelaraskan node DOM dengan representasi virtual komponen. Dalam kondisi tertentu, elemen yang Anda lihat sesaat setelah SSR bukan lagi elemen yang sama setelah hydration selesai. Inilah sebabnya klik pertama kadang terasa tidak konsisten atau state input seperti “meloncat”.

Masalah ini sering disalahartikan sebagai bug pada callback, padahal pemicunya adalah render awal yang tidak stabil. Karena itu, sebelum men-debug handler, pastikan dulu:

teks dan atribut hasil SSR sama dengan render klien pertama,
tidak ada penggunaan random/waktu saat render,
tidak ada akses storage/browser API di fase awal,
struktur list dan key item stabil.

Checklist debugging Rust Dioxus SSR

Berikut checklist praktis agar mismatch mudah direproduksi dan diperbaiki.

1. Cari semua sumber nilai non-deterministik

SystemTime::now()
generator angka acak
ID unik yang dibuat saat render
format tanggal berdasarkan zona waktu browser

Jika nilai itu muncul di render awal, ubah menjadi props server atau hitung setelah mount.

2. Audit akses API browser

window
document
localStorage / sessionStorage
ukuran layar, media query, atau preferensi sistem

Semua itu sebaiknya tidak menentukan markup SSR secara langsung.

3. Bandingkan output server dan klien pertama

Cara berpikir yang berguna: tanyakan, “Jika komponen ini dievaluasi dua kali, satu di server dan satu di browser, apakah hasil HTML awalnya identik?” Jika jawabannya tidak, Anda hampir pasti menemukan sumber flicker.

4. Bekukan state awal

Untuk reproduksi bug, paksa state awal menjadi nilai konstan. Misalnya:

set tema default tetap,
nonaktifkan pembacaan storage sementara,
gunakan data mock yang sama di server dan klien.

Jika flicker hilang, penyebabnya ada pada state awal yang tidak sinkron.

5. Uji dengan kondisi browser yang berbeda

Masalah hydration sering hanya muncul pada kondisi tertentu:

storage sudah berisi preferensi lama,
tab pertama vs reload,
zona waktu atau locale berbeda,
ukuran viewport yang memengaruhi cabang render.

6. Minimalkan komponen sampai mismatch terlihat jelas

Jika satu halaman besar sulit dianalisis, ambil komponen yang dicurigai lalu sederhanakan. Hapus fetch, context, dan styling yang tidak relevan sampai hanya tersisa logika render awal. Ini biasanya membuat akar masalah cepat terlihat.

7. Periksa list dan key

Walaupun topik utama di sini adalah SSR mismatch, list yang key-nya tidak stabil juga bisa membuat DOM tampak “berganti sendiri”. Pastikan item daftar memiliki identitas yang konsisten, bukan berdasarkan index yang berubah-ubah.

Strategi perbaikan yang paling efektif

Pilih satu sumber kebenaran untuk render awal

Jika state awal penting untuk SSR, server harus tahu nilainya. Jika server tidak bisa tahu, jangan berpura-pura tahu. Render placeholder atau status netral, lalu sinkronkan di klien.

Jangan hitung state awal dari environment yang berbeda

Server dan browser adalah environment berbeda. Kode yang bergantung pada waktu lokal, storage, viewport, atau objek DOM hampir selalu berisiko bila dijalankan saat render awal.

Utamakan perubahan kecil setelah hydration

Jika update klien memang perlu, usahakan perubahan sesudah mount seminimal mungkin. Mengganti teks lebih aman daripada mengganti struktur besar komponen. Ini mengurangi flicker dan menurunkan kemungkinan perilaku interaktif yang terasa janggal.

Pola ringkas yang bisa dijadikan aturan tim

Render awal harus deterministik.
Jangan akses browser API di fase render SSR.
Gunakan effect untuk sinkronisasi state klien.
Jika server tidak tahu nilainya, tampilkan placeholder yang stabil.
Pastikan state awal server dan klien identik sebelum hydration.

Penutup

Masalah utama pada Rust Dioxus SSR saat menghadapi UI flicker dan state hydration tidak stabil biasanya bukan pada rendering itu sendiri, melainkan pada asumsi bahwa server dan klien bisa memulai dari state yang berbeda lalu tetap menghasilkan markup yang sama. Asumsi ini hampir selalu salah.

Jika Anda menemukan konten berubah setelah mount, event terasa aneh, atau tema/login meloncat sesaat setelah halaman tampil, mulai dari tiga hal: hilangkan nilai non-deterministik saat render, pindahkan akses browser ke fase klien yang aman, dan buat initial state benar-benar konsisten. Dengan pola ini, mismatch jauh lebih mudah direproduksi, dipahami, dan diperbaiki.

Quick Search

shopping_cart Keranjang