Window Is Not Defined? Cara Mengatasi Browser API Undefined Next Js dari Penyebabnya

Ditulis oleh Next.js

Error browser API undefined di Next.js muncul karena kode membaca window atau localStorage saat render server. Perbaikannya pindahkan akses itu ke Client Component, ke dalam event handler, atau ke useEffect setelah mount. Tambahan use client saja tidak cukup kalau akses masih terjadi saat render awal.

Penyebab Browser API Undefined di App Router

App Router merender Server Component di server secara default. Lingkungan itu tidak punya objek browser.

Kode seperti window.innerWidth, document.title, navigator.language, atau localStorage.getItem() langsung gagal di sana. Client Component pun tetap dirender sekali di server, lalu dilanjutkan di browser.

Masalah lain muncul saat render server dan browser menghasilkan HTML berbeda. Ini biasa disebut hydration mismatch. Penyebab umum adalah state awal diambil dari localStorage, waktu, atau angka acak.

Tabel Troubleshooting Browser API Undefined

Pesan error Penyebab Arah solusi
window is not defined window dibaca saat render server Pindah ke useEffect atau event
document is undefined DOM diakses sebelum mount Gunakan ref dan akses setelah mount
localStorage null saat load State awal bergantung browser Pakai state netral, isi setelah mount

BACA JUGA:

Cara Mengatasi Browser API Undefined Next Js dengan Aman

Ikuti urutan ini agar render server tetap stabil dan browser mendapat data benar.

  1. Pindahkan komponen yang memakai browser API ke file Client Component dengan use client.
  2. Hapus akses browser dari badan render. Pindahkan ke event handler seperti onClick atau ke useEffect.
  3. Untuk data tersimpan, render state netral dulu seperti loading atau string kosong, lalu isi dari localStorage setelah mount.
  4. Tambah guard sebelum akses langsung, terutama untuk kode pihak ketiga.
if (typeof window !== "undefined") {
  const theme = localStorage.getItem("theme");
}
  • window untuk ukuran layar, scroll, dan URL client
  • document untuk query DOM dan fokus elemen
  • localStorage dan sessionStorage untuk preferensi pengguna
  • navigator untuk bahasa, clipboard, dan geolocation
  • matchMedia untuk dark mode dan breakpoint

FAQ

Apakah cukup tambah use client agar error hilang?

Tidak. Client Component tetap dirender di server, jadi akses browser harus menunggu mount atau event.

Kapan browser API boleh dibaca langsung?

Hanya di dalam event handler, useEffect, atau setelah guard typeof window memastikan kode berjalan di browser.

Bagaimana atasi hydration error karena localStorage?

Render nilai default yang sama di server dan client, lalu perbarui state dari localStorage setelah mount.

Artikel Terkait