Memahami Render Mismatch React Hydration dan Penyebabnya

Render mismatch terjadi ketika snapshot HTML yang dihasilkan server tidak cocok dengan hasil hydrating pada browser. Dalam konteks Spring Boot mendukung aplikasi React dengan campuran SSR dan CSR, mismatch biasanya disebabkan oleh data state yang berbeda, urutan API yang tidak konsisten, atau cache yang mengembalikan versi lama. Untuk tim backend, solusi pertama adalah memastikan payload yang dikirim ke client adalah sumber kebenaran tunggal untuk state yang di-render.

Pertanyaan inti: Kalau memang mismatch, dari mana asalnya? Jawabannya adalah perbedaan antara initial state yang digunakan oleh server rendering dengan state yang digunakan oleh hydrating React pada client, yang bisa disebabkan oleh routing yang memicu fetch tambahan, header cache tidak sinkron, atau mutasi state di middleware.

Validasi State dari Controller Spring Boot dan Payload Hydration React

Langkah pertama adalah membuat kontrak eksplisit. Setiap endpoint SSR harus mengembalikan JSON yang:

  • Memuat field state dengan struktur tetap.
  • Disertai timestamp atau hash untuk membantu validasi.
  • Tidak dimodifikasi oleh interceptor lain tanpa disadari.

Rencanakan validasi lintas sisi dengan menaruh hash state (misalnya MD5) di payload dan meneruskannya ke React melalui data-attribute atau script inline. Di client, bandingkan hash ini dengan hasil serialisasi state sebelum memanggil ReactDOM.hydrate(). Jika berbeda, log detailnya dan gunakan fallback render client.

Contoh validasi sederhana di JavaScript (React):

const serverState = window.__INITIAL_STATE__ || null;
const expectedHash = window.__INITIAL_STATE_HASH__;
const computedHash = hashState(serverState);
if (expectedHash !== computedHash) {
  console.warn('Render mismatch detected', { expectedHash, computedHash });
  startClientRender();
} else {
  hydrateApp(serverState);
}

Hash generator harus konsisten antara backend dan frontend (misalnya JSON canonicalization + SHA-256). Jika mismatch, jangan langsung abort: catat info tambahan agar bisa tracing.

Menyusun Controller API yang Menyalurkan Data State

Langkah demi langkah untuk controller Spring Boot:

  1. Susun response DTO tunggal yang merepresentasikan seluruh state yang dibutuhkan React.
  2. Gunakan ResponseEntity untuk mengontrol header cache.
  3. Sertakan header tambahan seperti X-Rendered-At atau X-State-Hash.

Contoh controller sederhana:

@RestController
@RequestMapping("/render-state")
public class RenderStateController {

    private final StateService stateService;

    public RenderStateController(StateService stateService) {
        this.stateService = stateService;
    }

    @GetMapping
    public ResponseEntity<RenderStateDto> getRenderState() {
        RenderStateDto payload = stateService.buildInitialState();
        String hash = HashUtil.computeHash(payload);

        return ResponseEntity.ok()
            .cacheControl(CacheControl.noStore())
            .header("X-State-Hash", hash)
            .header("X-Rendered-At", Instant.now().toString())
            .body(payload);
    }
}

Catatan:

  • CacheControl.noStore() memaksa browser mengambil state terbaru.
  • Hash ditampilkan di header karena memudahkan debugging tanpa memasang script payload besar.
  • Konsistensi DTO harus diuji dengan integration test yang memanggil serializer yang sama dengan server rendering.

Menangani Payload SSR/CSR Mix

Untuk SSR yang memuat sebagian HTML, pastikan API ini dipanggil sebelum template Thymeleaf (atau engine lain) merender state. Jika ada API tambahan yang mutasi data (misalnya fetch detail user), koordinasikan agar data SSR tidak memperbarui state setelah DOM dikirimkan.

Strategi Logging, Debugging, dan Pengecekan Hash

Langkah-langkah debugging:

  1. Log request-response pair: Info seperti URI, trace ID, hash state, dan timestamp.
  2. Bandingkan data client dan server: Tulis middleware Spring Boot yang menyimpan snapshot state saat rendering, dan gunakan script React untuk mengirimkan diff ke endpoint debug bila mismatch terdeteksi.
  3. Gunakan tooling seperti Sentry atau Loki: Bila mismatch terus terjadi, catat stack trace dan payload dalam log terstruktur.

Misalnya, middleware dapat menambahkan header X-Correlation-ID dan backend menyimpan snapshot state di log JSON dengan field renderHash. React kemudian dapat mengirim request rekonsiliasi jika hash tidak cocok, menyediakan payload client-side untuk analisis.

Untuk pengecekan hash:

  • Setiap komponen yang menyumbang state harus menyertakan versi data/struktur.
  • Gunakan checksum incremental per komponen bila state besar.
  • Validasi hash di server sebelum mengirim response. Jika hash berubah tidak terduga, susun alert untuk me-review perubahan API.

Kesimpulan dan Langkah Lanjutan

Render mismatch React hydration adalah sinyal data tidak sinkron antara server dan client. Tim backend Spring Boot harus menyelesaikan kontrak state yang eksplisit, menyediakan hash/metadata yang dapat divalidasi, serta menjaga logging yang cukup untuk tracing. Langkah-langkah di atas (validasi state, controller API dengan header hash, caching yang tepat, dan strategi debugging) membantu menjaga UI tetap konsisten meskipun aplikasinya menggabungkan SSR dan CSR.

Implementasi yang rapi tidak hanya memperbaiki mismatch, tetapi juga menyederhanakan troubleshooting ketika UI menampilkan perilaku tak terduga saat hydration berlangsung.