npm Nedir? install, init ve Paket Yönetimi

npm Nedir, Ne İşe Yarar?

npm aslında tek isim altında toplanmış üç farklı şeydir. Birincisi bir registry yani npmjs.com üzerinde yer alan devasa ve herkese açık JavaScript paket veritabanı. İkincisi Node.js ile birlikte gelen ve bu paketleri kurup yönetmeye yarayan bir komut satırı aracı. Üçüncüsü ise bir projenin nelere ihtiyaç duyduğunu anlatan spesifikasyon, yani bildiğimiz package.json formatı.

npm install express komutunu çalıştırdığında CLI registry ile konuşur, express paketini ve bağımlı olduğu her şeyi indirir, dosyaları node_modules adlı klasöre yerleştirir ve paketi sürümüyle birlikte package.json dosyana kaydeder. Döngünün tamamı bu kadar basit.

Node.js kuruluysa npm de sende zaten var demektir. Kontrol etmek için:

node --version
npm --version

İkisi de bir sürüm numarası yazdırıyorsa, her şey hazır demektir.

Projeyi Başlatmak: npm init

Her npm projesinin bir package.json dosyasına ihtiyacı vardır. Bu dosya projenin manifestosu gibidir; projenin adını, sürümünü, script'lerini ve bağımlılıklarını (dependencies) içinde tutar. En hızlı oluşturma yolu ise npm init -y komutudur — bu komut tüm varsayılan değerleri olduğu gibi kabul eder:

mkdir my-app
cd my-app
npm init -y

Şuna benzer bir çıktı verir:

{
  "name": "my-app",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

-y bayrağını kullanmazsan npm sana tüm alanları tek tek sorarak interaktif bir şekilde ilerler. Hangi yolu seçersen seç, sonuçta bir package.json dosyan olur — diğer her şeyin bağlandığı dosya burası. Bu dosyanın alanlarını bir sonraki sayfada detaylıca inceleyeceğiz.

npm install kullanımı: Paket kurulumu

Elinde bir package.json olduktan sonra, istediğin paketi npm install komutuyla (ya da kısaca npm i ile) kurabilirsin:

npm install lodash

Bu komut aslında üç iş birden yapıyor:

1. npm, lodash paketini ve bağımlılıklarını indirip node_modules/ klasörüne yerleştirir.
2. package.json dosyasındaki dependencies bölümüne "lodash": "^4.17.21" (ya da o an güncel olan sürüm) satırını ekler.
3. Ağaçtaki her paketin birebir sürümünü kayıt altına alan bir package-lock.json dosyası oluşturur.

Artık paketi kullanabilirsin:

require çağrısı (ya da ESM projelerinde import) paketi node_modules klasörüne bakarak bulur. Herhangi bir yol yazmanıza gerek yok — Node'un modül çözümleyicisi bu işi sizin yerinize halleder.

dependencies ve devDependencies farkı

Uygulamanız production ortamında çalışırken her pakete ihtiyacınız olmaz. Test framework'leri, linter'lar ve bundler'lar yalnızca geliştirme sürecinde işinize yarar. Bu tür paketleri --save-dev (veya kısaca -D) ile kurun:

npm install --save-dev jest
npm install -D eslint prettier

Bunlar dependencies yerine devDependencies altına düşer:

{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5"
  }
}

Production ortamındaki bir sunucuda npm install --omit=dev komutu, devDependencies bölümünü tamamen atlar; böylece kurulum hem daha küçük hem de daha hızlı olur. Bu ayrımı doğru yapmak göründüğünden çok daha önemli — yanlışlıkla dependencies altına düşmüş bir webpack, her production deploy'unu gereksiz yere şişirir.

Tüm Paketleri Tek Seferde Kurmak

İçinde zaten bir package.json bulunan bir repo'yu klonladığında, paketleri tek tek yazmana gerek yok. Şu komutu çalıştırman yeterli:

npm install

Argümansız çalıştırıldığında npm, package.json dosyasını okur (ve package-lock.json içindeki kesin sürümlere sadık kalarak) tüm bağımlılık ağacını node_modules klasörüne kurar. Yeni çekilmiş bir projede ilk çalıştıracağın komut budur.

node_modules klasörünün .gitignore içinde olmasının sebebi de tam olarak bu. Zaten lock dosyasından birebir yeniden üretilebiliyor, boyutu devasa ve her npm install çalıştığında değişiyor. Sen package.json ve package-lock.json dosyalarını commit'le yeter; node_modules'u herkes kendi makinesinde yeniden oluşturur.

npm Paket Güncelleme

Hangi paketlerin geride kaldığını görmek için npm outdated komutunu kullanırız:

