Site icon JocoDEV

Cara Mengatasi npm Not Recognized, npm Not Found, dan npm Run Dev Not Working

jeditor

Baru saja mengetik npm install atau npm run dev di terminal, tetapi yang muncul justru pesan npm is not recognized as an internal or external command di Windows, atau command not found di macOS dan Linux? Atau npm berhasil dijalankan, tetapi perintah npm run dev gagal dengan berbagai error aneh? Tenang, masalah ini sangat umum dan hampir selalu punya solusi yang sederhana.

Error npm not recognized dan npm not found pada dasarnya bermakna sama: sistem operasi tidak dapat menemukan program npm di PATH. Sementara npm run dev not working biasanya berkaitan dengan konfigurasi proyek, dependensi yang belum terpasang, atau versi Node.js yang tidak cocok. Artikel ini membahas penyebab dan langkah perbaikannya secara berurutan, mulai dari yang paling sering terjadi.

Mengapa Error npm Not Recognized Muncul

npm (Node Package Manager) adalah tool bawaan yang terpasang bersama Node.js. Ketika Anda mengetik npm di terminal, shell akan mencari program bernama npm di daftar direktori yang terdaftar pada variabel PATH. Jika npm tidak ditemukan di sana, munculah pesan error.

Ada tiga penyebab utama:

Sebelum melangkah jauh, pastikan dulu apakah Node.js benar-benar ada di sistem Anda.

Cek Instalasi Node.js dan npm

Jalankan perintah berikut di terminal atau Command Prompt:

node -v
npm -v

Cara Mengatasi npm Not Recognized di Windows

Solusi 1: Instal Ulang Node.js

Cara paling cepat dan paling aman adalah menginstal ulang Node.js dari situs resminya:

  1. Unduh installer LTS (Long Term Support) dari nodejs.org.
  2. Jalankan installer, centang opsi Add to PATH (biasanya sudah tercentang otomatis).
  3. Selesaikan instalasi, lalu tutup dan buka kembali Command Prompt atau PowerShell.
  4. Uji lagi dengan node -v dan npm -v.

Penting diingat: terminal yang sudah terbuka sebelum instalasi tidak akan membaca PATH baru. Selalu restart terminal setelah menginstal.

Solusi 2: Perbaiki PATH Secara Manual

Bila Node.js sudah terpasang tetapi tetap muncul npm is not recognized, kemungkinan PATH-nya hilang:

  1. Tekan Win + R, ketik sysdm.cpl, lalu masuk ke tab Advanced dan klik Environment Variables.
  2. Pada bagian System variables, pilih variabel Path dan klik Edit.
  3. Pastikan ada entri menuju folder instalasi Node.js, umumnya C:\Program Files\nodejs\.
  4. Jika tidak ada, tambahkan entri tersebut, klik OK, lalu restart terminal.

Setelah PATH benar, perintah npm akan langsung dikenali di terminal mana pun.

Cara Mengatasi npm Not Found di macOS dan Linux

Di macOS dan Linux, pesan yang muncul biasanya npm: command not found. Penyebab dan solusinya sedikit berbeda.

Instal Node.js Melalui nvm

Cara yang paling direkomendasikan adalah memakai nvm (Node Version Manager) karena memudahkan pengelolaan beberapa versi Node sekaligus:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc   # atau ~/.zshrc bila memakai zsh
nvm install --lts
node -v && npm -v

Periksa PATH di Shell

Bila Node.js sudah terpasang (misalnya lewat Homebrew atau installer resmi) tetapi npm tetap tidak ditemukan, cek isi PATH:

echo $PATH

Pastikan direktori seperti /usr/local/bin atau ~/.nvm/versions/node/<versi>/bin tercantum di sana. Jika tidak, tambahkan baris export PATH yang sesuai ke file ~/.bashrc atau ~/.zshrc, lalu jalankan source pada file tersebut.

