NPM Outdated

NPM outdated ne işe yarar?

npm outdated, projenizde güncellenebilecek bağımlılıkları listeler. Hangi sürümü kullandığınız (Current), sizin sürüm aralığınıza göre en güncel uyumlu sürüm (Wanted) ve npm’deki en son yayınlanmış sürüm (Latest) gibi sütunları gösterir.

Örnek çıktı:

$ npm outdated
Package       Current  Wanted  Latest  Location
express       4.16.4   4.17.1  5.0.0   my-project
lodash        4.17.11  4.17.21  4.17.21  my-project

Tipik çıktı sütunları:

Package: Paket adı
Current: Şu an kurulu sürüm (node_modules + lock dosyanızdaki)
Wanted: package.json’daki sürüm aralığınıza uyumlu en yeni sürüm
- Örn: ^2.3.0 ise, 2.x içindeki en son sürüm.
Latest: npm kayıt defterindeki (genelde latest dist-tag’i) en son sürüm (major dahil)
Location: Paketin bulunduğu yol (monorepo/workspace’lerde önemli)
(Workspaces kullanıyorsanız) Workspace veya Depended by gibi ek sütunlar görülebilir.

Çıktıyı okuma – küçük bir örnek

Varsayalım:

Package  Current  Wanted  Latest  Location
axios    1.6.7    1.7.7   2.2.1   node_modules/axios

Current: 1.6.7 kurulu.
Wanted: package.json aralığınız ^1.6.0 ise → 1.x’in sonu: 1.7.7
Latest: npm’deki en yeni yayın 2.2.1 (major kırıcı).
Patch/minor güncellemek için:

npm update axios

Major’a geçmek için:

npm install axios@latest
# veya package.json aralığını ^2.2.1 yapıp npm install

En çok kullanılan bayraklar (flags)

Yüzeysel (hızlı) kontrol:

npm outdated --depth=0

Sadece doğrudan bağımlılıkları (direct deps) listeler. En pratik ve hızlı kullanım.

Ayrıntılı çıktı (uzun):

npm outdated --long

Ek sütunlar ve daha fazla detay.

Makineye uygun (parse/JSON):

npm outdated --json
npm outdated --parseable

CI/CD, script ve araç entegrasyonlarında kullanışlıdır.

Global paketler için:

npm outdated -g

Workspaces (monorepo) için:

npm outdated -ws           # tüm workspacelerde tara
npm outdated -w packages/ui --long   # tek bir workspace’i tara
npm outdated --include-workspace-root  # kök package.json’ı da dahil et

Kısaltmalar: -ws = --workspaces, -w <name> = --workspace <name>

Güncelleme yolları

Semver aralığı içinde (patch/minor) güncelle

npm update, package.json aralığınıza uyan en yeni sürümü kurar (genelde major olmayan güncellemeler):

npm update
# veya spesifik paket:
npm update axios
# sadece doğrudan bağımlılıklar:
npm update --depth=0

npm update, Wanted sürüme taşır. Latest (majors) için yeterli olmaz.

Belirli bir sürüme güncelle

npm install lodash@4.17.21

Doğrudan istediğiniz sürümü kurar ve package.json/lock dosyasını günceller.

En son (Latest, major dahil) sürüme güncelle

npm install react@latest

react için latest dist-tag’lı sürüme (major dahil) geçer.

Sürüm aralığını değiştirerek gelecekte kolay güncelle

package.json’da aralığınızı tilde/karat ile bilinçli ayarlayın:

^1.2.3 → 1.x içindeki minor+patch’leri alır
~1.2.3 → sadece patch’leri alır
1.2.3 → sabit (hiçbir otomatik artış yok)

package.json’da duzeltme yaptıktan sonra:

npm update

diyerek Wanted → en üst uygun sürüme yükseltirsiniz.

Tüm bağımlılıkları major dahil toplu yükseltme

Resmi npm dışı ama pratik bir araç: npm-check-updates (ncu)

npx npm-check-updates        # package.json’daki aralıkları Latest’a çevirip gösterir
npx npm-check-updates -u     # package.json’ı yeni aralıklara günceller (major dahil)
npm install                  # lock ve node_modules güncellenir

