Pusing Sama Hydration Error di Next.js App Router? Coba Taktik Clean Code Ini Biar Aman

Lagi asyik-asyiknya ngoding, tiba-tiba konsol kamu merah menyala, isinya pesan horor: "Hydration failed because the initial UI does not match what was rendered on the server." Kalau kamu sudah mulai migrasi atau start project baru pakai Next.js App Router, kemungkinan besar kamu sudah pernah ketemu hantu ini.

Hydration Error ini memang bikin frustrasi. Next.js, apalagi dengan arsitektur Server Components (RSC) yang super canggih di App Router, menuntut kedisiplinan kode yang sangat tinggi. Next.js berusaha memberikan performa terbaik dengan mengirimkan HTML yang sudah jadi (dari Server Side Rendering/SSR), dan tugas browser cuma ‘menempelkan’ JavaScript-nya di atas HTML itu (proses hydration).

Masalahnya muncul ketika React di browser (Client) melihat ada perbedaan antara DOM yang dikirim Server dengan DOM yang dia harapkan setelah kode JavaScript dieksekusi. Ini bisa terjadi karena banyak faktor, mulai dari penggunaan hook yang salah tempat, sampai logika render yang bergantung pada environment tertentu.

Kami di Javapixa Creative Studio, sebagai tim yang fokus pada pengembangan aplikasi modern dan scalable, sering melihat developer muda terjebak di sini. Oleh karena itu, kami akan membagikan taktik clean code yang kami gunakan untuk memastikan aplikasi Next.js App Router berjalan mulus, cepat, dan bebas dari hydration error yang memusingkan.

Ini bukan cuma tentang fixing error, tapi tentang membangun fondasi kode yang kuat dan disiplin.

---

1. Memahami Batasan Next.js App Router: Server Component vs. Client Component

Kunci utama App Router adalah pemisahan tegas antara Server Components (SC) dan Client Components (CC). SC dijalankan di server, tidak punya akses ke state atau hooks seperti useState atau useEffect. CC, yang ditandai dengan "use client", dijalankan di browser dan boleh pakai semua fitur React klasik.

Hydration Error sering terjadi karena kita lupa bahwa output HTML dari SC harus sama persi dengan hasil render awal dari CC.

Taktik 1A: Disiplin Penuh pada "use client"

Banyak developer coba menyelipkan client logic (misalnya, menghitung dimensi layar) langsung di file Page atau Layout yang secara default adalah Server Component. Ini resep bencana.

Taktik Clean Code:

  1. Isolasi Logika Klien: Buat komponen pembungkus (wrapper) spesifik untuk logika yang memerlukan state atau browser APIs.
  2. Jadikan Komponen Daun (Leaf Node): Jangan pernah menaruh direktif "use client" di root Layout (kecuali sangat spesifik). Biarkan sebagian besar komponen utama (Page dan Layout) tetap menjadi Server Component. Hanya tandai komponen paling ujung (misalnya, Navbar yang punya toggle state, atau Button yang perlu onClick interaktif) sebagai Client Component.
  3. Hanya Kirim Props: Server Component hanya boleh mengirimkan data atau function statis sebagai props ke Client Component.

javascript
// BAD PRACTICE: Mencoba menggunakan hook di Server Component
// app/page.js (Default Server Component)

javascript
// GOOD PRACTICE: Mengisolasi client logic
// components/ClientInteractive.jsx
"use client"; // Ditempatkan di baris paling atasimport { useState } from 'react';export default function ClientInteractive() {
  const [count, setCount] = useState(0);
  // ... logika interaktif
  return  setCount(count + 1)}>{count};
}// app/page.js (Server Component)
import ClientInteractive from '@/components/ClientInteractive';export default function HomePage() {
  return (
    
      Selamat Datang!
       {/ Dipanggil sebagai children/prop /}
    
  );
}

Disiplin ini akan mengurangi 50% hydration error yang mungkin kamu temui. Javapixa Creative Studio selalu menekankan pemisahan tanggung jawab kode ini untuk memastikan scalability.

---

2. Mengatasi Konten Dinamis (The Root of All Evil)

Penyebab terbesar hydration error adalah konten yang hanya bisa diketahui setelah browser selesai me-render (misalnya, localStorage, window object, atau user-specific data yang diambil secara client-side).

Ketika Server merender HTML, ia tidak tahu apa isi localStorage pengguna, atau berapa lebar viewport mereka. Ketika klien melakukan hydration, ia membaca localStorage dan merender UI yang berbeda, sehingga terjadi mismatch.

