package.json Nedir? Scripts, Dependencies ve Sürümler

Node Projelerinin Manifest Dosyası

Her Node.js projesinin kök dizininde bir package.json dosyası bulunur. Sade bir JSON dosyasıdır ve projenizi tanımlar: adı, sürümü, hangi bağımlılıkları kullandığı, hangi komutları dışa açtığı... Kısacası npm ne zaman bir iş yapacak olsa önce bu dosyaya bakar. Silerseniz npm'in projeniz hakkında hiçbir fikri kalmaz.

Bu dosyayı oluşturmanın en hızlı yolu npm init komutudur:

npm init -y

-y bayrağı tüm soruları atlayıp varsayılan değerleri kabul eder. Sonuçta karşınıza şuna benzer bir dosya çıkar:

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

İşte iskeletin en sade hali. Bu alanların çoğu tek başına pek bir işe yaramaz — asıl değerlerini bağımlılıklar ve script'ler ekledikçe kazanıyorlar.

dependencies ve devDependencies farkı

İşin ağır yükünü neredeyse tamamen iki alan sırtlıyor: dependencies ve devDependencies. İkisi de paket adlarını sürüm aralıklarına eşleyen birer map yapısında.

Bu ayrımın tek bir önemli sebebi var: dependencies, kodunuzun çalışması için gerekli olan paketlerdir. devDependencies ise yalnızca geliştirme sırasında ihtiyaç duyduklarınızdır — test araçları, linter'lar, build araçları, tip kontrolcüleri. Birisi sizin paketinizi kendi projesine bağımlılık olarak kurduğunda, npm yalnızca dependencies altındakileri indirir; devDependencies atlanır.

Bu alanları npm otomatik olarak günceller. npm install express çalıştırdığınızda dependencies altına bir satır eklenir. npm install --save-dev vitest ise devDependencies altına bir satır ekler. Elle düzenlemeniz gereken durumlar çok nadirdir.

Sürüm aralıkları: ^, ~ ve sabit sürüm

^4.19.0 gibi gördüğünüz ifadeler aslında kesin sürümler değil, birer aralık. npm, semver kurallarına uyar ve sürümleri MAJOR.MINOR.PATCH şeklinde üçe ayırır:

• MAJOR artışları geriye dönük uyumluluğu bozar.
• MINOR artışları yeni özellikler ekler, ama mevcut olanı bozmaz.
• PATCH artışları hata düzeltmelerini içerir.

Her yerde karşınıza çıkacak iki operatör şunlar:

"express": "^4.19.0"   // >= 4.19.0 ve < 5.0.0  (4.19.0 veya üstü herhangi bir 4.x.x)
"express": "~4.19.0"   // >= 4.19.0 ve < 4.20.0 (4.19.0 veya üstü herhangi bir 4.19.x)
"express": "4.19.0"    // tam olarak 4.19.0

^ npm'in paket kurarken varsayılan olarak kullandığı işaretçidir. Minor ve patch güncellemelerinin uyumlu kalacağına güvenir. ~ biraz daha temkinli — sadece patch güncellemelerine izin verir. Versiyonu işaretsiz yazarsanız, tam olarak o sürüme sabitlenir.

İşin can alıcı noktası şu: "az önce kurduğum sürüm" ile "aralığın izin verdiği sürüm" aynı şey değil. Bugün express@4.19.0 kurarsınız, bir ay sonra ekip arkadaşınız projeyi klonlayıp kurduğunda ^4.19.0 pekâlâ 4.19.5'e denk gelebilir. İşte tam bu noktada package-lock.json devreye girer — çözümlenen tam sürümleri kaydeder, böylece herkes birebir aynı bağımlılık ağacını alır. Bu dosyayı mutlaka repo'ya commit'leyin.

package.json scripts: Projenizin Komut Arayüzü

scripts alanı, sık kullandığınız komutlara kısayol tanımladığınız yerdir. Buraya eklediğiniz her şeyi npm run <isim> ile çalıştırabilirsiniz:

Script'ler hakkında bilmeniz gereken birkaç nokta:

• npm start, npm test ve birkaç özel ad run anahtar sözcüğüne ihtiyaç duymadan çalışır. Geri kalan her şey için npm run <ad> yazmanız gerekir.
• Script'ler, PATH değişkenine node_modules/.bin eklenmiş bir shell içinde çalışır. Bu sayede kurulu paketlerin binary dosyalarını doğrudan çağırabilirsiniz. Örneğin vitest global olarak kurulu olmasa bile "test": "vitest" sorunsuz çalışır.
• Script'leri zincirleyebilirsiniz: "build": "npm run lint && npm run compile". "Sırayla çalışsın, hata olursa dursun" demek için && kullanın.
• pre<ad> ve post<ad> script'leri otomatik olarak tetiklenir. Mesela prebuild tanımlıysa, build'den önce kendiliğinden çalışır; ekstra bir ayar yapmanıza gerek yok.

