npm Komutları: Paket Yönetimi Rehberi

01npm Nedir, Ne İşe Yarar?

npm (Node Package Manager), JavaScript dünyasının paket yöneticisidir. Başkalarının yazdığı kütüphaneleri projenize eklemenizi, sürümlerini takip etmenizi ve projeyle ilgili komutları tek yerden çalıştırmanızı sağlar.

npm, Node.js ile birlikte gelir; ayrıca kurmanız gerekmez. Henüz Node.js kurmadıysanız önce Node.js kurulumu rehberimizi izleyin, ardından bu yazıdaki komutları kendi terminalinizde deneyin.

npm'in üç parçası vardır: bilgisayarınızdaki komut satırı aracı, paketlerin barındırıldığı kayıt (registry) ve her projenin kalbi olan package.json dosyası. Komutların neredeyse hepsi bu dosyayı okur ya da günceller.

02package.json Nedir?

package.json, projenin kimlik kartıdır: adı, sürümü, bağımlılıkları ve çalıştırılabilir betikleri burada yazar. Yeni bir projede bu dosyayı npm init ile oluşturursunuz; -y bayrağı tüm soruları varsayılan yanıtla geçer.

• dependencies: Uygulamanın çalışırken ihtiyaç duyduğu paketler.
• devDependencies: Yalnızca geliştirme ve derleme sırasında gereken araçlar (derleyici, test aracı, biçimlendirici).
• scripts: npm run ile çalıştırılan kısa komutlar.
• package-lock.json: Kurulan her paketin tam sürümünü kaydeder; bu dosyayı Git'e mutlaka ekleyin.

mkdir ilk-proje
cd ilk-proje
npm init -y

{
  "name": "ilk-proje",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "node --test"
  },
  "dependencies": {
    "axios": "^1.7.0"
  },
  "devDependencies": {
    "vite": "^6.0.0"
  }
}

03npm install ile Paket Kurma

npm install en sık kullanılan komuttur ve iki farklı işi yapar. Tek başına yazıldığında package.json'daki tüm bağımlılıkları node_modules klasörüne kurar; bir paket adıyla yazıldığında o paketi kurup package.json'a ekler. Kısa yazımı npm i'dir.

# Projedeki tüm bağımlılıkları kur
npm install

# Yeni paket ekle (dependencies)
npm install axios

# Geliştirme aracı ekle (devDependencies)
npm install -D prettier

# Belirli bir sürümü kur
npm install lodash@4

# Global kurulum (komut satırı araçları için)
npm install -g serve

# Paketi kaldır
npm uninstall axios

Global mi, yerel mi?

Paketleri mümkün olduğunca yerel kurun; böylece proje başka bir bilgisayarda da aynı sürümle çalışır. Global kurulumu yalnızca her yerde kullanacağınız komut satırı araçlarına ayırın, tek seferlik araçlar için ise npx yeterlidir.

npm ci ne zaman kullanılır?

npm ci, node_modules klasörünü silip package-lock.json'daki sürümleri birebir kurar ve kilit dosyasını değiştirmez. Sunucuya dağıtımda, sürekli entegrasyon hatlarında ve “bende çalışıyordu” sorunlarını çözmek için idealdir.

04npm run ile Betik Çalıştırma

package.json'daki scripts alanı, uzun komutlara kısa adlar vermenizi sağlar. Böylece ekipteki herkes, aracın ayrıntısını bilmeden npm run dev ile geliştirme sunucusunu, npm run build ile üretim derlemesini başlatır.

start ve test gibi bazı adlar özeldir; run yazmadan çalışır. Betiğe ek parametre göndermek için iki tire kullanılır.

npm run dev
npm run build
npm start
npm test

# Tanımlı tüm betikleri listele
npm run

# Betiğe parametre geçirme
npm run build -- --mode staging

pre ve post betikleri

Bir betiğin adının başına pre ya da post eklerseniz npm onu otomatik olarak önce ya da sonra çalıştırır. Örneğin prebuild adlı bir betik, npm run build'den hemen önce eski derleme klasörünü temizleyebilir. Bu düzen, ekipte kimsenin bir adımı unutmamasını sağlar.

Betikler neden yerel araçları bulur?

npm run, çalışırken projedeki node_modules/.bin klasörünü geçici olarak PATH'e ekler. Bu yüzden betiğe yalnızca vite ya da prettier yazmanız yeterlidir; aracı global kurmanıza gerek kalmaz. Aynı araç terminalde doğrudan yazıldığında bulunamıyorsa bunun nedeni budur ve çözüm npx kullanmaktır.

Betiklerde işletim sistemi farkı

