Render mismatch SSR terjadi ketika markup yang dihasilkan server berbeda dari versi klien setelah hydration. Penyebab umum adalah efek samping yang langsung mengubah state lokal saat komponen berjalan di browser, sehingga React mengganti DOM dan menimbulkan peringatan. Untuk mengidentifikasi masalah ini, fokuslah pada perubahan state yang tidak ditunggu sampai lifecycle klien—misalnya nilai yang berubah di event handler atau state default yang langsung dihitung dengan data client-only.

Judul artikel ini menggunakan istilah utama render mismatch SSR, sehingga sekarang kita akan membahas pengenalan, deteksi, dan solusi dengan tetap menjaga data server-rendered tetap konsisten setelah hydration.

Memahami Sumber Render Mismatch SSR

Render mismatch terjadi ketika state yang digunakan di server berbeda dari state yang tersedia saat client pertama kali menjalankan React. Kasus khas: komponen menggunakan state lokal yang defaultnya ditentukan berdasarkan objek global (misalnya window atau localStorage) tanpa menunggu efek sisi klien. Karena server tidak menyertakan objek tersebut, markup awal tidak mencerminkan perubahan saat client menjalankan code dan hydratasi.

Contoh lain: komponen menyetel state berdasarkan event listener atau API yang hanya tersedia di browser. Saat komponen dirender server, state tetap default; namun begitu client menjalankan lifecycle, state pengganti menghasilkan DOM berbeda. React memperingatkan mismatch karena atribut, teks, atau struktur berubah.

Untuk mencegahnya, pastikan state yang dapat berubah bergantung pada efek klien atau event handler, bukan hasil render server langsung. Gunakan state initial untuk markup yang aman, lalu lakukan penyelarasan di useEffect agar DOM tetap konsisten.

Deteksi dan Debugging Render Mismatch

Berikut praktik untuk menemukan dan memahami render mismatch:

  • Console Warning: React biasanya menampilkan pesan "Hydration failed" atau "Text content does not match" di console. Catat elemen yang disebutkan dan lihat props/state terkait.
  • React DevTools: Periksa state komponen setelah hydration. Jika state berubah drastis langsung setelah mount tanpa interaksi user, itu kandidat mismatch.
  • Next.js Dev Overlay: Saat terjadi mismatch, next dev server memberi overlay yang menjelaskan file dan komponen yang terlibat.
  • Snapshot simple: Render komponen di server (misalnya dengan npm run dev) dan bandingkan dengan markup client menggunakan browser devtools. Lacak elemen yang berbeda.

Gunakan logging strategis pada lifecycle: tempatkan console.log di useEffect untuk melihat kapan state berubah. Jika perubahan terjadi sebelum event user atau data async selesai, Anda bisa mengidentifikasi efek samping yang harus ditunda.

Strategi Penyelarasan State

Memindahkan Logika ke useEffect

Solusi umum adalah memastikan state lokal yang tergantung pada data client diproses di useEffect. Karena useEffect hanya berjalan di client setelah hydration, server tidak mengubah state ini dan markup awal tetap konsisten.

function ThemeToggle({ themeFromServer }) {
  const [theme, setTheme] = useState(themeFromServer);

  // Efek hanya dijalankan di client
  useEffect(() => {
    const localTheme = localStorage.getItem('theme');
    if (localTheme && localTheme !== theme) {
      setTheme(localTheme);
    }
  }, []);

  return (
    <button onClick={() => setTheme('dark')}>Tema: {theme}</button>
  );
}

Pada contoh di atas, theme default berasal dari server. Pembaruan berdasarkan localStorage hanya terjadi di client, sehingga DOM server dan client tetap sinkron sampai efek dijalankan.

Event Handler yang Tidak Mengubah Markup Kritis

Jika state diubah di event handler (misalnya onClick), pastikan perubahan tidak langsung meretrigger markup utama sebelum user berinteraksi. Hindari menginisialisasi state dengan event yang terjadi selama hydration.

Untuk data yang perlu disinkronkan dengan server (misalnya status autentikasi), gunakan pattern berikut:

  • Muat nilai default di server melalui props.
  • Gunakan useEffect untuk memvalidasi/menyesuaikan nilai tersebut jika client memiliki informasi lebih lanjut.
  • Gunakan flag seperti isHydrated untuk menahan render bagian yang sangat sensitif sampai state sudah sinkron.

Praktik Penjajaran Data Server dan Client

Berikut langkah praktis menyelaraskan data:

  1. Ambil data di getServerSideProps/getStaticProps untuk server render.
  2. Gunakan props tersebut sebagai initial state pada komponen klien.
  3. Tunda perubahan yang hanya diketahui client sampai useEffect dijalankan.
  4. Tandai bagian markahp yang rentan dan siapkan fallback (misalnya skeleton) supaya markup awal tetap valid.

Contoh pattern Next.js:

export async function getServerSideProps(context) {
  const data = await fetchFromAPI(context);
  return { props: { data } };
}

function Page({ data }) {
  const [value, setValue] = useState(data);
  const [isHydrated, setHydrated] = useState(false);

  useEffect(() => {
    setHydrated(true);
    const freshValue = checkClientCache();
    if (freshValue !== value) {
      setValue(freshValue);
    }
  }, []);

  if (!isHydrated) {
    return <div>Loading...</div>;
  }

  return <div>{value.content}</div>;
}

Dengan tambahan flag isHydrated, Anda mencegah render bagian akhir sebelum state client tersinkronisasi. Ini mengurangi peluang mismatch karena DOM awal tidak digantikan sebelum state final tersedia.

Kesalahan Umum dan Tips Debugging

Berikut beberapa kesalahan yang sering terjadi:

  • Menginisialisasi state dengan window atau API client-only di luar efek.
  • Mengandalkan data async dalam render tanpa memeriksa apakah sudah tersedia di client.
  • Menggunakan useLayoutEffect untuk data yang dipersiapkan di server (karena akan terdeteksi berbeda saat server render). Gunakan useEffect atau pisahkan logika ke dalam komponen yang hanya dirender di client.

Debugging tip: tahan tombol Shift dan refresh halaman untuk memaksa re-hydration penuh pada Next.js dev server, lalu lihat console untuk pesan mismatch. Sinkronisasi ulang props/state dan pastikan tidak ada data yang langsung berubah di tahap render pertama.

Kesimpulan

Render mismatch SSR akibat efek samping state lokal pasca hydration bisa dihindari dengan membuat logika client-only berada di useEffect, menunda perubahan sampai state klien siap, dan menggunakan flag sederhana untuk membatasi render sensitif. Gunakan alat debugging seperti React DevTools dan console warnings untuk menemukan bagian yang memicu mismatch. Dengan struktur lifecycle yang jelas, markup server dan client akan tetap konsisten setelah hydration.