Render mismatch adalah perbedaan antara output server-side dan html yang dihasilkan oleh klien saat hydration. Di Nuxt 4, mismatch sering muncul karena state yang berubah secara asinkron atau objek yang tidak ter-serialize dengan benar. Artikel ini langsung menjawab bagaimana memetakan mismatch tersebut dengan snapshot state, alat debug, dan penyesuaian lifecycle.

Mengidentifikasi Render Mismatch di Nuxt 4

Langkah pertama adalah memastikan perbedaan berasal dari state, bukan bug rendering murni. Gunakan log build dan konsol browser untuk melihat pesan hydration warning. Jika mismatch hanya terjadi pada komponen tertentu, catat prop atau computed yang terlibat sebelum melangkah ke snapshot.

Snapshot State Sebelum dan Setelah SSR

Anda bisa menangkap snapshot state dengan menambahkan hook di root layout atau plugin yang meng-serialize state sebelum dikirim ke klien dan setelah klien menyalin kembali state tersebut. Gunakan file JSON sementara atau console.table untuk membandingkan bentuknya.

export default defineNuxtPlugin((nuxtApp) => {
  if (process.server) {
    nuxtApp.hook('app:rendered', ({ HTML }) => {
      console.log('Snapshot sebelum hydration', JSON.stringify(nuxtApp.payload.data));
    });
  }
  if (process.client) {
    nuxtApp.hook('app:mounted', () => {
      console.log('Snapshot setelah hydration', nuxtApp.payload.data);
    });
  }
});

Bandingkan snapshot di keduanya untuk memastikan struktur, tipe data, dan nilai sama persis. Fokus pada properti yang sering berubah seperti timestamp, ID dinamis, atau hasil fetch yang tidak disimpan secara deterministik.

Tooling: Vue Devtools dan Snapshot DOM

Vue Devtools tetap penting untuk melihat tree component dan state pada saat klien berjalan. Mulailah dengan menandai komponen yang mengalami mismatch, lalu buka tab "Events" untuk mencari hook mounted/destroyed yang memicu perubahan DOM. Untuk snapshot DOM, gunakan fitur browser yang menyimpan struktur DOM pada waktu tertentu (misalnya, Chrome DevTools > Rendering > Capture DOM snapshot). Bandingkan snapshot server (rendered view-source) dan client snapshot untuk melihat elemen yang berubah.

Menangani State Serialisasi dan Watch

Perbedaan sering terjadi ketika state yang diteruskan lewat payload tidak mudah di-serialize, misalnya Date atau Map. Nuxt sudah melakukan JSON.stringify untuk payload, sehingga pastikan data Anda kompatibel.

Strategi Serialisasi Aman

Gunakan helper untuk menormalisasi state sebelum disimpan di store atau payload:

function normalizeForHydration(data) {
  return JSON.parse(JSON.stringify(data, (_key, value) => {
    if (value instanceof Date) {
      return value.toISOString();
    }
    return value;
  }));
}

Panggil helper ini sebelum menyet state di server dan sebelum penggunaan di lifecycle client. Hindari menyimpan fungsi, Symbol, atau referensi DOM langsung karena tidak akan muncul di hasil serialisasi.

Debug Watch Asynchronous DOM Changes

Watcher yang menjalankan setTimeout atau fetch pada mounted kadang menulis DOM berbeda setelah hydration. Gunakan watch dengan { immediate: false } bila Anda tidak ingin memicu perubahan selama server rendering. Selain itu, pastikan watcher beroperasi pada state yang sudah pasti ada saat SSR, atau bungkus logika asynchronous dalam blok if (process.client).

Contoh kasus: watch axios request yang memutakhirkan DOM berdasarkan ukuran layar. Jika operasi ini berjalan sebelum hydration selesai, hasil DOM saat client bisa berbeda. Solusinya adalah menunda update sampai hydration event selesai atau gunakan class CSS untuk menyembunyikan elemen sampai data valid.

Sinkronisasi Props, Lifecycle, dan Plugin

Komponen yang menerima prop asynchronous harus memastikan nilai awal sama antara server dan client. Jika prop memiliki default yang bergantung pada window atau plugin client-only, hijack dengan state fallback yang konsisten.

Plugin Nuxt yang mengubah DOM, misalnya menambahkan kelas saat inisialisasi, harus dijalankan dalam lifecycle yang seragam. Pastikan plugin memeriksa konteks dengan flag seperti if (process.client) dan hanya memodifikasi DOM setelah hydration selesai.

Untuk plugin yang perlu berjalan baik di server maupun client, batasi efek samping ke state store, bukan langsung ke DOM. Registrasi komponen global sebaiknya tidak mengubah atribut DOM pada saat setup.

Langkah Reproduksi dan Metrik yang Dipantau

  1. Reproduksi: Render halaman terkena mismatch, jalankan devtools, dan catat perubahan DOM serta state.
  2. Snapshot: Ambil JSON state dari server dan klien lalu bandingkan dengan diff tool atau perbandingan manual.
  3. Debug: Gunakan Vue Devtools untuk menginspeksi props/emit serta DOM snapshot untuk perbedaan struktur.
  4. Metrik: Monitor frekuensi hydration warning di console, ukuran payload (untuk memastikan snapshots tidak terlalu besar), dan waktu yang dibutuhkan hingga mounted selesai (menandakan async loop tertangani).

Jika mismatch terus muncul, periksa lifecycle hooks (onBeforeMount vs onMounted) dan pastikan plugin lain tidak menulis DOM secara langsung selama hydration.

Kesimpulan dan Praktik Terbaik

Sebisa mungkin, jaga agar state yang digunakan saat render server sama persis dengan state awal di client. Memetakan render mismatch berhasil lewat snapshot state, devtools, serta kontrol ketat pada serialisasi dan watcher. Ketika Anda mengetahui faktor penyebabnya—props tidak konsisten, plugin DOM, atau watcher async—maka perbaikan bisa ditargetkan dengan lebih cepat.