rm -rf gibi komutlar Windows'un varsayılan kabuğunda çalışmaz. Ekipte farklı işletim sistemleri varsa betiklerde platformdan bağımsız Node.js araçlarını ya da kısa Node.js betiklerini tercih edin; böylece aynı package.json her makinede aynı sonucu verir.

05Paketleri Güncelleme ve Denetleme

Paketler düzenli olarak güncellenir; güvenlik açıkları kapatılır, yeni özellikler gelir. Güncellemeden önce neyin eskidiğini görmek için npm outdated komutunu çalıştırın.

package.json'daki ^ işareti küçük ve yama sürümlerine izin verir (1.7.0 → 1.9.2), ~ işareti yalnızca yama sürümlerine (1.7.0 → 1.7.5). npm update bu sınırlar içinde günceller; ana sürüm atlamak için paketi @latest ile yeniden kurmanız gerekir ve bu genellikle kodda değişiklik ister.

# Eskiyen paketleri listele
npm outdated

# İzin verilen aralıkta güncelle
npm update

# Ana sürüme geç (dikkatli kullanın)
npm install axios@latest

# Güvenlik denetimi
npm audit
npm audit fix

# Kurulu paketleri görüntüle
npm ls --depth=0
npm ls -g --depth=0

# Bir paketin yayındaki son sürümü
npm view axios version

06npx Nedir, Ne Zaman Kullanılır?

npx, npm ile gelen bir paket çalıştırıcıdır. Bir aracı global olarak kurmadan, tek seferlik çalıştırmanızı sağlar; araç önce projedeki node_modules içinde aranır, yoksa geçici olarak indirilir.

Proje şablonu oluşturmak npx'in en yaygın kullanımıdır. Örneğin Vite ile yeni bir React projesi açmak için npm create komutu kullanılır; ayrıntıları Vite ile React kurulumu yazımızda bulabilirsiniz.

# Klasörü yerel sunucuda yayınla
npx serve .

# Projede kurulu biçimlendiriciyi çalıştır
npx prettier --write .

# Şablondan yeni proje (npm create, npx create-... ile aynı işi yapar)
npm create vite@latest

07npm, yarn ve pnpm Farkı

npm tek seçenek değildir; yarn ve pnpm de aynı kayıt üzerinden paket kurar. Üçü de package.json kullandığı için proje yapısı değişmez, fark kurulum hızında, disk kullanımında ve kilit dosyasında ortaya çıkar.

• Bir projede tek bir paket yöneticisi kullanın; iki kilit dosyası birden olması sürüm karışıklığına yol açar.
• Mevcut projeye katılıyorsanız klasördeki kilit dosyasına bakıp aynı aracı seçin.
• Yeni başlıyorsanız npm ile başlamak en az sürtünmeli yoldur.

08Sık Hatalar ve Çözümleri

npm hatalarının çoğu bozuk önbellek, uyumsuz Node.js sürümü ya da çakışan bağımlılıklardan kaynaklanır. Önce hata mesajının ilk satırlarını okuyun; çözümü genellikle orada anlatır.

• ERESOLVE / peer dependency hatası: Paketlerden biri başka bir paketin farklı sürümünü bekliyordur. Paketleri uyumlu sürümlere güncelleyin; geçici çözüm olarak npm install --legacy-peer-deps kullanılabilir.
• Bozuk node_modules: node_modules klasörünü silip npm install ya da npm ci çalıştırın. Kilit dosyasını silmek son çaredir.
• Önbellek sorunu: npm cache verify önbelleği denetler; gerekirse npm cache clean --force ile temizleyin.
• EACCES izin hatası: Global kurulumda sudo kullanmayın; Node.js'i nvm ile yeniden kurun.
• Engine uyarısı: Paket daha yeni bir Node.js istiyorsa nvm ile LTS sürüme geçin.

09npm'i Projelerde Doğru Kullanmak

Gereğinden fazla paket, hem güvenlik riskini hem de sayfanın tarayıcıya gönderdiği JavaScript miktarını artırır. Her yeni bağımlılıktan önce “bunu birkaç satır kodla çözebilir miyim?” diye sormak, sayfa hızı için en ucuz optimizasyondur. Bu konuyu hız ve performans yönetimi hizmetimizde düzenli ele alıyoruz.

node_modules klasörünü asla Git'e eklemeyin; .gitignore dosyasına yazın ve yalnızca package.json ile kilit dosyasını paylaşın. Projeyi uzak depoya göndermeyi GitHub'a proje yükleme rehberimizde adım adım anlattık.

İşletmeniz için web tasarımı ya da ödeme, kargo ve muhasebe sistemlerini birbirine bağlayan bir entegrasyon projesi planlıyorsanız, bağımlılık yönetimini baştan doğru kurmak uzun vadede bakım maliyetini düşürür. Daha fazla Node.js içeriği için nodejs etiketi sayfasına göz atın.