[NODE JS] package-lock.json Ne İşe Yarar?
Selam arkadaşlar. package-lock.json dosyası npm'in en yanlış anlaşılan dosyalarından biri. Çoğu kişi bu dosyayı gereksiz sanıyor, .gitignore'a ekliyor veya silip tekrar oluşturuyor. Ama bu dosya projenizin tutarlılığı için hayati öneme sahip. Ben bir keresinde bu dosyayı görmezden geldiğimiz bir projede production'da ciddi sorunlar yaşadık, anlatacağım.
package-lock.json Neden Gerekli?
package.json'da bağımlılıklar genellikle versiyon aralığı ile belirtilir. Mesela "express": "^4.18.0" ifadesi 4.18.0 ile 5.0.0 arasındaki herhangi bir versiyonu kabul eder. Bu esneklik iyi görünür ama sorun şu: siz bugün npm install yaptığınızda 4.18.2 yüklenir, arkadaşınız yarın yaptığında 4.18.3 yüklenebilir. Küçük fark gibi görünür ama bazen patch güncellemeler bile bug getirebiliyor.
package-lock.json tam olarak bu sorunu çözer. Her paketin tam versiyonunu, indirme URL'ini, integrity hash'ini ve alt bağımlılıklarını kaydeder. Bu dosya sayesinde herkes her zaman aynı paket versiyonlarını yükler. Deterministic installation denir buna.
Tecrübeme göre en yaygın sorun şu: geliştirici A'nın bilgisayarında çalışan kod, geliştirici B'de çalışmıyor. Neden? Farklı paket versiyonları. package-lock.json bu sorunu tamamen ortadan kaldırır, ama dosyanın git'e dahil edilmesi şart.
JavaScript:
// === PACKAGE-LOCK.JSON YAPISI ===
// package-lock.json dosyasının basitleştirilmiş yapısı
const lockDosyasi = {
"name": "proje-adi",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "proje-adi",
"version": "1.0.0",
"dependencies": {
"express": "^4.18.0"
}
},
"node_modules/express": {
"version": "4.18.2", // TAM versiyon
"resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
"integrity": "sha512-abc123...", // Bütünlük hash'i
"dependencies": {
"accepts": "~1.3.8",
"body-parser": "1.20.1",
"cookie": "0.5.0"
// ... diğer alt bağımlılıklar
},
"engines": {
"node": ">= 0.10.0"
}
},
"node_modules/accepts": {
"version": "1.3.8",
"resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz",
"integrity": "sha512-def456...",
"dependencies": {
"mime-types": "~2.1.34",
"negotiator": "0.6.3"
}
}
// ... yüzlerce alt bağımlılık
}
};
console.log('=== package-lock.json Yapısı (Basitleştirilmiş) ===');
console.log(JSON.stringify(lockDosyasi, null, 2));
// Integrity hash açıklaması
console.log('
=== Integrity Hash ===');
console.log('integrity alanı paketin bütünlüğünü doğrular.');
console.log('Paket indirildiğinde hash kontrol edilir.');
console.log('Eşleşmezse yükleme durdurulur (güvenlik!).');
// npm ci vs npm install davranış farkı
console.log('
=== npm ci vs npm install ===');
const davranislar = {
'npm install': [
'package.json'ı okur',
'Versiyon aralığına uyan EN SON versiyonu yükler',
'package-lock.json'ı GÜNCELLER',
'node_modules'ı korur, eksikleri ekler',
'Geliştirme sırasında kullanılır'
],
'npm ci': [
'package-lock.json'ı okur (package.json ile tutarlılık kontrol eder)',
'TAM olarak lock dosyasındaki versiyonları yükler',
'package-lock.json'ı DEĞİŞTİRMEZ',
'node_modules'ı SİLER ve sıfırdan oluşturur',
'CI/CD ve production'da kullanılır'
]
};
Object.entries(davranislar).forEach(([komut, adimlar]) => {
console.log(`
${komut}:`);
adimlar.forEach((adim, i) => console.log(` ${i + 1}. ${adim}`));
});En İyi Pratikler
Bu dosya ile ilgili en önemli kurallar: her zaman git'e dahil edin, elle düzenlemeyin, çakışmalarda npm install ile yeniden oluşturun. merge conflict yaşandığında package-lock.json'daki çakışmayı çözmenin en kolay yolu bir tarafı kabul edip npm install çalıştırmaktır.
Ben projelerimde şu kuralları uyguluyorum: development'ta npm install, CI/CD'de npm ci, güncelleme yapacaksam npm update sonra test çalıştırıp commit, ve her hafta npm audit ile güvenlik kontrolü.
JavaScript:
// === EN İYİ PRATİKLER ===
// 1. Git'e dahil etme kuralları
const gitKurallari = {
'package-lock.json': 'GIT'E EKLE - Her zaman commit'le',
'node_modules/': 'GIT'E EKLEME - .gitignore'da olmalı',
'package.json': 'GIT'E EKLE - Tabii ki',
'.npmrc': 'GIT'E EKLE - Proje ayarları için (secret içermeyen)'
};
console.log('=== Git Kuralları ===');
Object.entries(gitKurallari).forEach(([dosya, kural]) => {
console.log(` ${dosya}: ${kural}`);
});
// 2. Merge conflict çözümü
console.log('
=== Merge Conflict Çözümü ===');
const conflictAdimlari = [
'Çakışma oluştuğunda package-lock.json'da karmaşık diff görürsünüz',
'Panik yapmayın! Çözüm basit:',
'',
' git checkout --theirs package-lock.json (veya --ours)',
' npm install',
' git add package-lock.json',
' git commit',
'',
'npm install komutu package.json'a bakarak lock dosyasını yeniden oluşturur',
'Bu sayede tutarlı bir lock dosyanız olur'
];
conflictAdimlari.forEach(adim => console.log(` ${adim}`));
// 3. Lockfile versiyonları
const lockVersionlari = [
{ versiyon: 'v1', npm: 'npm 5-6', aciklama: 'Eski format, dependencies alanı' },
{ versiyon: 'v2', npm: 'npm 7', aciklama: 'Geriye uyumlu, packages + dependencies' },
{ versiyon: 'v3', npm: 'npm 9+', aciklama: 'Modern format, sadece packages alanı' }
];
console.log('
=== Lockfile Versiyonları ===');
console.table(lockVersionlari);
// 4. Yaygın hatalar ve çözümleri
const hatalar = [
{
hata: 'package-lock.json silmek',
sonuc: 'Her yüklemede farklı versiyonlar',
cozum: 'Asla silmeyin, git'e dahil edin'
},
{
hata: '.gitignore'a eklemek',
sonuc: 'Ekip üyeleri farklı versiyonlar kullanır',
cozum: '.gitignore'dan çıkarın'
},
{
hata: 'Elle düzenlemek',
sonuc: 'Bozuk bağımlılık ağacı',
cozum: 'npm install ile otomatik güncelletin'
},
{
hata: 'CI/CD'de npm install kullanmak',
sonuc: 'Beklenmeyen güncelleme, tutarsız build',
cozum: 'npm ci kullanın'
},
{
hata: 'Güncelleme sonrası test etmemek',
sonuc: 'Production'da regression bug',
cozum: 'npm update sonrası her zaman test çalıştırın'
}
];
console.log('
=== Yaygın Hatalar ===');
hatalar.forEach((h, i) => {
console.log(`
${i + 1}. Hata: ${h.hata}`);
console.log(` Sonuç: ${h.sonuc}`);
console.log(` Çözüm: ${h.cozum}`);
});
// Alternatif paket yöneticileri ve lock dosyaları
console.log('
=== Paket Yöneticileri ve Lock Dosyaları ===');
const alternatifler = [
{ yonetici: 'npm', lockDosya: 'package-lock.json' },
{ yonetici: 'yarn', lockDosya: 'yarn.lock' },
{ yonetici: 'pnpm', lockDosya: 'pnpm-lock.yaml' },
{ yonetici: 'bun', lockDosya: 'bun.lockb' }
];
console.table(alternatifler);package-lock.json basit bir dosya gibi görünür ama projenizin tutarlılığının garantisidir. Git'e dahil edin, CI/CD'de npm ci kullanın ve merge conflict'lerde panik yapmayın. Bu kuralları uygularsanız bağımlılık yönetiminde hiç sorun yaşamazsınız. Kolay gelsin.
