Di macOS, pertama-tama identifikasi apakah npm melaporkan konflik penggabungan (merge conflict) Git, ketidakcocokan antara package.json dan package-lock.json, atau kesalahan resolusi peer dependency. Periksa berkas proyek, status Git, dan versi npm di Terminal sebelum mengubah apa pun. Jika hanya lockfile yang perlu diselaraskan, opsi --package-lock-only milik npm dapat memperbaruinya tanpa menginstal ulang paket ke dalam node_modules.

Mulai di folder proyek dan pertahankan status saat ini

Buka Terminal, berpindahlah ke direktori proyek, dan pastikan Anda berada di direktori utama (root) proyek yang dituju. Di Finder, Anda dapat menemukan folder tersebut, lalu gunakan perintah cd di Terminal; jika jalur (path) mengandung spasi, beri tanda kutip pada jalur tersebut, misalnya cd "$HOME/Projects/My App". Jalankan:

pwd
git status --short
node --version
npm --version

git status --short menunjukkan apakah salah satu manifes memiliki perubahan yang belum di-commit. Jika ada perubahan yang perlu Anda simpan, simpan atau commit perubahan tersebut sebelum melanjutkan; jangan menimpa berkas saat Anda masih mempertimbangkan perubahan dependensi mana yang sesuai. Catat versi Node.js dan npm agar Anda dapat membandingkannya dengan penyiapan yang terdokumentasi pada proyek atau konfigurasi continuous integration. Format lockfile npm telah berubah di berbagai versi utama npm, sehingga perbedaan format dapat menjelaskan perubahan tak terduga tanpa membuktikan bahwa dependensi itu sendiri rusak. Dokumentasi package-lock npm

Tentukan jenis konflik yang Anda alami

Jika package-lock.json berisi penanda Git seperti <<<<<<<, =======, atau >>>>>>>, ini adalah konflik penggabungan (merge conflict) pada kontrol sumber (source control). Periksa seluruh bagian yang terpengaruh dan bandingkan perubahan dari kedua cabang. Selesaikan deklarasi dependensi di package.json terlebih dahulu: panduan konflik lockfile versi terdahulu dari npm secara eksplisit menyatakan untuk menyelesaikan konflik manifes secara manual sebelum membuat ulang lockfile. Jangan langsung mempertahankan satu sisi lockfile hanya karena kebiasaan; setiap cabang mungkin telah menambahkan atau mengubah dependensi. Panduan konflik package-lock npm

Jika tidak ada penanda Git, bandingkan nama dependensi dan rentang versinya di package.json dengan yang ada di lockfile. package.json menentukan rentang yang dapat diterima, sedangkan lockfile mencatat struktur pohon dependensi yang telah diselesaikan. Dokumentasi npm saat ini menyebutkan bahwa npm install biasa akan menggunakan versi yang terkunci jika versi tersebut memenuhi rentang pada manifes, dan akan memperbarui lockfile jika tidak memenuhi. Cara npm install menggunakan lockfile

Jika perintah gagal dengan pesan peer dependency, fokuslah pada paket-paket yang disebutkan dalam kesalahan tersebut beserta persyaratan peer-nya. Hal ini bisa jadi merupakan ketidakcocokan yang valid antara rentang paket yang dideklarasikan, bukan instalasi yang rusak. Jangan gunakan --force atau --legacy-peer-deps sebagai jalan pintas diagnosis: mengubah perilaku resolusi dependensi dapat menghasilkan pohon dependensi yang berbeda dari penyiapan yang diinginkan oleh proyek.

Periksa perubahan sebelum meminta npm untuk menyelaraskan

Tinjau riwayat proyek dan perbedaan (diff) saat ini:

git diff -- package.json package-lock.json
git log -5 --oneline -- package.json package-lock.json

Cari commit atau cabang yang mengubah deklarasi dependensi, versi lockfile, atau konfigurasi npm. Periksa juga apakah proyek memiliki berkas .npmrc; dokumentasi npm mencatat bahwa opsi pembentuk pohon seperti legacy-peer-deps atau install-links dapat memengaruhi apakah lockfile dan instalasi bersih (clean install) di kemudian hari akan cocok. Gunakan pengaturan khusus proyek yang sama dengan yang sudah diterapkan oleh repositori, alih-alih menambahkan flag baru secara acak. Dokumentasi npm ci

Nilai lockfileVersion membantu mengidentifikasi format berkas, tetapi hindari memperlakukannya sebagai diagnosis tunggal. npm mendokumentasikan format versi 1, 2, dan 3 serta mencatat bahwa versi npm yang lebih baru dapat memperbarui lockfile yang lebih lama. Versi yang berubah mungkin mencerminkan perilaku kompatibilitas npm; periksa diff dependensi yang sebenarnya sebelum menyetujui penulisan ulang dalam skala besar. Format lockfile dan berkas versi lama

Selaraskan lockfile tanpa menginstal ulang dependensi

Setelah menyelesaikan semua penanda konflik dan memastikan package.json sudah benar, minta npm untuk memperbarui lockfile saja:

npm install --package-lock-only

Dokumentasi npm menyatakan opsi ini memperbarui package-lock.json tanpa memeriksa node_modules atau mengunduh dependensi. Ini adalah langkah penyelarasan yang terfokus; opsi ini tidak menjamin bahwa susunan dependensi yang dihasilkan sesuai dengan yang Anda inginkan, jadi periksalah diff setelahnya. Opsi npm install

git diff --check
git diff -- package.json package-lock.json
git status --short

git diff --check membantu menemukan kesalahan spasi/whitespace, sedangkan diff itu sendiri menunjukkan apa saja yang diubah oleh npm. Pastikan manifes tidak memuat perubahan yang tidak disengaja, periksa perubahan versi yang tak terduga atau penulisan ulang lockfile yang luas, dan verifikasi bahwa penanda konflik sudah hilang. Jika perubahan yang diajukan tidak masuk akal, pulihkan berkas dari status yang Anda simpan atau dari kontrol sumber dan periksa kembali penyebabnya, alih-alih menghapus node_modules atau membuat ulang semuanya.

Ketahui kapan instalasi bersih (clean install) tepat dilakukan

Gunakan npm ci hanya setelah manifes dan lockfile telah diselaraskan secara sengaja dan Anda ingin mereproduksi struktur pohon dependensi yang terkunci. Perintah ini memerlukan lockfile, akan gagal alih-alih memperbarui ketidakcocokan, dan menghapus direktori node_modules yang ada sebelum menginstal. Hal tersebut membuatnya berguna untuk mengonfirmasi status yang telah terselesaikan, tetapi ini bukanlah perintah pemeriksaan yang aman tanpa efek samping. Perilaku npm ci

Jika npm install --package-lock-only tidak dapat menyelesaikan konflik, catat pesan kesalahan persisnya, tinjau rentang paket yang disebutkan dan pengaturan npm proyek, lalu bandingkan dengan cabang atau lingkungan CI yang menghasilkan lockfile tersebut. Pertanyaan yang menentukan adalah deklarasi dependensi mana yang harus dipertahankan oleh proyek; pembersihan instalasi tidak dapat menjawab hal itu untuk Anda. Setelah keputusan tersebut tercermin di package.json, buat ulang hanya lockfile-nya, periksa perubahan yang diajukan, dan barulah tentukan apakah instalasi bersih diperlukan.

Sumber