Saat pertama kali deploy aplikasi Next.js, banyak developer mengalami masalah seperti:

• data tidak muncul

• API gagal di-fetch

• auth error padahal di local aman

Penyebabnya sering kali bukan bug di kode, tapi Environment Variable (ENV) yang salah konfigurasi.

Di artikel ini, kita bahas cara kerja ENV di Next.js secara praktis dan mudah dipahami.

Apa Itu Environment Variable?

Environment Variable adalah nilai konfigurasi yang:

• tidak ditulis langsung di kode

• bisa berbeda antara development dan production

• biasanya berisi URL, token, atau secret

Contoh:

API_URL=https://api.example.com

File ENV yang Dibaca Next.js

Next.js TIDAK membaca semua file .env secara sembarangan.

Urutan prioritasnya:

1. .env.local ✅

2. .env.development

3. .env.production

4. .env

📌 .env.example hanya template, tidak pernah dibaca.

Kenapa .env.local Direkomendasikan?

Karena:

• otomatis dibaca Next.js

• tidak ikut ke-commit (aman)

• bisa beda di tiap server

Contoh membuatnya:

cp .env.example .env.local

Perbedaan ENV Server & Client

Ini bagian paling sering bikin error.

❌ ENV tanpa NEXT_PUBLIC_

API_SECRET=xxxxx

❌ Tidak bisa dipakai di browser

✅ ENV dengan NEXT_PUBLIC_

NEXT_PUBLIC_SITE_URL=http://localhost:8080

✅ Bisa dipakai di client & browser

📌 Gunakan NEXT_PUBLIC_ HANYA untuk data yang aman dipublikasikan.

Contoh Kasus Nyata (Port Salah)

Misalnya aplikasi kamu jalan di port 8080, tapi kodenya:

baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000"

Jika BETTER_AUTH_URL tidak diset:
👉 request akan lari ke port 3000 (mati)
👉 hasilnya: Failed to fetch

Solusi:

BETTER_AUTH_URL=http://localhost:8080

Perlu Build Ulang atau Tidak?

✅ YA, kalau:

• ubah .env.local

• deploy production

• pakai pm2 start npm -- start

❌ Tidak perlu build ulang kalau:

• cuma ubah UI

• pakai npm run dev

Workflow ENV yang Benar (Production)

cp .env.example .env.local
nano .env.local
npm run build
pm2 restart next-portfolio

Kesalahan Umum

• ❌ mengandalkan .env.example

• ❌ lupa restart PM2

• ❌ pakai localhost:3000 di server

• ❌ lupa prefix NEXT_PUBLIC_

Penutup

Memahami ENV di Next.js akan menghemat:

• waktu debugging

• error aneh di production

• deploy gagal tanpa pesan jelas

Kalau deploy kamu sering bermasalah, cek ENV dulu sebelum cek kode.

Saat membangun aplikasi Next.js, menjalankannya di local dengan npm run dev memang mudah.
Tapi ketika masuk ke server / VPS, kita butuh cara yang stabil, aman, dan otomatis hidup kembali saat server restart.

Di artikel ini, aku akan membahas cara deploy Next.js di VPS menggunakan PM2, lengkap dari build hingga troubleshooting umum.

Kenapa Tidak npm run dev di Server?

Mode dev:

• ❌ Tidak untuk production

• ❌ Boros resource

• ❌ Mati saat terminal ditutup

Solusinya adalah production build + PM2.

Persiapan

Pastikan di VPS kamu sudah terinstall:

• Node.js v20+

• npm

• Project Next.js siap jalan

Cek versi Node:

node -v

1. Build Project Next.js

Sebelum dijalankan di production, WAJIB build dulu:

npm run build

Jika sukses, akan muncul:

Compiled successfully

2. Install PM2

PM2 adalah process manager untuk Node.js.

npm install -g pm2

Cek:

pm2 -v

3. Jalankan Next.js dengan PM2

Gunakan next start, bukan dev.

Contoh menjalankan di port 8080:

pm2 start npm --name "next-portfolio" -- start -- -H 0.0.0.0 -p 8080

Cek status:

pm2 list

4. Auto Start Saat Server Reboot

Agar aplikasi otomatis hidup kembali:

pm2 save
pm2 startup

Jalankan command yang muncul di terminal.

5. Konfigurasi Environment Variable

Next.js tidak membaca .env.example.
Gunakan .env.local.

cp .env.example .env.local

Contoh env penting:

NEXT_PUBLIC_SITE_URL=http://localhost:8080
BETTER_AUTH_URL=http://localhost:8080

⚠️ Setiap ubah ENV → build ulang wajib dilakukan.

6. Restart Setelah Update

npm run build
pm2 restart next-portfolio

Troubleshooting Umum

❌ Website Tidak Bisa Diakses

• Pastikan port terbuka (ufw allow 8080)

• Pastikan app listen ke 0.0.0.0

❌ Data Kosong / Failed to Fetch

• .env.local belum diisi

• ENV berubah tapi tidak build ulang

• URL API masih localhost:3000

❌ PM2 Online Tapi Web Mati

Cek log:

pm2 logs next-portfolio

Penutup

Dengan PM2, aplikasi Next.js jadi:

• ✅ Stabil

• ✅ Auto-restart

• ✅ Siap production

Kalau kamu serius deploy Next.js ke server, PM2 adalah pilihan wajib.

✨ Semoga bermanfaat dan selamat ngoding!