Race state saat hydration React terjadi ketika nilai yang dipakai untuk render awal klien berbeda dari HTML hasil render server, atau ketika update lain tiba sebelum hydration selesai. Gejalanya dapat berupa peringatan hydration mismatch, konten yang berubah sesaat, atau hasil async lama yang menimpa data terbaru.

Solusinya bukan menunda semua update secara membabi buta. Pastikan render awal klien menggunakan snapshot yang sama dengan server, gunakan useSyncExternalStore untuk membaca state eksternal, dan cegah hasil async usang menulis state.

Urutan render dan sumber race

Dalam aplikasi dengan server-side rendering, urutan umumnya adalah:

  1. Render server: React menghasilkan HTML dari data yang tersedia di server.
  2. Render awal klien: React membangun pohon awal di browser. Untuk hydration yang cocok, hasil render ini harus konsisten dengan HTML server.
  3. Hydration selesai dan update berikutnya: React menghubungkan event handler, lalu aplikasi dapat menampilkan perubahan dari browser, store eksternal, atau operasi async.

Race muncul jika render awal klien membaca nilai yang tidak tersedia atau berbeda di server, misalnya localStorage, waktu saat ini, atau state store yang berubah. Race lain terjadi ketika beberapa permintaan async selesai tidak berurutan: permintaan lama dapat menimpa hasil permintaan terbaru.

Diagnosis: temukan siapa yang menulis state dan kapan

Mulailah dengan mencatat sumber nilai yang berubah, waktu pembacaan, dan semua jalur yang dapat menulisnya. Periksa khususnya kode yang membaca browser API saat render, langganan store, efek yang berjalan setelah mount, serta callback async.

  • Jika ada peringatan hydration mismatch, bandingkan nilai render server dengan render awal klien. Jangan menganggap peringatan itu sekadar masalah tampilan.
  • Jika konten berubah setelah halaman muncul, cari pembacaan localStorage, ukuran layar, atau state eksternal yang dilakukan langsung saat render.
  • Jika data kembali ke nilai lama, periksa apakah permintaan sebelumnya selesai setelah permintaan terbaru.

Tambahkan pencatatan sementara pada titik baca dan tulis, termasuk ID permintaan atau versi state. Hindari logging seluruh objek sensitif di lingkungan produksi.

Jaga snapshot awal tetap konsisten

Jangan membaca state browser secara langsung dalam render yang juga dipakai untuk hydration. Berikan nilai awal yang sama kepada server dan klien, lalu baca state browser setelah render awal klien. Contoh berikut menampilkan preferensi server terlebih dahulu dan menyinkronkannya dengan localStorage setelah mount.

import { useEffect, useState } from 'react';

type Theme = 'light' | 'dark';

function ThemeLabel({ initialTheme }: { initialTheme: Theme }) {
  const [theme, setTheme] = useState(initialTheme);

  useEffect(() => {
    const saved = localStorage.getItem('theme');
    if (saved === 'light' || saved === 'dark') {
      setTheme(saved);
    }
  }, []);

  return <span>Tema: {theme}</span>;
}

Pastikan initialTheme yang dipakai server juga dikirim ke klien sebagai props atau data bootstrap. Jangan menghitung nilai awal secara berbeda di kedua lingkungan. Pendekatan ini dapat menampilkan nilai sementara sebelum efek berjalan; jika kilatan perubahan tidak dapat diterima, kirim preferensi dari server melalui mekanisme yang sesuai dengan arsitektur aplikasi.

Gunakan useSyncExternalStore untuk state eksternal

Store di luar React perlu menyediakan langganan, snapshot terkini, dan snapshot khusus server. useSyncExternalStore menghubungkan pembacaan snapshot dengan perubahan store; fungsi getServerSnapshot menyediakan nilai yang dipakai pada server dan render awal hydration. Nilai server tersebut harus cocok dengan data yang tersedia pada klien saat hydration.

import { useSyncExternalStore } from 'react';

function createStore<T>(initialSnapshot: T) {
  let snapshot = initialSnapshot;
  const listeners = new Set<() => void>();

  return {
    getSnapshot: () => snapshot,
    getServerSnapshot: () => initialSnapshot,
    subscribe(listener: () => void) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
    set(next: T) {
      if (Object.is(snapshot, next)) return;
      snapshot = next;
      listeners.forEach((listener) => listener());
    },
  };
}