Taktik 2A: Tunda Rendering hingga Komponen Terpasang (Mounting)

Solusi paling efektif adalah memastikan bahwa komponen yang bergantung pada browser API tidak merender konten dinamisnya sama sekali selama fase SSR. Tunda rendering hingga React tahu bahwa komponen tersebut sudah benar-benar mounted di sisi klien.

Blueprint Komponen Dinamis (The isMounted Pattern):

Buat sebuah custom hook atau gunakan useState dan useEffect untuk menunda tampilan konten:

javascript
// components/HydrationSafeWrapper.jsx
"use client";import { useState, useEffect } from 'react';export default function HydrationSafeWrapper({ children }) {
  const [isMounted, setIsMounted] = useState(false);useEffect(() => {
    // Ini hanya berjalan di sisi klien setelah mounting
    setIsMounted(true);
  }, []);if (!isMounted) {
    // Render tampilan statis (misalnya null, atau skeleton loading) saat SSR
    return null; 
    // Atau: return

Dengan membungkus komponen yang rentan (misalnya komponen yang membaca window.innerWidth untuk responsive rendering) dengan HydrationSafeWrapper, kamu menjamin bahwa konten dinamis hanya akan muncul setelah klien mengambil alih.

Taktik 2B: Menangani Tanggal dan Waktu

Kesalahan hydration sering muncul ketika menampilkan tanggal, terutama jika zona waktu (timezone) server berbeda dengan klien.

Contoh masalah:

  • Server merender: "Hari ini: 15.00 WIB" (Waktu server)
  • Klien me-render: "Hari ini: 13.00 WIB" (Waktu klien)

Mismatch!*

Taktik Clean Code:

Jangan pernah merender hasil format tanggal yang bergantung pada zona waktu lokal secara langsung.

  1. Selalu Kirim Timestamp: Kirimkan timestamp mentah (misalnya ISO string atau angka) dari Server Component ke Client Component.
  2. Format di Klien: Biarkan Client Component (yang sudah ditandai "use client") yang bertanggung jawab memformat timestamp tersebut menggunakan Intl.DateTimeFormat atau library seperti date-fns/moment di useEffect.

javascript
// components/TimeDisplay.jsx
"use client";
import { useEffect, useState } from 'react';export default function TimeDisplay({ isoString }) {
  const [displayTime, setDisplayTime] = useState('');useEffect(() => {
    if (isoString) {
      // Formatting di sisi klien, menggunakan timezone lokal
      const date = new Date(isoString);
      setDisplayTime(date.toLocaleTimeString());
    }
  }, [isoString]);

---

3. Integrasi Pihak Ketiga dan Dynamic Imports (SSR: False)

Ketika kita menggunakan library pihak ketiga yang tidak dioptimalkan untuk SSR (misalnya, beberapa charting libraries atau carousel lama), mereka mungkin mencoba mengakses document atau window secara prematur.

Taktik 3A: Menggunakan next/dynamic dengan Opsi ssr: false

Next.js menyediakan solusi elegan melalui dynamic import dengan menonaktifkan Server Side Rendering untuk komponen tersebut. Ini memberi tahu Next.js, "Komponen ini hanya boleh di-render setelah di browser."

Taktik Clean Code:

javascript
import dynamic from 'next/dynamic';// Anggap ChartComponent adalah library yang tidak mendukung SSR
const DynamicChart = dynamic(() => import('@/components/ChartComponent'), {
  // SSR: false adalah kuncinya.
  ssr: false, 
  // Opsional: berikan loading fallback yang akan dirender di sisi server
  loading: () => Memuat chart..., 
});// app/page.js (Server Component)
export default function ChartPage() {
  return (
    
      Data Penjualan
       props dari server /} />
    
  );
}

Dengan cara ini, Server akan merender placeholder (Memuat chart...), dan hanya klien yang akan menjalankan kode ChartComponent. Tidak ada mismatch karena Server tidak pernah mencoba merender output asli dari komponen dinamis tersebut. Di Javapixa Creative Studio, kami selalu menerapkan dynamic import untuk komponen berat atau yang rentan terhadap hydration error.

---

4. Hindari Manipulasi DOM di Luar React (Hati-hati dengan Tools Legacy)

Next.js dan React modern bergantung pada kendali penuh atas DOM. Jika kamu menggunakan library atau utility yang secara langsung memanipulasi DOM (misalnya, $().append() dari jQuery, atau script eksternal yang mengubah struktur HTML), React tidak akan tahu perubahan itu, dan ini 100% akan memicu hydration error.

Taktik 4A: Penggunaan suppressHydrationWarning yang Bertanggung Jawab

React menawarkan prop suppressHydrationWarning. Ini adalah prop yang bilang ke React, "Saya tahu ada sedikit ketidakcocokan antara Server dan Klien, tapi tolong abaikan saja."

Kapan Menggunakannya?

HANYA untuk ketidakcocokan yang tidak dapat dihindari dan minor* (misalnya, perbedaan kecil pada atribut tertentu yang secara fungsional tidak mengubah tampilan).

  • Jangan pernah menggunakannya untuk menutupi perbedaan struktural besar (misalnya, perbedaan jumlah elemenatau ).

Contoh paling umum adalah jika kamu harus merender elemen yang ID-nya dibuat secara acak dan hanya bisa dijamin unik di klien (walaupun ini jarang terjadi di App Router).

jsx

  {/ Konten yang mungkin sedikit berbeda di server/klien /}

Menggunakan taktik ini secara berlebihan adalah tanda code smell. Tim Javapixa melihat ini sebagai jalan keluar terakhir, bukan solusi utama. Solusi utamanya selalu kembali ke Taktik 2A: menunda rendering.

---

5. Clean Code Practice: Custom Hook untuk Mengukur Environment

Untuk menjaga agar file Page kamu tetap bersih dan fokus pada routing dan data fetching (tanggung jawab Server Component), abstraksikan semua logika klien yang sensitif terhadap hydration ke dalam custom hook di file Client Component terpisah.

Taktik 5A: Membuat useClientSideValue Hook

Jika kamu perlu nilai yang hanya ada di klien (seperti localStorage atau sessionStorage), jangan hitung nilainya saat initial render.

javascript
// hooks/useClientSideValue.js
"use client";
import { useState, useEffect } from 'react';// Ambil nilai awal dari storage (default ke nilai SSR)
// Key Storage: Kunci di localStorage, initialValue: Nilai default saat SSR
export function useClientSideValue(storageKey, initialValue) {
  const [value, setValue] = useState(initialValue);
  const [isMounted, setIsMounted] = useState(false);useEffect(() => {
    setIsMounted(true);
    // Jalankan pengambilan data storage HANYA setelah mount di klien
    const storedValue = localStorage.getItem(storageKey);
    if (storedValue) {
      setValue(storedValue);
    }
  }, [storageKey]);// Pastikan kita mengembalikan nilai default saat SSR (isMounted=false)
  if (!isMounted) {
    return initialValue;
  }

Bagaimana Menggunakannya?

Dalam Client Component kamu:

javascript
// components/UserPref.jsx
"use client";
import { useClientSideValue } from '@/hooks/useClientSideValue';export default function UserPref() {
  // Server merender 'light' (initialValue), Klien akan fetch dari localStorage
  const theme = useClientSideValue('user-theme', 'light');return Tema aktif: {theme};
}

Dengan mengimplementasikan hook seperti ini, kamu memastikan bahwa Server Component selalu merender nilai initial yang sama ('light'), dan klien hanya mengubah nilai tersebut setelah proses hydration selesai. Kode jadi lebih rapi, terisolasi, dan mudah di-debug.

---

Penutup: Konsistensi adalah Kunci Next.js

Hydration Error di Next.js App Router seringkali merupakan alarm yang menunjukkan kurangnya disiplin dalam memisahkan logika Server dan Klien. Next.js App Router memang menantang, tapi ia memaksa kita menjadi developer yang lebih baik, lebih teliti dalam manajemen environment dan state.

Di Javapixa Creative Studio, kami percaya bahwa performa aplikasi yang optimal berawal dari clean code yang disiplin. Dengan menerapkan taktik seperti isolasi use client, menunda rendering dinamis menggunakan mount flag, dan memanfaatkan next/dynamic secara bijak, kamu tidak hanya menghilangkan hydration error, tetapi juga membangun aplikasi yang lebih cepat, lebih stabil, dan siap untuk di-deploy di lingkungan produksi yang sesungguhnya.

Jangan biarkan konsol merah mengganggu proses deployment kamu. Terapkan taktik clean code ini, dan coding journey kamu di Next.js akan jauh lebih mulus! Jika kamu butuh tim profesional untuk menangani kompleksitas App Router dan memastikan kode kamu error-free sejak awal, Javapixa Creative Studio siap menjadi mitra kamu.