Debug Hydration Error Pasca-Deploy: Solusi Locale Desync di Next.js SSR

Hydration error sering kali lolos dari pengujian lokal dan baru meledak di production (Vercel, AWS Lambda, Cloudflare Workers). Manifestasinya berupa React error #418 atau #423: representasi DOM hasil server-side rendering (SSR) tidak identik dengan initial render pohon virtual DOM di browser.

Penyebab paling umum pasca-deploy adalah locale desync dan timezone divergence. Mesin lokal developer menjalankan Node.js dengan zona waktu lokal (misal Asia/Jakarta atau UTC+7) dan locale OS user (misal id-ID atau en-US). Sebaliknya, environment production runtime (container Docker, serverless edge, Lambda) hampir selalu berjalan pada timezone UTC dengan default locale dasar (C.UTF-8 atau en-US minimal).

Mengapa Locale Desync Memicu React Error #418 dan #423

React 18+ mengandalkan konsistensi absolut antara string HTML hasil SSR dan output first render client. Saat komponen mengeksekusi API seperti new Date().toLocaleDateString() atau Intl.NumberFormat() tanpa parameter eksplisit:

• Di Server (Production): Intl memformat tanggal menggunakan timezone UTC dan locale environment runtime container.
• Di Browser Klien: Intl memformat tanggal yang sama menggunakan timezone perangkat user (misalnya WITA/UTC+8) dan locale browser preferensi user.

Perbedaan satu karakter, spasi NBSP (non-breaking space pada format mata uang), urutan bulan/hari, atau perbedaan jam memicu hydration mismatch. React membatalkan hidrasi parsial dan melakukan de-optimasi dengan re-render penuh di client (error #423) setelah mencatat warning #418 di konsol.

Langkah Reproduksi Mismatch di Lingkungan Localhost

Jangan menguji SSR i18n/formatting hanya dengan npm run dev standar. Simulasikan environment server production dan browser yang bertolak belakang.

1. Override Timezone dan Locale Server

Jalankan server lokal dengan environment variable TZ=UTC:

# Linux / macOS
TZ=UTC npm run dev

# Windows (PowerShell)
$env:TZ="UTC"; npm run dev

2. Override Locale dan Timezone Browser

Buka Chrome DevTools:

1. Buka menu More tools > Sensors.
2. Pada dropdown Location, pilih zona selain UTC (misalnya Tokyo atau London).
3. Ubah bahasa browser via chrome://settings/languages atau gunakan toggle Network Conditions untuk menyetel header Accept-Language yang berbeda.

Solusi 1: Deterministic SSR Menggunakan Content Negotiation via Middleware

Pendekatan terbaik: server dan client menyepakati locale dan timezone yang sama sebelum rendering terjadi. Tangkap preferensi dari header HTTP Accept-Language di middleware Next.js, lalu inject ke context atau header internal.

1. Middleware Content Negotiation

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const SUPPORTED_LOCALES = ['en-US', 'id-ID'];
const DEFAULT_LOCALE = 'en-US';

export function middleware(request: NextRequest) {
  const acceptLang = request.headers.get('accept-language');
  let resolvedLocale = DEFAULT_LOCALE;

  if (acceptLang) {
    const preferred = acceptLang.split(',')[0].trim();
    if (SUPPORTED_LOCALES.includes(preferred)) {
      resolvedLocale = preferred;
    }
  }

  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-resolved-locale', resolvedLocale);

  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  });
}

2. Deterministic Rendering di Server Component

Server Component membaca header tersebut dan memformat data secara eksplisit tanpa mengandalkan locale default runtime mesin.

// app/transaction-summary/page.tsx
import { headers } from 'next/headers';

function formatCurrency(amount: number, locale: string) {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: locale === 'id-ID' ? 'IDR' : 'USD',
    currencyDisplay: 'narrowSymbol',
  }).format(amount);
}

function formatDate(date: Date, locale: string) {
  return new Intl.DateTimeFormat(locale, {
    dateStyle: 'medium',
    timeZone: 'UTC', // Wajib: kunci timezone server dan client ke basis yang sama
  }).format(date);
}

export default async function TransactionPage() {
  const headerList = await headers();
  const locale = headerList.get('x-resolved-locale') ?? 'en-US';
  const txDate = new Date('2025-03-30T10:00:00Z');
  const amount = 1500000;

  return (
    <section>
      <p>Tanggal Transaksi: {formatDate(txDate, locale)}</p>
      <p>Total: {formatCurrency(amount, locale)}</p>
    </section>
  );
}

Solusi 2: Two-Pass Rendering Menggunakan Mount Guard (Client Component)

Gunakan pola ini ketika data wajib mengikuti timezone lokal dan bahasa spesifik dari sistem operasi perangkat user yang tidak dikirimkan lewat HTTP headers.

Render konten statis/fallback pada pass pertama (SSR dan client initial render identik), lalu render data lokal setelah mount selesai.

'use client';

import { useState, useEffect } from 'react';

type DynamicDateProps = {
  dateIsoString: string;
};

export function LocalizedTimestamp({ dateIsoString }: DynamicDateProps) {
  const [formatted, setFormatted] = useState<string | null>(null);

  useEffect(() => {
    // Dijalankan hanya di client pasca-hidrasi selesai
    const date = new Date(dateIsoString);
    setFormatted(
      new Intl.DateTimeFormat(navigator.language, {
        dateStyle: 'full',
        timeStyle: 'short',
      }).format(date)
    );
  }, [dateIsoString]);

  // Pass 1: Render placeholder statis agar SSR cocok dengan initial client render
  if (formatted === null) {
    return <span className="skeleton">Loading date...</span>;
  }

  // Pass 2: Render data lokal perangkat
  return <time dateTime={dateIsoString}>{formatted}</time>;
}

Trade-off: Pola ini memicu Layout Shift (CLS) kecil jika fallback tidak memiliki dimensi yang proporsional, serta memerlukan satu siklus render tambahan di browser.

Evaluasi dan Batasan suppressHydrationWarning

React menyediakan escape hatch berupa atribut suppressHydrationWarning:

<time dateTime={isoDate} suppressHydrationWarning>
  {new Date(isoDate).toLocaleDateString()}
</time>

Batasan Teknis:

• Hanya Berlaku 1 Level (Shallow): Atribut ini hanya mengabaikan perbedaan teks dan atribut pada elemen tempat ia ditempel. Perbedaan struktur tag di dalamnya tetap memicu hydration failure.
• Visual Glitch: Browser akan menampilkan teks server sesaat sebelum langsung meloncat ke teks browser. Untuk angka atau timestamp penting, layout jitter ini merusak User Experience.
• Risiko False Positives: Menempelkan atribut ini secara luas menutupi bug logika rendering lain yang sebenarnya butuh investigasi.

Panduan Memilih Solusi