Memahami cara kerja manajemen paket dan izin pengguna di Linux akan sangat membantu saat mengutak-atik PATH dan direktori binari seperti ini — konsepnya dibahas tuntas dalam artikel Manajemen Paket dan User Permission di Linux.

Mengatasi npm Run Dev Not Working

Kasus kedua berbeda: npm dikenali sistem, tetapi perintah npm run dev tetap gagal. Berikut penyebab yang paling sering ditemui.

1. Error Missing Script: dev

Pesan npm error Missing script: dev berarti tidak ada script bernama dev di file package.json. Buka file tersebut dan periksa bagian scripts:

"scripts": {
  "dev": "vite",
  "build": "vite build"
}

Nama script bisa berbeda antar proyek — ada yang memakai dev, start, serve, atau development. Jalankan npm run tanpa argumen untuk melihat daftar script yang tersedia, lalu gunakan nama yang benar.

2. Dependensi Belum Terpasang

Bila muncul error seperti Cannot find module, hampir pasti folder node_modules belum ada atau tidak lengkap. Jalankan:

npm install

Perintah ini mengunduh semua paket yang tercantum di package.json. Setelah selesai, coba lagi npm run dev.

3. node_modules Rusak atau Cache Bermasalah

Jika error berlanjut meski dependensi sudah terpasang, bersihkan instalasi:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Di Windows, hapus folder node_modules dan file package-lock.json secara manual lewat File Explorer bila perintah rm -rf tidak tersedia.

4. Versi Node.js Tidak Cocok

Beberapa framework modern (misalnya Vite versi terbaru) mensyaratkan Node.js minimal versi tertentu. Bila versi Node Anda terlalu lama, npm run dev bisa gagal dengan error sintaks atau modul yang tidak dikenal. Cek syarat versi di dokumentasi framework yang dipakai, lalu perbarui Node.js — di sinilah nvm sangat berguna karena Anda bisa berpindah versi dengan satu perintah.

5. Port Sudah Dipakai Proses Lain

Bila dev server gagal jalan dengan pesan port already in use, ada proses lain yang menduduki port yang sama (umumnya 3000 atau 5173). Matikan proses tersebut atau jalankan dev server di port lain sesuai opsi framework yang dipakai.

Mencegah Error npm di Kemudian Hari

Setelah masalah teratasi, ada beberapa kebiasaan yang menjaga proyek tetap sehat. Selalu commit file package.json dan package-lock.json ke repositori agar versi dependensi konsisten di semua mesin. Hindari memasang paket global sembarangan, dan baca changelog sebelum melakukan upgrade versi mayor.

Praktik pengelolaan dependensi yang rapi juga merupakan bagian dari disiplin rekayasa perangkat lunak yang lebih luas — tim engineering GitHub kerap membagikan pelajaran tentang praktik engineering dan rilis perangkat lunak yang relevan untuk menjaga rantai pasok paket tetap aman dan terkelola. Untuk memperdalam dasar bahasa yang menjadi fondasi npm itu sendiri, artikel Dasar-Dasar JavaScript Modern: Fitur ES6+ yang Wajib Dikuasai Developer bisa menjadi bacaan lanjutan yang tepat.

Kesimpulan

Error npm not recognized dan npm not found hampir selalu berarti Node.js belum terpasang atau lokasinya tidak terdaftar di PATH — solusinya adalah instal ulang Node.js, perbaiki PATH, atau gunakan nvm di macOS dan Linux. Sementara npm run dev not working umumnya disebabkan script yang salah nama, dependensi yang belum terpasang, node_modules yang rusak, versi Node.js yang terlalu lama, atau port yang bentrok. Dengan mengikuti langkah-langkah di atas secara berurutan — cek instalasi, perbaiki PATH, lalu bereskan konfigurasi proyek — sebagian besar masalah npm bisa diselesaikan dalam hitungan menit.

Foto sampul oleh Jake Walker di Unsplash.

Exit mobile version