next dev --inspect: Debugging Next.js 16

Sejak Next.js 16.1, next dev --inspect mengaktifkan Node.js debugger langsung tanpa perlu NODE_OPTIONS=--inspect. Bedanya: --inspect bawaan next dev hanya melekat ke proses yang benar-benar menjalankan kode aplikasi, sementara cara lama lewat NODE_OPTIONS melekat ke semua proses yang dijalankan Next.js sehingga breakpoint sering kena proses yang salah.

Ringkasan cepat:

1. next dev --inspect dirilis di Next.js 16.1 (18 Desember 2025) sebagai pengganti NODE_OPTIONS=--inspect yang lebih rawan salah target proses.
2. Perbedaan utama: debugger kini hanya melekat ke proses yang menjalankan kode aplikasi, bukan ke seluruh proses internal Next.js.
3. Dipakai bersama chrome://inspect (Chrome) atau about:debugging (Firefox) untuk debugging server-side dengan breakpoint asli, bukan cuma console.log.
4. --inspect=0.0.0.0 dibutuhkan untuk remote debugging dari luar localhost, misalnya saat aplikasi berjalan di container Docker.
5. Untuk kebutuhan --inspect-brk/--inspect-wait (menahan eksekusi sejak awal), tetap wajib pakai NODE_OPTIONS, flag --inspect bawaan belum mencakup varian ini.

Apa Itu next dev --inspect di Next.js 16?#

next dev --inspect adalah flag yang mengaktifkan Node.js debugger saat menjalankan server development Next.js. Sebelum Next.js 16.1, cara satu-satunya mengaktifkan debugger adalah menjalankan NODE_OPTIONS=--inspect next dev, yang punya masalah nyata: inspector melekat ke semua proses yang dijalankan Next.js, bukan hanya proses yang menjalankan kode milik developer.

Menurut catatan rilis resmi Next.js 16.1, perubahan ini masuk kategori "easier debugging":

You can now enable the Node.js debugger by passing --inspect to next dev. Previously this required passing NODE_OPTIONS=--inspect and would attach the inspector to all processes spawned by Next.js instead of only to the process running your code.

(Next.js 16.1 announcement, nextjs.org/blog/next-16-1)

Dampak praktisnya: breakpoint yang dipasang di kode Server Component, Route Handler, atau Server Action lebih konsisten berhenti di tempat yang benar, tanpa perlu menebak-nebak proses mana yang sedang aktif di chrome://inspect.

Kapan Masih Perlu NODE_OPTIONS#

Flag --inspect bawaan next dev belum menggantikan semua kasus pemakaian Node.js inspector. Dokumentasi resmi panduan debugging Next.js menyebut, untuk memakai --inspect-brk (menahan eksekusi di baris pertama sampai debugger terhubung) atau --inspect-wait, caranya tetap lewat NODE_OPTIONS, misalnya NODE_OPTIONS=--inspect-brk next dev.

Bagaimana Cara Memakai next dev --inspect?#

Langkah dasarnya cukup menambah flag --inspect ke perintah dev yang sudah ada, disesuaikan dengan package manager yang dipakai:

npm run dev -- --inspect
# atau
pnpm dev --inspect
yarn dev --inspect

Setelah server berjalan, terminal akan menampilkan baris mirip ini:

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/learn/getting-started/debugging
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Untuk debugging lewat Chrome DevTools: buka tab baru ke chrome://inspect, cari aplikasi di bagian Remote Target, lalu klik inspect untuk membuka jendela DevTools terpisah dan masuk ke tab Sources untuk memasang breakpoint. Firefox punya alur serupa lewat about:debugging.

Kalau aplikasi berjalan di dalam container (misalnya Docker, pola yang relevan buat deploy self-hosted di luar Vercel seperti dibahas di artikel Build Adapters API Next.js untuk Non-Vercel), gunakan --inspect=0.0.0.0 supaya port debugger bisa diakses dari luar localhost.

Bagi yang lebih nyaman debugging langsung dari editor, VS Code punya konfigurasi launch.json siap pakai yang menjalankan --inspect secara otomatis lewat tombol Debug: Start Debugging (F5), dijelaskan lengkap di dokumentasi resmi debugging Next.js.

Ringkasan: Debugger Kini Melekat ke Proses yang Tepat, Bukan ke Semua Proses Next.js#

• next dev --inspect (Next.js 16.1+) menggantikan NODE_OPTIONS=--inspect untuk kasus pemakaian umum, dengan keunggulan debugger hanya melekat ke proses yang menjalankan kode aplikasi.
• Dipakai bersama chrome://inspect atau about:debugging untuk breakpoint server-side yang akurat, tanpa salah target proses.
• NODE_OPTIONS tetap relevan untuk kasus lanjutan seperti --inspect-brk/--inspect-wait yang belum didukung langsung oleh flag --inspect bawaan.
• Fitur ini satu dari beberapa perbaikan developer experience di rilis minor Next.js 16.1-16.3, dibahas lebih lengkap di fitur baru Next.js 16.1, 16.2, 16.3.
• Butuh bantuan mengaudit atau menyiapkan workflow development Next.js yang lebih efisien? Lihat layanan web development yang ditawarkan.