Bu, major değişiklikleri de “aralık” olarak günceller; sonrasında test şart!

“Wanted” ve “Latest” nasıl belirlenir? (Semver kısa dersi)

SemVer, projenin geliştirme sürecini takip etmemizi sağlar. Sürüm numaraları, projenin hangi aşamada olduğunu gösterir ve değişikliklerin ne tür olduğunu anlatır.

package.json satırınız ^2.3.0 ise:
- Wanted: 2.x’teki en yeni sürüm (örn. 2.9.5)
- Latest: npm’deki en güncel release (örn. 3.1.0) → major kırıcı olabilir.
~2.3.0 → 2.3.x patch’lerine izin verir.
2.3.0 (sabit) → Wanted == Current kalır; npm update bir şey yapmaz (sürüm aralığını genişletmeden).

dist-tags:

Bir paket latest dışında next, beta, rc gibi etiketler (tag) yayınlayabilir.

npm view mylib dist-tags
npm install mylib@next

Workspaces (Monorepo) – pratik akış

Tüm workspacelerde tarama:

npm outdated -ws --depth=0

Tek bir workspace içinde güncelleme:

npm -w packages/ui update
npm -w packages/ui install axios@latest

Bir bağımlılığı tüm workspacelerde aynı sürüme sabitlemek için:

Kök package.json’a overrides yazabilirsiniz (npm v8+):

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

Ardından:

npm install

Bu, alttaki paketlerin istediği sürüm aralığını override eder.

Global paket güncellemeleri

Globalde hangi paketler eski?

npm outdated -g --depth=0

Güncellemek için:

npm update -g
# veya
npm install -g typescript@latest

Pre-release & tag’ler

Pre-release sürümler 1.2.3-beta.1 gibi görünür. latest yere next kullanmak:

npm install mylib@next
npm outdated --long  # pre-release ve tag bilgileri için faydalı olabilir

Yaygın senaryolar – “Reçeteler”

“Sadece patch/minor güncellemeleri alayım”

npm outdated --depth=0
npm update --depth=0

“Şu üç paketi en son sürüme (major dahil) çıkar”

npm install pkg1@latest pkg2@latest pkg3@latest

“Tüm projeyi major dahil güncelleyin, ama kontrollü”

# 1) Neler eski? (özet)
npm outdated --depth=0

# 2) Aralıkları Latest’a çek (major dahil)
npx npm-check-updates -u

# 3) Kur ve test et
npm install
npm test

“Sadece doğrudan bağımlılıklarımı listelemek istiyorum (hızlı CI adımı)”

npm ci
npm outdated --depth=0 --json > outdated.json
# JSON’ı CI raporu olarak yorumlayın

“Monorepo’da tek bir paketin bağımlılıklarını güncelle”

npm -w packages/api outdated --depth=0
npm -w packages/api update

Sık karşılaşılan sorunlar ve ipuçları

“Nothing to update” ama npm outdated liste gösteriyor? npm update sadece Wanted’a kadar çıkartır. Latest (major) istiyorsanız npm install pkg@latest.
Lock dosyası / node_modules bozuk hissediyorsanız:
Terminal window
```
rm -rf node_modules package-lock.json
npm install
```
Özel/şirket içi registry kullanıyorsanız: .npmrc ayarlarını (auth token, registry URL) kontrol edin. Yanlış registry, Latest verisini yanlış gösterir.
Peer dependency çakışmaları: Major yükseltirken peerDependencies uyarılarına dikkat edin. Genelde bağlı paketleri koordineli yükseltmek gerekir.
Engine (Node sürümü) kısıtları: Paket engines.node ile daha yeni Node isteyebilir. Node LTS sürümünde kalmaya çalışın.

Hızlı “Cheat Sheet”

# Durum
npm outdated --depth=0
npm outdated --long
npm outdated --json

# Patch/Minor (semver aralığı içinde)
npm update
npm update <paket>

# En son (major dahil)
npm install <paket>@latest

# Belirli sürüm
npm install <paket>@1.4.2

# Workspaces
npm outdated -ws --depth=0
npm -w packages/ui outdated --depth=0
npm -w packages/ui update
npm -w packages/ui install <paket>@latest

# Global
npm outdated -g --depth=0
npm update -g

