Cara Memperbaiki Halaman Putih Kosong di Aplikasi Web Kamu

Halaman putih kosong hampir selalu berarti salah satu dari dua hal: JavaScript aplikasi crash sebelum sempat menggambar apa pun, atau JavaScript tidak pernah termuat sama sekali. Buka console browser (klik kanan → Inspect → Console) dan baca error merah pertama, lalu periksa tab Network untuk file yang gagal dimuat. Sebagian besar penyebabnya adalah environment variable yang hilang, base path yang salah, build yang belum selesai, atau crash di satu komponen.

Panduan ini membahas aplikasi single-page yang dibangun dengan React, Vue, atau framework serupa (termasuk aplikasi yang dibuat pembuat aplikasi AI), yaitu tempat halaman kosong paling sering terjadi.

Mengapa halamannya putih

Aplikasi single-page (SPA) modern mengirim ke browser sebuah file HTML yang hampir kosong, kira-kira seperti ini:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

JavaScript kemudian membangun seluruh halaman di dalam div kosong itu. Jika script gagal dimuat, atau melempar error sebelum merender, div tetap kosong dan kamu hanya melihat putih. Halamannya tidak “rusak” dengan cara yang terlihat; ia hanya tidak pernah tergambar.

Karena itu, perbaikannya selalu dimulai di developer tools, bukan di halaman itu sendiri.

Langkah 1: Baca console

Buka developer tools: klik kanan halaman dan pilih Inspect, atau tekan F12 (Cmd+Option+I di Mac). Buka tab Console dan muat ulang halaman.

Lihat error merah pertama; error berikutnya sering kali hanya efek samping. Isinya menunjuk ke penyebab:

Salin teks error lengkap, termasuk nama file dan nomor baris. Jika kamu memakai pembuat aplikasi AI, tempelkan langsung ke chat.

Langkah 2: Periksa apakah file berhasil dimuat

Buka tab Network, centang Disable cache, lalu muat ulang. Lihat request untuk file .js dan .css.

• Status 404 pada file JavaScript: halaman meminta file yang tidak ada di server.
• Status 200 tetapi tipenya text/html: server mengembalikan halaman (sering kali index.html itu sendiri, karena fallback SPA) alih-alih script. Penyebab dasarnya sama: file tidak berada di tempat yang diharapkan halaman.

Alasan yang umum:

Base path yang salah. Jika aplikasi disajikan dari sub-folder, seperti contoh.com/app/, tetapi dibangun untuk memuat file dari /assets/..., setiap request script akan meleset. Di Vite ini adalah opsi base di vite.config; di Create React App adalah field homepage; di Next.js adalah basePath. Nilainya harus cocok dengan tempat aplikasi benar-benar disajikan.

index.html yang sudah usang. Build tool memberi file nama dengan hash konten, seperti index-a1b2c3.js. Setelah deploy baru, file lama sudah hilang. Jika browser atau CDN masih menyimpan index.html lama di cache, ia meminta file lama dan tidak mendapat apa-apa. Hard refresh (Cmd+Shift+R atau Ctrl+Shift+R) memastikan hal ini. Solusi jangka panjangnya adalah menyajikan index.html dengan header cache yang pendek atau tanpa cache, sementara file ber-hash disimpan lama di cache.

Build belum selesai atau belum di-deploy. Jika build gagal, host mungkin menyajikan folder output yang lama atau kosong. Periksa log build untuk error.

Folder yang salah dipublikasikan. Host harus menyajikan output build (biasanya dist atau build), bukan folder sumber proyek. Menyajikan folder sumber memberimu index.html yang menunjuk ke /src/main.tsx, yang tidak bisa dijalankan browser.

Langkah 3: Periksa environment variable

Aplikasi front end sering membaca pengaturan seperti URL API atau kunci publik saat build. Jika sebuah variable hilang di build live, kode seperti createClient(undefined, undefined) langsung melempar error, dan halamannya menjadi putih.

Hal yang perlu diketahui:

• Di Vite, hanya variable dengan awalan VITE_ yang tersedia di kode browser, dibaca sebagai import.meta.env.VITE_NAME. Di Create React App awalannya REACT_APP_; di Next.js, NEXT_PUBLIC_.
• Nilai-nilai ini ditanam saat aplikasi dibangun. Menambahkan variable setelah build tidak berpengaruh sampai kamu membangun ulang dan men-deploy ulang.
• Pratinjau atau mesin lokal mungkin punya file .env yang tidak dimiliki build produksi. Atur variable yang sama di host.
• Apa pun dengan awalan ini berakhir di JavaScript publik. Hanya letakkan nilai publik di sana, jangan pernah kunci rahasia.

Tes cepat: cari undefined di dekat nama pengaturan dalam error console, atau tanyakan:

Halaman aplikasi yang dipublikasikan kosong. Daftarkan setiap environment variable yang dibaca frontend, periksa mana yang hilang atau kosong di build live, dan buat aplikasi menampilkan pesan error yang jelas alih-alih halaman kosong ketika ada yang hilang.

Langkah 4: Perbaiki crash

Jika console menampilkan error JavaScript biasa, kode crash saat rendering. Penyebab umum di aplikasi yang dibangun AI:

