Hydration mismatch terjadi ketika representasi virtual DOM yang dihasilkan oleh server (Node.js) tidak identik dengan struktur DOM awal yang dibangun oleh browser pada saat eksekusi JavaScript klien. Pada komponen kompleks seperti split-flap board (papan informasi mekanis bandara/stasiun), kesalahan ini sangat umum terjadi akibat divergensi state animasi, sanitasi string, atau kalkulasi dimensi yang bergantung pada browser.

Penyebab Utama Hydration Mismatch pada Split-Flap Board

Komponen split-flap membagi string teks ke dalam matriks grid karakter individual dengan flap atas dan bawah yang berputar menggunakan CSS 3D transforms. Tiga faktor utama pemicu mismatch adalah:

  • Divergensi Padding dan Sanitasi String: Server dan klien memproses panjang string atau spasi pengisi (whitespace padding) secara berbeda, misalnya jika string menggunakan manipulasi string yang bergantung pada locale atau window size.
  • State Awal dan Siklus Animasi: Server langsung merender karakter target akhir atau string kosong, sementara klien memulai state lokal animasi dari karakter awal acak sebelum transisi dimulai.
  • Layout Shift CSS 3D Transform: Browser merender font flap secara dinamis, sementara server tidak memiliki konteks font metrics, menyebabkan perbedaan ukuran kontainer atau teks yang memicu koreksi re-layout saat hydration.

Pola 1: Deterministic Character Matrix

Agar server dan klien menghasilkan struktur DOM yang identik, pembentukan grid karakter harus sepenuhnya murni (pure function) dan deterministik. Jangan membuat perhitungan jumlah kolom berdasarkan lebar viewport saat komputasi awal di server.

// utils/matrix.ts
export function createFlapMatrix(text: string, columns: number, rows: number): string[][] {
  const sanitized = text.toUpperCase().replace(/[^A-Z0-9 ]/g, " ");
  const totalCells = columns * rows;
  const padded = sanitized.padEnd(totalCells, " ").slice(0, totalCells);
  
  const matrix: string[][] = [];
  for (let r = 0; r < rows; r++) {
    const start = r * columns;
    matrix.push(padded.slice(start, start + columns).split(""));
  }
  return matrix;
}

Fungsi di atas menjamin kalkulasi jumlah tag <span> atau <div> flap persis sama di Node.js dan peramban.

Pola 2: Two-Pass Rendering dengan isMounted Guard

Jika flap board memerlukan animasi pembalik karakter saat pertama kali dimuat, hindari memulai state acak pada first render. Gunakan pendekatan rendering dua tahap: render state statis yang stabil pada SSR, lalu aktifkan logika interaktif/animasi setelah komponen terpasang di DOM klien.

// components/SplitFlapBoard.tsx
"use client";

import { useState, useEffect } from "react";
import { createFlapMatrix } from "../utils/matrix";

interface SplitFlapProps {
  targetText: string;
  columns: number;
  rows: number;
}

export function SplitFlapBoard({ targetText, columns, rows }: SplitFlapProps) {
  const [isMounted, setIsMounted] = useState(false);

  useEffect(() => {
    setIsMounted(true);
  }, []);

  // SSR dan First Render klien menggunakan representasi target statis yang identik
  const matrix = createFlapMatrix(targetText, columns, rows);

  return (
    <div className="flap-board">
      {matrix.map((row, rIdx) => (
        <div key={`row-${rIdx}`} className="flap-row">
          {row.map((char, cIdx) => (
            <div key={`cell-${rIdx}-${cIdx}`} className="flap-cell">
              <span className="flap-upper">{char}</span>
              <span className="flap-lower">{char}</span>
              {/* Komponen dinamis/animasi aktif hanya setelah mounted */}
              {isMounted && (
                <div className="flap-animator" data-char={char} />
              )}
            </div>
          ))}
        </div>
      ))}
    </div>
  );
}

Pendekatan ini menjamin HTML hasil SSR cocok 100% dengan virtual DOM hydration awal, tanpa memunculkan peringatan Hydration failed because the initial UI does not match what was rendered on the server.

Pola 3: CSS Font Metrics Pre-Allocation

Perbedaan dimensi karakter sebelum webfont selesai diunduh dapat merusak perhitungan layout. Tetapkan ukuran pasti untuk setiap flap cell pada CSS global atau scoped agar tidak terjadi Cumulative Layout Shift (CLS) dan reflow yang memicu render bug pada transform 3D.

.flap-board {
  display: flex;
  flex-direction: column;
  gap: 4px;
  background-color: #111;
  padding: 16px;
}

.flap-row {
  display: flex;
  gap: 4px;
}

.flap-cell {
  position: relative;
  width: 2rem;
  height: 3rem;
  perspective: 300px;
  font-family: monospace;
  font-size: 2rem;
  line-height: 3rem;
  text-align: center;
  overflow: hidden;
  font-variant-numeric: tabular-nums;
}

Properti font-variant-numeric: tabular-nums; atau penggunaan monospace typeface memastikan setiap slot flap mengonsumsi lebar piksel yang deterministik.

Pola Penanganan: Hindari suppressHydrationWarning Berlebihan

Menambahkan atribut suppressHydrationWarning pada parent container board sering kali disalahgunakan untuk menyembunyikan error. Atribut ini hanya mengabaikan perbedaan atribut teks sedalam satu tingkat; ia tidak memperbaiki node hierarki yang rusak atau hilangnya event listener.

Gunakan opsi berikut secara bijak:

  • Dynamic Import (ssr: false): Jika papan flap sepenuhnya murni visual dan tidak memengaruhi Core Web Vitals atau SEO, nonaktifkan SSR secara eksplisit via dynamic import pada framework Anda.
  • Deterministic Initial State: Jika konten papan flap butuh terindeks mesin pencari, gunakan pendekatan Pola 1 dan Pola 2 di atas tanpa suppressHydrationWarning.