Solusi Nginx 404 Not Found pada Single Page Application (SPA)

Error 404 Not Found pada Nginx saat mengakses Single Page Application (SPA) seperti React, Vue, atau Angular terjadi karena Nginx mencoba mencari file fisik sesuai path URL yang diakses (misalnya /dashboard), padahal seluruh aplikasi hanya dilayani oleh satu file utama yaitu index.html. Solusi paling tuntas untuk masalah ini adalah menambahkan direktif try_files $uri $uri/ /index.html; di dalam blok server konfigurasi Nginx Anda.

Ketika pengguna mengakses root domain, Nginx akan melayani index.html dengan benar. Namun, ketika pengguna melakukan penyegaran halaman (refresh) di URL rute dalam seperti https://example.com/settings, Nginx secara default mencari folder atau file bernama settings di direktori root server. Karena file tersebut tidak ada, Nginx mengembalikan respon HTTP 404. Dengan mengonfigurasi ulang blok location /, kita memaksa Nginx untuk mengembalikan index.html dan menyerahkan kendali routing sepenuhnya kepada router sisi klien (React Router, Vue Router, dll).

Konfigurasi Nginx untuk SPA

Berikut adalah blok konfigurasi Nginx yang wajib diterapkan pada file virtual host situs Anda (biasanya terletak di /etc/nginx/sites-available/default atau direktori domain spesifik).

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/my-spa/dist;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ /index.html;
    }

    error_page 404 /index.html;
}

Analisis Komponen Konfigurasi

Langkah Penerapan dan Pengujian

Ikuti prosedur teknis di bawah ini untuk menerapkan perubahan konfigurasi ke server produksi:

1. Buka terminal server dan edit file konfigurasi Nginx menggunakan teks editor seperti nano atau vim.
   sudo nano /etc/nginx/sites-available/default
2. Tambahkan atau perbarui blok location / dengan menyertakan baris try_files $uri $uri/ /index.html;.
3. Simpan file dan keluar dari editor (pada nano: tekan Ctrl+O, Enter, lalu Ctrl+X).
4. Uji integritas sintaks konfigurasi Nginx untuk menghindari kegagalan layanan.
   sudo nginx -t
5. Jika hasil pengujian mencetak pesan syntax is ok dan test is successful, muat ulang (reload) Nginx untuk menerapkan perubahan tanpa memutus koneksi aktif.
   sudo systemctl reload nginx

Troubleshooting Masalah Umum

Jika setelah konfigurasi ini halaman tetap menampilkan error 404 atau mengalami masalah lain, periksa beberapa titik berikut:

• Path Direktori Root Salah: Pastikan path pada direktori root benar-benar mengarah ke folder yang berisi file index.html hasil kompilasi (bundling), bukan folder repository mentah.
• Keluaran Routing Sisi Klien (Base URL): Jika SPA Anda di-deploy di sub-direktori (contoh: example.com/myapp/), Anda harus menyesuaikan blok location menjadi location /myapp/ { try_files $uri $uri/ /myapp/index.html; } dan mengatur base path pada bundler Anda (Vite/Webpack).
• Browser Caching: Terkadang browser menyimpan cache dari respon 404 sebelumnya. Lakukan hard refresh (Ctrl+F5 pada Windows atau Cmd+Shift+R pada Mac) atau buka situs dalam mode Incognito.