const store = createStore({ count: 0 });

function Counter() {
  const state = useSyncExternalStore(
    store.subscribe,
    store.getSnapshot,
    store.getServerSnapshot
  );

  return <button onClick={() => store.set({ count: state.count + 1 })}>
    Hitung: {state.count}
  </button>;
}

Contoh ini memakai snapshot awal tetap, sehingga sesuai untuk data awal yang memang sama pada server dan klien. Untuk state yang berbeda per permintaan, buat store per request dan sertakan snapshot yang sama dalam data bootstrap klien. Jangan memakai store global server untuk data pengguna: nilainya dapat bocor antarpermintaan. getSnapshot juga harus mengembalikan referensi yang stabil selama state tidak berubah; membuat objek baru pada setiap pemanggilan dapat memicu render berulang.

Abaikan hasil async yang sudah usang

Jika efek memulai operasi async, batalkan operasi bila memungkinkan atau tandai hasilnya agar callback lama tidak menulis state. Contoh berikut memakai AbortController untuk membatalkan permintaan sebelumnya saat parameter berubah atau komponen dilepas.

import { useEffect, useState } from 'react';

type User = { name: string };

function UserName({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);

  useEffect(() => {
    const controller = new AbortController();

    async function load() {
      try {
        const response = await fetch(`/api/users/${userId}`, {
          signal: controller.signal,
        });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        const nextUser: User = await response.json();
        setUser(nextUser);
      } catch (error) {
        if (error instanceof Error && error.name !== 'AbortError') {
          console.error('Gagal memuat pengguna', error);
        }
      }
    }

    load();
    return () => controller.abort();
  }, [userId]);

  return <span>{user?.name ?? 'Memuat…'}</span>;
}

Pembatalan mencegah hasil permintaan yang dibatalkan dipakai oleh contoh ini. Untuk operasi yang tidak mendukung pembatalan, gunakan penanda lokal yang diubah pada cleanup dan periksa penanda sebelum menulis state. Jika beberapa permintaan dapat berjalan bersamaan, tetapkan aturan eksplisit: hanya hasil untuk parameter atau ID permintaan terbaru yang boleh diterapkan.

Batasi penulis state dan uji urutan update

Prinsip disjointness dapat menjadi inspirasi untuk membagi kepemilikan state: hindari beberapa bagian aplikasi menulis nilai yang sama tanpa aturan koordinasi. Artikel type-level disjointness membahas gagasan membatasi tumpang tindih secara tipe. Ini dapat membantu membentuk API agar penulis state lebih jelas, tetapi TypeScript tidak mencegah race saat runtime; urutan callback, request, dan perubahan browser tetap perlu ditangani oleh implementasi.

Uji perilaku, bukan hanya hasil akhir render:

  • Render server dengan snapshot awal tertentu, lalu hydrate menggunakan snapshot yang sama. Pastikan tidak ada peringatan mismatch.
  • Ubah state browser setelah render awal. Pastikan UI beralih ke nilai browser tanpa mengubah snapshot awal yang diperlukan untuk hydration.
  • Jalankan dua permintaan dengan urutan mulai dan selesai yang berbeda. Pastikan hasil lama tidak menimpa hasil terbaru.
  • Untuk store eksternal, ubah snapshot dan pastikan komponen menerima update; verifikasi juga snapshot server yang dipakai saat hydration.

Jika memakai lingkungan pengujian yang tidak mendukung hydration server, pisahkan uji fungsi snapshot dan penanganan hasil usang, lalu tambahkan uji integrasi di lingkungan yang menjalankan SSR. Saat debugging, catat ID permintaan dan versi snapshot untuk mengungkap penulis yang terlambat.

Ringkasan pilihan

  • Untuk nilai awal yang harus sama di server dan klien, kirim snapshot awal yang sama dan baca state browser setelah render awal.
  • Untuk store eksternal, gunakan useSyncExternalStore dengan getServerSnapshot yang sesuai dengan data bootstrap.
  • Untuk operasi async, batalkan pekerjaan lama atau abaikan hasilnya sebelum menulis state.
  • Kurangi penulis state yang saling tumpang tindih, tetapi tetap tangani sinkronisasi saat runtime.