• Data belum dimuat. Sebuah komponen membaca user.name sebelum user tiba. Solusinya adalah loading state, atau optional chaining (user?.name).
• Data kosong. Akun baru tidak punya record, dan kode mengasumsikan daftar memiliki setidaknya satu item.
• Bentuk data tidak sesuai. API mengembalikan objek error alih-alih daftar yang diharapkan kode.
• Import yang hilang setelah sebuah file diubah namanya atau dipindahkan.
• Menggunakan API khusus browser saat server-side rendering, seperti window atau localStorage di komponen server Next.js.

Berikan AI error lengkapnya, halamannya, dan akun mana yang sedang kamu pakai saat itu:

Halaman Dashboard kosong untuk pengguna baru. Console: TypeError: Cannot read properties of undefined (reading 'map') di ProjectList.tsx:18. Berfungsi untuk akun saya, yang punya proyek. Perbaiki agar akun kosong menampilkan "Belum ada proyek", dan periksa akun baru di pratinjau.

Langkah 5: Tambahkan error boundary

Di React, satu komponen yang crash bisa melepas seluruh aplikasi, itulah sebabnya bug kecil bisa menghasilkan halaman yang benar-benar kosong. Error boundary adalah komponen yang menangkap error rendering di bawahnya dan menampilkan fallback sebagai gantinya.

Tambahkan error boundary di sekitar route utama yang menampilkan "Terjadi kesalahan" dengan tombol Muat ulang, dan mencatat error ke console. Biarkan header dan navigasi di luar boundary agar tetap tampil.

Ini tidak memperbaiki bug-nya, tetapi pengunjung melihat pesan alih-alih layar kosong, dan kamu melihat di mana kerusakannya terjadi.

Langkah 6: Tidak ada error, tetap kosong

Jika console bersih dan script termuat:

• Periksa tab Elements. Apakah ada konten di dalam <div id="root">? Jika ya, berarti sudah dirender tetapi tidak terlihat: teks putih di atas putih, opacity: 0, display: none, atau elemen layar penuh yang menutupinya.
• Periksa router. Jika tidak ada route yang cocok dengan URL saat ini dan tidak ada route “tidak ditemukan”, beberapa router tidak merender apa pun. Tambahkan route catch-all yang menampilkan halaman 404.
• Periksa titik mount. Kode harus di-mount ke elemen yang ada. Jika index.html memiliki id="app" tetapi kode mencari root, tidak ada yang muncul (dan React biasanya mencatat error).
• Periksa ekstensi browser. Coba jendela privat. Ad blocker kadang memblokir script dengan nama seperti analytics atau ads.

Kosong hanya setelah me-refresh halaman?

Jika halaman utama berfungsi tetapi me-refresh /dashboard menampilkan halaman kosong atau 404, server tidak tahu untuk mengirim index.html pada route aplikasi. Itu masalah fallback routing, yang dibahas di cara memperbaiki error 404 setelah deploy.

Kesalahan umum

• Membaca error terakhir alih-alih yang pertama. Baris merah pertama biasanya penyebabnya.
• Mengatur environment variable tanpa membangun ulang. Variable frontend ditetapkan saat build.
• Hanya menguji dengan akun sendiri. Crash pada akun kosong adalah salah satu penyebab halaman kosong yang paling umum.
• Mengira deploy sudah berhasil. Periksa log build sebelum men-debug kode.
• Menyalahkan cache browser untuk segalanya. Hard refresh menyingkirkannya dalam hitungan detik; jika halaman masih kosong, penyebabnya ada di tempat lain.

Halaman kosong di Mythex

Jika Pratinjau kosong, pertama periksa apakah aplikasi berjalan (buka Code → terminal), lalu minta Mythex menjalankan server yang benar, klik Refresh di toolbar pratinjau, atau gunakan /fix. Untuk URL yang sudah dipublikasikan tetapi kosong, dokumentasi menyarankan untuk menunggu sebentar dan melakukan hard refresh, memastikan env var dan database sudah diatur sebelum publikasi, serta memeriksa kuota hosting kamu. Ingat bahwa aplikasi yang dipublikasikan adalah snapshot: setelah memperbaiki sesuatu, publikasikan lagi. Jika sebuah perubahan yang menyebabkannya, Kembalikan ke titik ini pada balasan terakhir yang berfungsi akan mengembalikan proyek ke keadaan sebelumnya. Lihat Pemecahan masalah dan Pemecahan masalah publikasi di dokumentasi, serta panduan umum kami tentang men-debug aplikasi buatan AI.

Checklist halaman kosong

• Membaca error merah pertama di Console
• Memeriksa tab Network untuk file .js/.css yang 404 atau mengembalikan HTML
• Base path cocok dengan tempat aplikasi disajikan
• Build selesai, dan folder output build adalah yang dipublikasikan
• Semua environment variable frontend diatur pada build live, lalu dibangun ulang
• Crash diperbaiki, termasuk untuk akun kosong dan baru
• Error boundary terpasang agar crash di masa depan menampilkan pesan
• Route catch-all untuk URL yang tidak dikenal
• Diuji setelah hard refresh dan di jendela privat

Pertanyaan