Önceki sürüme geri dönme

Bir güncellemeden sonra sorun yaşarsanız? Önceki sürüme dönebilirmisiniz?

Evet geri dönmek mümkün ve sık yapılan bir pratiktir.

En güvenlisi: Git’te paket dosyalarını eski haline al + npm ci ile temiz kurulum. Sadece tek bir paketi geri almak istiyorsan npm install paket@eski yeter. Transitif bağımlılık sorunlarında overrides ile ağaç sabitlemek çok işe yarar. Geri dönüşün sorun çıkarma ihtimali; kodun yeni API’lere göre değiştirilmiş olması, peer dependency çakışmaları ve lockfile tutarsızlıklarıyla sınırlıdır—bunları yukarıdaki adımlarla bertaraf edebilirsin.

Sadece bir paketi güncelledin → eski sürüme dön

Eski versiyonu net biliyorsan:

# proje kökünde
npm install <paket>@<ESKI_SURUM>
# örn: npm install axios@1.6.7

Bu, package.json ve package-lock.json’ı eski sürüme göre günceller.

Eski sürümü bilmiyorsan:

npm view <paket> versions --json
# sürüm listesinden seç → sonra:
npm install <paket>@<ESKI_SURUM>

Workspaces (monorepo):

npm -w packages/ui install <paket>@<ESKI_SURUM>

“npm update” ile birden fazla paket güncellendi → tamamen geri al

En temiz ve güvenli yöntem: Git ile paket dosyalarını geri al.

git checkout -- package.json package-lock.json
rm -rf node_modules
npm ci

it checkout … → bu iki dosyayı güncelleme öncesi haline getirir.
npm ci → lockfile’a birebir uygun node_modules kurar (CI için de önerilen).

Git commit’leri mevcutsa, direkt “güncelleme commit’ini” revert etmek en sağlıklısıdır.

Sorun transitif (dolaylı) bir bağımlılıkta ise (sen doğrudan kurmadın)

overrides (npm v8+) ile ağacı zorla sabitle:

{
  "overrides": {
    "yup": "1.2.0",
    "some-lib > dayjs": "1.11.10"   // sadece some-lib altındaki dayjs’i sabitle
  }
}

Sonra:

rm -rf node_modules package-lock.json
npm install

Workspaces’ta overrides’ı kökte tutmak genelde daha etkilidir.

Global paketleri geri al

npm install -g <paket>@<ESKI_SURUM>

Geri alırken neler sorun çıkarabilir?

Kod artık yeni API’yi kullanıyorsa

Eski sürüme dönünce build/test kırılabilir. Gerekirse ilgili kod değişikliklerini de geri alın.

Çözüm: Güncellemeyi yapan commit’i komple revert edin (kod + package.json + lockfile).
Peer dependency uyuşmazlıkları

Eski sürüme döndüğünde başka paketlerin istediği peer aralıklarıyla çakışabilir.

Çözüm: İlgili peer’leri de birlikte geri alın veya overrides ile koordine edin.
Lockfile ile node_modules uyumsuzluğu

Elle dosya kurcalandıysa “şans eseri” çalışan bir ağaç oluşabilir.

Çözüm: Her zaman rm -rf node_modules && npm ci ile temiz kurulum.
Semver aralıkları çok geniş (^ veya ~)

Sonraki kurulumlarda tekrar istenmeyen sürüme sıçrayabilir.

Çözüm: Kritik paketleri geçici olarak sabit sürüm (ör. “1.6.7”) veya ~ ile daralt; ya da overrides kullan.

En iyi pratik “geri alma” akışı (üretim için güvenli)

Önce Git’te geri al:

Güncelleme commit’ini revert et veya package.json + package-lock.json’ı güncelleme öncesine döndür.

Temiz kurulum:

rm -rf node_modules
npm ci

Test: Unit/E2E + smoke testler.
Gerekiyorsa overrides ile ağacı sabitle.
Konfig: Gelecekte kazara sıçramayı önlemek için:
- Kritik bağımlılıkları geçici sabit sürüme alın (save-prefix’i boş yapabilirsiniz):
  Terminal window
```
npm config set save-prefix=""
# veya package.json’da manuel sabit sürüm
```
- CI’da sadece npm ci kullanın.