Selesaikan Install Gagal dengan Cara Mengatasi Npm Version Conflict

Cara mengatasi npm version conflict yang paling aman adalah menyelaraskan versi paket yang diminta di package.json, bukan memaksa install. Blok ERESOLVE biasanya muncul karena dua paket meminta major version berbeda dari dependency yang sama, atau karena package-lock.json tidak sinkron dengan package.json.

Penyebab Umum Npm Version Conflict

Pesan ERESOLVE unable to resolve dependency tree memberi tahu dependensi mana yang bertabrakan. Bedakan empat lapisnya: versi Node tidak cocok dengan engines, versi npm terlalu lama, versi package langsung bentrok, dan peer dependency yang rentangnya sempit.

Periksa engines, dependencies, devDependencies, dan package-lock.json sebelum menghapus apa pun. Banyak kasus selesai hanya dengan membaca rentang versi yang tertulis di sana.

  • package-lock.json dibuat dengan npm atau Node berbeda, lalu tidak diperbarui.
  • Peer dependency memakai rentang sempit, misalnya react@^17 diminta padahal proyek memakai react@18.
  • Dua package meminta major berbeda, contoh A butuh webpack@4 sedangkan B butuh webpack@5.
  • Update satu package tanpa update pasangannya yang saling terkait.
  • Menyalin package.json dari tutorial lama ke Node dan npm baru.

Diagnosis Cepat Sebelum Perbaiki

Jalankan tiga perintah ini untuk memetakan masalah. Catat versi Node, versi npm, dan paket mana yang ditandai sebagai invalid atau deduped.

npm --version
node -v
npm ls nama-paket-konflik

Baca blok ERESOLVE dari bawah ke atas. Fokus ke baris Found dan Could not resolve karena di sana tertulis paket mana meminta versi apa.

Masalah Penyebab Solusi awal
ERESOLVE peer dep Rentang peer sempit Update paket induk bersama
Lockfile bentrok Lock beda Node atau npm Regenerasi lock terkontrol
Dua major terpasang Transitive dep berbeda Selaraskan atau pakai overrides

Cara Memperbaiki Npm Version Conflict Langkah Demi Langkah

Gunakan urutan ini agar perbaikan rapi dan bisa dikembalikan lewat Git.

  1. Identifikasi paket konflik dari log ERESOLVE dan output npm ls.
  2. Cek versi tersedia dan dependensinya di registry.
  3. Update selektif paket yang bermasalah, lalu rapikan duplikasi.
  4. Pakai overrides hanya bila dua library memaksa major berbeda dan tidak bisa diupdate.
  5. Validasi dengan install bersih dan jalankan start atau test.
npm view nama-paket versions --json
npm update nama-paket
npm dedupe
npm install --package-lock-only
npm ci

Contoh overrides di package.json untuk npm versi 8.3 ke atas:

{
  "overrides": {
    "semver": "^7.5.4"
  }
}

Flag seperti --force dan --legacy-peer-deps melewati pemeriksaan peer dependency. Install bisa lanjut, tetapi aplikasi berisiko crash saat runtime karena API antar major tidak cocok. Hapus package-lock.json dan node_modules juga berisiko karena menaikkan banyak versi sekaligus dan menghilangkan acuan versi stabil.

  • Lakukan install bersih dengan npm ci setelah lock diperbaiki.
  • Jalankan npm start dan npm test untuk pastikan tidak ada modul rusak.
  • Kunci versi yang stabil lewat commit package.json dan package-lock.json.
  • Catat versi Node di engines agar tim memakai runtime sama.

FAQ

Apakah hapus package-lock.json aman untuk version conflict?

Tidak selalu aman karena npm akan menyelesaikan ulang semua versi dan dapat menimbulkan konflik baru.

Kapan boleh memakai –legacy-peer-deps?

Pakai sementara hanya untuk library lama yang belum mendukung peer dependency baru, lalu catat sebagai utang teknis.

Mengapa npm ls masih menampilkan versi ganda setelah fix?

Kondisi tersebut normal bila dua paket memang membutuhkan major berbeda dan npm menyimpan salinannya secara nested.