Cara Deploy React ke Netlify

Deploy React ke Netlify itu cepat — lima menit kalau lancar. Tapi hampir semua orang menemui masalah yang sama sehari kemudian: halaman 404 saat di-refresh. Kebanyakan tutorial tidak menyinggung itu sama sekali, jadi panduan ini memasukkannya sebagai langkah wajib, bukan catatan tambahan.

Langkahnya sedikit berbeda antara project Vite dan Create React App. Keduanya dibahas.

Yang perlu disiapkan

• Node.js 20 atau lebih baru — cek dengan node -v.
• Akun Netlify, paket gratis cukup.
• Project React yang jalan dengan npm run dev atau npm start.
• Repositori Git di GitHub, GitLab, atau Bitbucket.

Langkah 1: Kenali dulu build tool-mu

Ini menentukan nama folder hasil build, dan salah di sini membuat deploy menghasilkan halaman kosong.

Kalau ragu, jalankan npm run build di lokal dan lihat folder mana yang muncul.

Langkah 2: Buat netlify.toml

Kamu bisa mengisi setelan build lewat dashboard, tapi menaruhnya di repositori lebih baik — konfigurasinya ikut ter-versi, dan berlaku sama untuk semua orang yang meng-clone repo.

Bikin netlify.toml di root project. Untuk Vite:

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Untuk Create React App, sama persis kecuali satu baris:

  publish = "build"

Blok [[redirects]] di bawah itu yang mencegah masalah 404 — penjelasannya di langkah berikutnya.

Langkah 3: Kenapa blok redirect itu wajib

Tanpa aturan itu, kamu akan menemui gejala ini: navigasi antar halaman lancar, tapi begitu di-refresh di /tentang muncul 404. Dan yang lebih menyakitkan — kalau ada orang membuka tautan langsung ke halaman dalam, mereka juga kena 404.

Sebabnya sederhana. React Router bekerja di sisi browser. Saat kamu refresh, browser meminta /tentang ke server, dan server mencari berkas bernama tentang yang memang tidak pernah ada — yang ada cuma index.html.

Aturan tadi menyuruh Netlify mengembalikan index.html untuk semua rute, dengan status 200. Aplikasimu termuat, lalu routernya membaca URL dan menampilkan halaman yang benar.

Kalau kamu lebih suka berkas terpisah, buat public/_redirects (tanpa ekstensi) berisi satu baris:

/*    /index.html   200

Berkas itu harus ada di folder yang ikut tersalin ke hasil build — public/ untuk Vite maupun CRA.

Langkah 4: Hubungkan repositori

1. Push project-mu ke GitHub, GitLab, atau Bitbucket.
2. Di dashboard Netlify, klik Add new site lalu Import an existing project.
3. Pilih penyedia Git dan repositorimu.
4. Netlify membaca netlify.toml dan mengisi setelannya sendiri. Biarkan apa adanya.
5. Klik Deploy site.

Satu-dua menit kemudian situsmu live di alamat acak seperti gleeful-marzipan-8c3f21.netlify.app. Ganti namanya lewat Site configuration lalu Change site name.

Sejak sekarang, setiap push ke branch utama otomatis jadi deploy baru.

Langkah 5: Environment variable

Berkas .env.local tidak ikut ter-commit, jadi nilainya harus didaftarkan ulang di Site configuration lalu Environment variables.

Yang paling sering bikin bingung: prefiks. Variabel hanya sampai ke kode browser kalau namanya diawali prefiks yang benar, dan prefiksnya berbeda antara Vite dan CRA.

Satu hal lagi: variabel dibaca saat build. Menambahkan variabel baru tidak berpengaruh sampai kamu men-deploy ulang. Pakai tombol Trigger deploy lalu Clear cache and deploy site.

Langkah 6: Deploy preview

Fitur ini aktif otomatis dan sering kali paling berguna dari semuanya.

Setiap kali kamu membuka pull request, Netlify mem-build cabang itu dan memberinya URL sendiri. Kamu bisa membuka perubahan itu di browser sungguhan — di ponsel juga — sebelum di-merge. Untuk tim, ini yang membuat review jadi mungkin tanpa siapa pun harus menjalankan project di laptopnya.

URL-nya muncul otomatis sebagai komentar di pull request kalau integrasi GitHub-nya aktif.

Langkah 7: Pasang domain sendiri

Buka Domain management lalu Add a domain. Cara paling mudah adalah memindahkan nameserver ke Netlify DNS, karena domain root ditangani otomatis. Sertifikat SSL diterbitkan otomatis setelah DNS terverifikasi.

Langkah DNS lengkapnya ada di panduan custom domain dan SSL.

Masalah yang sering muncul

Halaman putih setelah deploy

Buka DevTools lalu Console. Kalau penuh 404 untuk berkas .js dan .css, berarti publish salah folder — dist untuk Vite, build untuk CRA.

404 saat refresh

Aturan redirect belum ada, atau berkas _redirects tidak ikut ke hasil build. Cek di dashboard bagian Deploys, buka deploy terakhir, dan lihat apakah Netlify mendeteksi aturan redirectmu.

Build gagal padahal jalan di lokal

Penyebab nomor satu: kapitalisasi nama berkas. macOS dan Windows tidak membedakan Header.jsx dan header.jsx, server build Linux membedakannya. Periksa semua import-mu.

Penyebab nomor dua di CRA: peringatan diperlakukan sebagai error. Kalau log-mu berhenti di Treating warnings as errors because process.env.CI = true, perbaiki peringatannya, atau — kalau memang mendesak — set CI = "false" di [build.environment].

Environment variable undefined

Tiga hal yang perlu dicek berurutan: prefiksnya benar, nilainya sudah didaftarkan di dashboard, dan situsnya sudah di-deploy ulang setelah variabel ditambahkan.

Gambar di folder public tidak muncul

Untuk Vite, path absolut seperti /logo.png bekerja selama situsmu di root domain. Cara yang lebih tahan banting adalah mengimpornya:

import logo from './assets/logo.png';

<img src={logo} alt="Logo" />

Dengan cara ini Vite ikut mengurus hashing nama berkasnya, jadi cache tidak pernah basi.

Batas paket gratis Netlify

Untuk aplikasi React ukuran biasa, yang paling mungkin kamu sentuh adalah menit build — apalagi kalau kamu sering push dan tiap build makan dua sampai tiga menit.

Ringkasan

Mau membandingkan dengan platform lain dulu? Lihat Vercel vs Netlify. Untuk gambaran menyeluruh soal deploy, mulai dari panduan lengkap deploy website. Kalau deploy-mu gagal, cek 15 error deploy paling umum.