Mengatasi Compile Stuck Next.js 16 di Turbopack Server
Iwan Efendi3 min
Cara saya men-debug dan memperbaiki dev server Next.js 16 Turbopack yang terus crash di 'Compiling /[locale]' setelah migrasi ke Tailwind CSS v4.
Read in EnglishEN
Setelah berhasil migrasi SnipGeek dari Tailwind CSS v3.4.1 ke v4 dan Next.js 15 ke 16, saya menabrak tembok yang sangat membuat frustrasi: dev server terus mati secara diam-diam di
Setiap kali saya menjalankan
Tidak ada error kompilasi. Tidak ada log yang membantu. Prosesnya langsung hilang begitu saja.
Sebelum menemukan akar masalahnya, saya melewati beberapa percobaan gagal yang layak didokumentasikan.
Kadang memang digunakan, kadang tidak. Mematikan proses yang tersisa dan restart tidak membantu. Server akan mulai, lalu crash lagi saat kompilasi.
Terobosan datang ketika saya mengambil pendekatan yang lebih sistematis:
Setelah ketiga perbaikan diterapkan, server berhasil mengompilasi:
Kompilasi memakan waktu 7.8 detik—itulah mengapa terlihat seperti stuck. Sebenarnya sedang bekerja, tetapi kehabisan memori sebelum selesai.
Untuk memahami lebih lanjut tentang cara membaca log error compiler dan debugging otomatis, kamu bisa merujuk ke panduan Cara Memperbaiki Log Build Gagal pada AI dengan Cepat. Sementara itu, jika masalah kompilasimu selesai namun performa memuat halaman web tersendat, baca Cara Optimasi Scroll Next.js dan Pemuatan Gambar.
Saya memperbarui script
Tiga faktor bergabung menciptakan crash yang diam-diam:
T: Apa saja tanda-tanda atau signature error saat server mengalami crash OOM di Turbopack?
J: Tanda utamanya adalah server mati tanpa menampilkan error log sama sekali (exit code
○ Compiling /[locale] ... dengan exit code 1. Tidak ada pesan error. Tidak ada stack trace. Hanya... mati.
Catatan ini mendokumentasikan perjalanan debugging lengkap—setiap langkah yang salah dan solusi akhirnya—agar kamu tidak perlu membuang waktu berjam-jam untuk masalah yang sama.
Gejalanya
npm run dev, server Turbopack akan mulai dengan baik:
▲ Next.js 16.1.6 (Turbopack)
- Local: http://localhost:9003
✓ Starting...
✓ Ready in 1552ms
○ Compiling /[locale] ...
# ← proses mati di sini, exit code 1Langkah yang Salah
Percobaan 1: Restart Server
Langkah pertama yang paling jelas. Kill prosesnya, restart. Hasil yang sama setiap kali—stuck di titik yang sama.Percobaan 2: Cek Konflik Port
Saya curiga port9003 sudah digunakan:
netstat -ano | findstr :9003Percobaan 3: Revert Git Commit
Saya bahkan melakukan rollback ke commit lama (c640944 — backup sebelum migrasi) untuk menyingkirkan kemungkinan perubahan kode. Kode Tailwind v3 yang lama punya masalahnya sendiri dengan dependensi yang lebih baru, jadi ini bukan jalan yang tepat.
Jangan Panik Revert
Melakukan rollback beberapa commit tanpa memahami akar masalahnya bisa menciptakan lebih banyak masalah. Selalu diagnosis dulu sebelum revert.
Menemukan Akar Masalah
1
Hapus cache Cache Turbopack yang usang dari proses migrasi bisa menyebabkan kompilasi gagal.
.next sepenuhnya.Remove-Item -Recurse -Force .next2
Tingkatkan alokasi memori Node.js.Route
/[locale] di SnipGeek sangat berat—mengimpor Firebase, Radix UI, Framer Motion, Recharts, dan banyak dependensi lainnya. Ukuran heap default Node.js (~1.7 GB) tidak cukup untuk Turbopack mengompilasi semuanya.$env:NODE_OPTIONS="--max-old-space-size=4096"
npx next dev --turbopack -p 90033
Perbaiki nama export proxy.Next.js 16 mengganti nama
middleware menjadi proxy. File sudah di-rename ke src/proxy.ts, tetapi fungsi yang di-export masih bernama middleware:// ❌ Sebelum (crash diam-diam)
export function middleware(request: NextRequest) { ... }
// ✅ Sesudah
export function proxy(request: NextRequest) { ... }✓ Ready in 2.3s
○ Compiling /[locale] ...
GET / 200 in 9.2s (compile: 7.8s, proxy.ts: 82ms, render: 1249ms)Perbaikan Permanen
dev di package.json agar selalu mengalokasikan memori yang cukup:
{
"scripts": {
"dev": "cross-env NODE_OPTIONS=--max-old-space-size=4096 next dev --turbopack -p 9003"
}
}Mengapa Ini Terjadi
| Faktor | Detail |
|---|---|
| Turbopack + route besar | Layout /[locale] mengimpor 15+ paket berat (Firebase, Radix UI, Framer Motion, dll.) |
| Batas memori default | Node.js default ~1.7 GB heap, tidak cukup untuk bundling semua dependensi |
| OOM diam-diam | Turbopack tidak menampilkan error kehabisan memori secara jelas—proses langsung keluar dengan kode 1 |
Diagnostik Cepat
Jika dev server Next.js 16 kamu mati diam-diam saat kompilasi, hal pertama yang harus dicoba adalah menaikkan memori:
NODE_OPTIONS=--max-old-space-size=4096. Ini saja sudah menyelesaikan banyak crash kompilasi Turbopack.Poin Penting
- Exit code 1 diam-diam saat kompilasi Turbopack sering kali masalah OOM. Selalu cek alokasi memori terlebih dahulu.
- Hapus cache
.nextsetelah migrasi besar. Cache usang bisa menyebabkan kegagalan kompilasi yang tidak terduga. - Next.js 16 membutuhkan export
proxy, bukanmiddleware. Pesan errornya jelas, tapi bisa tenggelam jika masalah lain membuat server crash duluan. - Jangan panik revert. Diagnosis secara sistematis sebelum rollback commit.
FAQ
1 atau 137 pada Linux/macOS) sesaat setelah mencetak pesan ○ Compiling /[locale] .... Hal ini dikarenakan OS langsung menghentikan paksa runtime Node.js sebelum sempat menulis file log pengecualian ke layar terminal.
T: Apakah sebaiknya saya menggunakan Turbopack atau Webpack untuk pengembangan lokal?
J: Sangat disarankan untuk menggunakan Turbopack karena kecepatan rendering HMR (Hot Module Replacement) dan startup berkali-kali lipat lebih cepat. Namun, karena Turbopack dibuat dengan bahasa Rust dan melakukan kompilasi native yang intensif, ia memakan memori lebih besar saat memetakan dependency graph yang rumit. Menambahkan 4096 pada parameter NODE_OPTIONS dapat mencegah masalah crash tersebut.
T: Bagaimana cara menghapus cache Next.js lokal secara bersih saat terjadi loop kompilasi?
J: Kamu harus menghapus folder .next yang terletak pada root direktori proyekmu. Di terminal Linux atau macOS, jalankan rm -rf .next. Untuk pengguna Windows PowerShell, gunakan Remove-Item -Recurse -Force .next. Ini akan memaksa compiler menyusun ulang dependency graph dari awal.
T: Apa perbedaan antara middleware.ts dan proxy.ts pada Next.js 16?
J: Next.js 16 membawa perombakan skema routing middleware. Penanganan interceptor HTTP yang sebelumnya ditaruh di root sebagai middleware.ts kini didefinisikan dalam modul proxy untuk menangani redirect secara native, yang mengharuskan ekspor bernama proxy bukan lagi default export middleware.
Referensi
- Panduan Penanganan Kegagalan Kompilasi Next.js — Referensi resmi Next.js mengenai penanganan error kompilasi dan konfigurasi alokasi memori.
- Dokumentasi Resmi Turbopack — Penjelasan detail arsitektur Turbopack, strategi caching, dan integrasi Next.js.
- Opsi Baris Perintah Node.js — Panduan resmi penggunaan parameter
max-old-space-sizeuntuk optimasi memori. - Panduan Migrasi Tailwind CSS v4 — Langkah-langkah detail mengenai pembaruan struktur CSS dan integrasinya pada Next.js v16.
Topics
Topik dalam catatan
Jelajahi pembahasan serupa lewat topik-topik terkait berikut.
Bagikan artikel ini
Diskusi
Menyiapkan area komentar...