npm outdated

Current, Wanted ve Latest sütunlarının olduğu bir tablo göreceksiniz. Wanted, package.json dosyasındaki aralığın izin verdiği en yeni sürümdür (örneğin ^4.17.21 için 5.0.0 altındaki her şey). Latest ise yayınlanmış en son sürümdür; bu, henüz geçiş yapmadığınız bir major sürüm olabilir.

İzin verilen aralık içinde güncelleme yapmak için:

npm update

Paketi major sürüm atlamaları dahil gerçek anlamda en son haline yükseltmek için paketi @latest ile tekrar kurun:

npm install lodash@latest

Major sürüm atlamaları kodunuzu bozabilir — versiyon numarasının size söylemeye çalıştığı şey tam olarak bu. Böyle bir geçiş yapmadan önce mutlaka changelog'u okuyun.

Paket kaldırma

Bir paketi kaldırmak, kurmanın simetriği:

npm uninstall lodash

Bu komut paketi hem node_modules klasöründen siler hem de package.json içindeki kaydını temizler. Paket bir dev dependency ise -D bayrağını eklemen işe yarar (npm aslında türünü kendi anlıyor ama açık yazmak, script'lerde sürpriz yaşamamanı sağlar).

Global vs local kurulum

Kurulumların neredeyse tamamı local olmalı — yani paket, projenin kendi node_modules klasörüne sabitlenmeli. Tek istisna, her yerden erişmek istediğin komut satırı araçları:

npm install -g typescript
npm install -g http-server

Global kurulum, aracı sistem genelinde bir konuma yerleştirir ve bin girdisini PATH'inize ekler; böylece tsc veya http-server gibi komutları herhangi bir dizinden çalıştırabilirsiniz. Ancak global kurulumlar proje bazında takip edilmediği için makineler arasında sürüm tutarsızlıkları yaşanabilir.

Tek seferlik komutlar için daha sağlıklı bir orta yol, npm ile birlikte gelen npx'tir:

npx create-react-app my-app
npx prettier --write .

npx, paketi global olarak kurmana gerek kalmadan çalıştırır — anında indirir, işini görür ve biter. Bir kere kullanıp bırakacağın araçlar için, kalıcı global kurulumdan çok daha temiz bir yol.

Kısa ve Öz Bir Kopya Kâğıdı

Günlük hayatta gerçekten işine yarayacak komutlar:

npm init -y                     # package.json oluştur
npm install                     # package.json'daki her şeyi yükle
npm install <pkg>               # çalışma zamanı bağımlılığı ekle
npm install -D <pkg>            # geliştirme bağımlılığı ekle
npm install -g <pkg>            # CLI aracını global olarak yükle
npm uninstall <pkg>             # bir bağımlılığı kaldır
npm outdated                    # neyin güncel olmadığını gör
npm update                      # izin verilen aralıklar içinde güncelle
npm install <pkg>@latest        # en yeni sürüme geç
npm run <script>                # package.json'dan bir script çalıştır
npx <pkg>                       # bir paketi yüklemeden çalıştır

npm'in büyük kısmı bu kadar. Geri kalanı — yayınlama, workspaces, scoped paketler — ihtiyaç duyduğunda öğrenirsin.

node_modules Klasöründe Gerçekte Ne Var?

Son bir zihinsel model. node_modules, projenin bağımlı olduğu tüm paketleri ve o paketlerin de bağımlı olduğu her şeyi — yani tüm bağımlılık zincirini — içeren, görece düz bir klasördür. Tek bir paket kurarsın, bakarsın yüz tane paket inmiş; bu gayet normal. npm mümkün olan yerlerde tekrarları temizler, yani aynı lodash sürümüne bağımlı iki paket tek bir kopyayı paylaşır.

Kilit dosyası (package-lock.json) ise bu paketlerin her birinin çözümlenmiş tam sürümünü kaydeder. Build'lerin tekrarlanabilir olmasını sağlayan şey tam olarak budur: aynı lockfile ile npm install çalıştıran iki geliştirici, aradan aylar geçse bile bayt bayt aynı ağacı elde eder.

node_modules'u üretilmiş bir çıktı gibi düşün. Asla içindeki dosyaları elle düzenleme — biri tekrar install çalıştırdığı anda değişikliklerin uçup gider.

Sırada: package.json

package.json, npm'in arka planda sürekli okuyup yeniden yazdığı dosyadır. Alanlarını bilmek — scripts, main, type, sürüm aralıkları, engines — npm'i kara kutu olmaktan çıkarıp kontrol edebildiğin bir şeye dönüştürür. Sıradaki konu bu.