Hydration error pada dashboard telemetri GPU/GPGPU berbasis React atau Next.js umumnya terjadi akibat state divergence. Server merender status fallback (misalnya generic GPU atau non-CUDA), sedangkan browser langsung mengevaluasi adapter hardware lokal via API seperti navigator.gpu segera setelah script berjalan. Ketidakcocokan antara HTML awal dari server dan virtual DOM client memicu error hydration mismatch.

Akar Masalah: State Divergence Antara SSR dan WebGPU API

Server Node.js tidak memiliki akses ke hardware GPU client, driver lokal (seperti ZLUDA layer atau CUDA toolkit), maupun objek browser navigator.gpu. Akibatnya, server selalu merender markup fallback default:

// Hasil render server
<span class="badge-fallback">DirectX/Vulkan Fallback (Generic)</span>

Jika komponen membaca status WebGPU secara sinkron atau menginisialisasi state dengan nilai hardware pada render pertama client, client langsung menghasilkan:

// Hasil render client (setelah mendeteksi adapter spesifik)
<span class="badge-nvidia">NVIDIA RTX 4090 via WebGPU</span>

React membandingkan kedua DOM tree ini saat fase hydration. Perbedaan tag, teks, atau atribut class akan memutus proses rekonstruksi DOM, menghasilkan error Hydration failed because the initial UI does not match what was rendered on the server.

Pola Perbaikan: Two-Pass Rendering

Solusi deterministik adalah menunda rendering informasi hardware spesifik hingga fase hydration selesai menggunakan pola two-pass rendering. Pass pertama merender fallback deterministik yang identik dengan output SSR. Pass kedua dijalankan setelah komponen terpasang (mounted) via useEffect untuk membaca API hardware.

Implementasi Hook Deteksi WebGPU

Pisahkan logika akses hardware ke dalam custom hook yang aman terhadap SSR:

import { useState, useEffect } from 'react';

interface GPUCapabilities {
  adapterName: string;
  isGPGPUAvailable: boolean;
  driverType: 'native' | 'fallback' | 'undetected';
}

export function useWebGPUInfo(): GPUCapabilities {
  const [info, setInfo] = useState<GPUCapabilities>({
    adapterName: 'Generic Fallback',
    isGPGPUAvailable: false,
    driverType: 'undetected',
  });

  useEffect(() => {
    let isMounted = true;

    async function detectGPU() {
      if (!navigator.gpu) {
        if (isMounted) {
          setInfo({
            adapterName: 'WebGPU Unavailable',
            isGPGPUAvailable: false,
            driverType: 'fallback',
          });
        }
        return;
      }

      try {
        const adapter = await navigator.gpu.requestAdapter();
        if (!adapter) throw new Error('No adapter found');
        
        const info = await adapter.requestAdapterInfo?.();
        if (isMounted) {
          setInfo({
            adapterName: info?.description || adapter.name || 'Discrete/Integrated Adapter',
            isGPGPUAvailable: true,
            driverType: 'native',
          });
        }
      } catch (err) {
        if (isMounted) {
          setInfo({
            adapterName: 'Software Rasterizer / Generic',
            isGPGPUAvailable: false,
            driverType: 'fallback',
          });
        }
      }
    }

    detectGPU();
    return () => { isMounted = false; };
  }, []);

  return info;
}

Render Metrik Tanpa Merusak Tree DOM

Gunakan flag mount eksplisit untuk mengontrol rendering komponen metrik, sehingga struktur tree DOM tetap konsisten selama proses hydration.

'use client';

import { useState, useEffect } from 'react';
import { useWebGPUInfo } from './useWebGPUInfo';

export function GPUMetricsWidget() {
  const [isMounted, setIsMounted] = useState(false);
  const gpu = useWebGPUInfo();

  useEffect(() => {
    // ponytail: upgrade to useSyncExternalStore if reading from mutable external telemetry buffers.
    setIsMounted(true);
  }, []);

  // Render awal identik 100% antara server dan client pass pertama
  if (!isMounted) {
    return (
      <div className="p-4 border rounded bg-zinc-900 text-zinc-400">
        <span className="animate-pulse">Menginisialisasi telemetri GPU...</span>
      </div>
    );
  }

  return (
    <div className="p-4 border rounded bg-zinc-900 text-white">
      <h3 className="text-sm font-mono text-zinc-400">Active Adapter</h3>
      <p className="text-lg font-bold">{gpu.adapterName}</p>
      <span className={`inline-block px-2 py-0.5 mt-2 text-xs rounded ${
        gpu.driverType === 'native' ? 'bg-emerald-800' : 'bg-amber-800'
      }`}>
        {gpu.isGPGPUAvailable ? 'Compute Shaders Active' : 'Fallback Pipeline'}
      </span>
    </div>
  );
}

Opsi Alternatif dan Trade-off

  • Dynamic Import (next/dynamic dengan ssr: false): Mematikan SSR secara total untuk widget terkait. Pendekatan ini lebih ringkas tanpa state tambahan, tetapi widget tidak ada sama sekali dalam HTML mentah, menyebabkan layout shift jika ukuran container tidak disiapkan.
  • CSS Masking / Placeholder: Merender kedua struktur dalam satu container dan menyembunyikan fallback via CSS client class. Opsi ini memiliki kompleksitas tinggi dan berisiko mengekspos layout shift visual jika ukuran teks adapter dinamis.
Gunakan pola two-pass rendering dengan struktur bounding box tetap jika metrik dashboard penting untuk performa visual tanpa Cumulative Layout Shift (CLS).