[NODE JS] package.json Dosyasını Anlamak
Selam arkadaşlar. package.json dosyası her Node.js projesinin kalbidir. Projenizin kim olduğunu, ne yaptığını, hangi bağımlılıklara sahip olduğunu ve nasıl çalıştırılacağını tanımlayan dosyadır. Ben ilk başlarda bu dosyayı sadece npm install ile otomatik oluşan bir şey sanıyordum ama zamanla ne kadar önemli ve güçlü olduğunu anladım.
Temel Alanlar
package.json aslında bir JSON dosyasıdır ve belirli alanlardan oluşur. Bazıları zorunlu, bazıları opsiyonel. name ve version zorunlu alanlardır, gerisi projenizin ihtiyacına göre eklenir. Bir paket yayınlayacaksanız tüm alanları düzgün doldurmanız gerekir ama sadece kendi projenizde kullanıyorsanız temel alanlar yeterli.
Tecrübeme göre en çok ihmal edilen alan scripts. Çoğu kişi sadece start ve test yazar ama scripts alanını düzgün kullanmak geliştirme sürecini çok hızlandırır. Build, lint, format, migration, seed gibi tüm komutları buraya ekleyebilirsiniz.
JavaScript:
// === PACKAGE.JSON YAPISI ===
const packageJsonOrnegi = {
// Zorunlu alanlar
"name": "proje-adi", // Paket adı (küçük harf, tire/alt çizgi, @ ile scope)
"version": "1.2.3", // Semantic versioning (major.minor.patch)
// Açıklayıcı alanlar
"description": "Proje açıklaması",
"keywords": ["nodejs", "api", "rest"],
"author": "İsim <email@example.com> (https://website.com)",
"license": "MIT",
"homepage": "https://github.com/user/repo",
"repository": {
"type": "git",
"url": "https://github.com/user/repo.git"
},
"bugs": {
"url": "https://github.com/user/repo/issues"
},
// Giriş noktaları
"main": "src/index.js", // CommonJS giriş noktası
"module": "src/index.mjs", // ES Module giriş noktası
"types": "src/index.d.ts", // TypeScript tip tanımları
"type": "module", // "module" veya "commonjs" (varsayılan)
"exports": { // Modern giriş noktası tanımı
".": {
"import": "./src/index.mjs",
"require": "./src/index.cjs"
},
"./utils": "./src/utils.js"
},
// Çalıştırılabilir dosyalar
"bin": {
"myapp": "./bin/cli.js"
},
"files": ["src/", "bin/", "README.md"], // npm publish'te dahil edilecek dosyalar
// Motor gereksinimleri
"engines": {
"node": ">=18.0.0",
"npm": ">=9.0.0"
},
// Script'ler (en önemli alan!)
"scripts": {
"start": "node src/index.js",
"dev": "node --watch src/index.js",
"build": "tsc",
"test": "jest",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"lint": "eslint src/",
"lint:fix": "eslint src/ --fix",
"format": "prettier --write src/",
"db:migrate": "node scripts/migrate.js",
"db:seed": "node scripts/seed.js",
"docker:build": "docker build -t myapp .",
"docker:run": "docker run -p 3000:3000 myapp",
"prestart": "npm run build", // start öncesi otomatik çalışır
"postinstall": "npm run build" // install sonrası otomatik çalışır
}
};
console.log('Package.json yapısı:');
console.log(JSON.stringify(packageJsonOrnegi, null, 2));Bağımlılık Yönetimi
package.json'ın en kritik bölümlerinden biri bağımlılık alanlarıdır. dependencies, devDependencies, peerDependencies ve optionalDependencies olmak üzere dört tür bağımlılık var. Hangisine ne koyacağınızı bilmek önemli çünkü production'da gereksiz paketler yüklemek istemezsiniz.
Versiyon numaralarının başındaki işaretler de önemli: ^ (caret) minor güncellemelere izin verir, ~ (tilde) sadece patch güncellemelere izin verir, işaretsiz ise tam o versiyon yüklenir. Ben genelde ^ kullanıyorum ama kritik bağımlılıklarda tam versiyon kilitlemeyi tercih ediyorum.
JavaScript:
// === BAĞIMLILIK YÖNETİMİ ===
const bagimliliklar = {
// Production bağımlılıkları (uygulama çalışırken gerekli)
"dependencies": {
"express": "^4.18.2", // ^: >=4.18.2, <5.0.0 (minor güncelleme OK)
"mongoose": "~7.6.0", // ~: >=7.6.0, <7.7.0 (patch güncelleme OK)
"dotenv": "16.3.1", // Tam bu versiyon
"jsonwebtoken": "^9.0.0",
"bcrypt": "^5.1.0",
"cors": "^2.8.5",
"helmet": "^7.0.0",
"winston": "^3.11.0",
"joi": "^17.11.0"
},
// Geliştirme bağımlılıkları (sadece development'ta gerekli)
"devDependencies": {
"nodemon": "^3.0.0",
"jest": "^29.7.0",
"eslint": "^8.50.0",
"prettier": "^3.0.0",
"supertest": "^6.3.0",
"@types/node": "^20.0.0",
"typescript": "^5.2.0"
},
// Peer bağımlılıkları (kütüphane yazarken, host projenin sağlaması gereken)
"peerDependencies": {
"react": "^18.0.0" // Eklenti/plugin yazarken
},
// Opsiyonel bağımlılıklar (bulunamazsa hata vermez)
"optionalDependencies": {
"fsevents": "^2.3.0" // macOS'a özel
}
};
// Versiyon aralıkları açıklaması
const versiyonlar = [
{ sembol: '"1.2.3"', aciklama: 'Tam olarak 1.2.3' },
{ sembol: '"^1.2.3"', aciklama: '>=1.2.3, <2.0.0 (minor+patch güncellemeler)' },
{ sembol: '"~1.2.3"', aciklama: '>=1.2.3, <1.3.0 (sadece patch güncellemeler)' },
{ sembol: '">=1.2.3"', aciklama: '1.2.3 ve üzeri herhangi bir versiyon' },
{ sembol: '"*"', aciklama: 'Herhangi bir versiyon (TEHLİKELİ!)' },
{ sembol: '"latest"', aciklama: 'En son yayınlanan versiyon' },
{ sembol: '"1.x"', aciklama: '1.0.0'dan 2.0.0'a kadar' }
];
console.log('
=== Versiyon Aralıkları ===');
console.table(versiyonlar);
// Semantic Versioning (SemVer) açıklaması
console.log('
=== Semantic Versioning ===');
console.log('MAJOR.MINOR.PATCH');
console.log('MAJOR: Geriye uyumsuz API değişiklikleri (breaking changes)');
console.log('MINOR: Geriye uyumlu yeni özellikler');
console.log('PATCH: Geriye uyumlu hata düzeltmeleri');
console.log('');
console.log('Örnekler:');
console.log(' 1.0.0 -> 1.0.1 : Bug fix (patch)');
console.log(' 1.0.0 -> 1.1.0 : Yeni özellik (minor)');
console.log(' 1.0.0 -> 2.0.0 : Breaking change (major)');
// npm komutları özeti
const npmKomutlari = [
{ komut: 'npm init', aciklama: 'Yeni package.json oluşturur' },
{ komut: 'npm init -y', aciklama: 'Varsayılanlarla hızlı oluşturur' },
{ komut: 'npm install', aciklama: 'Tüm bağımlılıkları yükler' },
{ komut: 'npm install paket', aciklama: 'Paketi dependencies'e ekler' },
{ komut: 'npm install -D paket', aciklama: 'devDependencies'e ekler' },
{ komut: 'npm uninstall paket', aciklama: 'Paketi kaldırır' },
{ komut: 'npm update', aciklama: 'Paketleri günceller' },
{ komut: 'npm outdated', aciklama: 'Güncel olmayan paketleri listeler' },
{ komut: 'npm audit', aciklama: 'Güvenlik açıklarını kontrol eder' },
{ komut: 'npm run script_adi', aciklama: 'Script çalıştırır' }
];
console.log('
=== npm Komutları ===');
console.table(npmKomutlari);
console.log(JSON.stringify(bagimliliklar, null, 2));package.json dosyasını iyi anlamak projenizin sağlığı için çok önemli. Scripts alanını aktif kullanın, bağımlılıkları doğru kategoriye koyun ve versiyon aralıklarını bilinçli seçin. Bu alışkanlıkları edinirseniz proje yönetiminiz çok daha düzenli olur. Kolay gelsin.