Script'ler, projenizin komut arayüzüdür. İyi yazılmış bir package.json sayesinde projeye yeni katılan biri repoyu klonlayıp npm install çalıştırır, ardından wiki'ye bakmadan npm run dev veya npm test komutlarını doğrudan kullanabilir.

Giriş Noktaları: main, exports ve type

Bu alanlar, Node'a (ve bundler'lara) paketinizin nasıl yükleneceğini anlatır.

• type alanı, .js dosyalarının nasıl yorumlanacağını belirler. "module" yazarsanız ESM (import / export) kullanılır. Hiç yazmazsanız veya "commonjs" derseniz CommonJS (require) devreye girer. Detaylar için CommonJS vs ESM dokümanına göz atın.
• main, eski usul giriş noktasıdır — yani require("my-lib") dediğinizde hangi dosyaya çözümleneceğini söyler. Eski araçlar hâlâ bunu dikkate alıyor.
• exports ise bunun modern ve daha katı halidir. Paketi kullananların tam olarak hangi dosyaları, hangi alt yol üzerinden import edebileceğini burada tanımlarsınız. Listede olmayan bir dosyayı import etmeye çalışırsanız hata alırsınız — bu bir bug değil, bilinçli bir tasarım. Public API'nizin kontrolü sizde.

Eğer paket yayınlamıyor, sadece bir uygulama geliştiriyorsanız bunların içinde sizi gerçekten ilgilendiren tek alan muhtemelen type olacaktır.

Gerçek hayattan bir package.json örneği

Hepsini bir araya getirdiğimizde, küçük bir Node uygulamasının package.json dosyası pratikte aşağı yukarı şöyle görünür:

engines.node alanına dikkat edin. Bu alan bilgi amaçlıdır — kullanıcının Node sürümü uyuşmuyorsa npm uyarı verir (engine-strict ile hata fırlatır). Yayınlayacağınız her paket için uygulamanız gereken iyi bir alışkanlık.

Bilmeye Değer Diğer Alanlar

Karşınıza çıkacak birkaç alan daha:

• private: true — paketi yanlışlıkla npm'e yayınlamanızı engeller. Yayınlanmayacak her projeye eklemenizde fayda var.
• license — "MIT" veya "ISC" gibi SPDX tanımlayıcısı. Açık kaynak projelerde önemli.
• repository, bugs, homepage — npm registry sayfanızda görüntülenir.
• bin — paketiniz bir CLI sunuyorsa, komut adlarını burada script dosyalarıyla eşleyin. Kurulumdan sonra bu komutlar doğrudan çalıştırılabilir hale gelir.
• workspaces — monorepo'lar için; npm'e alt dizinleri birbirine bağlı paketler olarak ele almasını söyler.

Hepsine ihtiyacınız yok. Yaptığınız işe uygun olanlara ihtiyacınız var.

Sık Yapılan Hatalar

İnsanların tökezlediği birkaç nokta:

• node_modules klasörünü commit'lemek. Yapmayın. .gitignore dosyasına ekleyin. package.json ve package-lock.json ikilisi, herhangi birinin npm install ile klasörü yeniden oluşturması için yeterli.
• package-lock.json dosyasını commit'lememek. Kesinlikle commit'leyin. Lockfile olmadan "benim makinemde çalışıyordu" senaryosu gerçeğe dönüşür; çünkü semver aralıkları zaman içinde farklı sürümlere çözümlenebilir.
• Çalışma zamanı bağımlılıklarını devDependencies içine koymak. Uygulamanız yerelde dev bağımlılıkları da yüklü olduğu için sorunsuz çalışabilir, ama production ortamında bunlar atlandığı için patlar. Yayınladığınız kod bir paketi kullanıyorsa, o paket dependencies içinde olmalı.
• Sürümleri elle düzenleyip yeniden kurmamak. package.json içinde bir sürümü değiştirdiğinizde npm install çalıştırın — yoksa node_modules ile lockfile senkron dışına çıkar.

Sırada: Node Çalışma Zamanı

package.json, Node'a projenizin ne olduğunu anlatır. Nasıl çalıştığına ise Node çalışma zamanı karar verir — modül çözümleme, yerleşik modüller, global değişkenler ve perde arkasındaki event loop. Bir sonraki sayfanın konusu tam olarak bu.