Node.js ve npm Rehberi: package.json, Modüller, Bağımlılıklar ve npm Scriptleri
Node.js nedir, npm ne işe yarar, package.json ve package-lock.json neden önemlidir? ES modülleri, sürüm aralıkları, npm scriptleri ve bağımlılık güvenliğini uygulamalı örneklerle anlatıyoruz.

JavaScript uzun yıllar yalnızca tarayıcıda yaşadı. Node.js, Chrome’un V8 motorunu tarayıcı dışına taşıyarak JavaScript’i sunucularda, komut satırı araçlarında ve otomasyon betiklerinde çalıştırılabilir hâle getirdi. Bugün bir web projesine başladığınızda kullanacağınız derleme araçlarının, test kütüphanelerinin ve geliştirme sunucularının büyük kısmı Node.js üzerinde çalışır ve npm ile kurulur. Bu yazıda ikisini birlikte, sıfırdan ele alıyoruz.
Node.js’i kurmak ve sürüm seçmek
Node.js’in resmî sitesinden (nodejs.org) indirme yapabilir ya da Windows’ta winget install OpenJS.NodeJS.LTS komutunu kullanabilirsiniz. Kurulumda iki seçenekle karşılaşırsınız:
- LTS (Long Term Support): Uzun süreli destek alan, kararlı sürüm. Projeler için doğru tercih budur.
- Current: En yeni özellikleri içeren, daha kısa destek süreli sürüm.
Kurulumdan sonra terminalde kontrol edin:
node --version
npm --version
Farklı projelerde farklı Node sürümleri gerekiyorsa nvm (macOS/Linux), nvm-windows veya fnm gibi sürüm yöneticileri işinizi kolaylaştırır.
İlk Node.js programı
merhaba.js adlı bir dosya oluşturun:
const ad = process.argv[2] ?? "Dünya";
console.log(`Merhaba, ${ad}!`);
console.log(`Node sürümü: ${process.version}`);
node merhaba.js Teknoedu
Tarayıcıdaki window ve document nesneleri Node.js’te yoktur. Bunun yerine process (çalışan işlem bilgisi), dosya sistemi (node:fs), yollar (node:path) ve HTTP (node:http) gibi yerleşik modüller vardır.
Hiç paket kurmadan küçük bir web sunucusu bile yazabilirsiniz. Aşağıdaki kodu sunucu.mjs olarak kaydedip node sunucu.mjs ile çalıştırın, ardından tarayıcıda http://localhost:3000 adresini açın:
import { createServer } from "node:http";
const sunucu = createServer((istek, yanit) => {
yanit.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
yanit.end(JSON.stringify({ mesaj: "Merhaba", yol: istek.url }));
});
sunucu.listen(3000, () => console.log("http://localhost:3000 dinleniyor"));
Gerçek projelerde yönlendirme, gövde ayrıştırma ve hata yönetimi için Express veya Fastify gibi çatılar tercih edilir; ama bunların hepsi bu yerleşik modülün üzerine kuruludur.
package.json: Projenin kimlik kartı
Yeni bir proje başlatmak için:
mkdir not-araci && cd not-araci
npm init -y
Oluşan package.json dosyasını şöyle düzenleyelim:
{
"name": "not-araci",
"version": "1.0.0",
"type": "module",
"main": "src/index.js",
"scripts": {
"start": "node src/index.js",
"dev": "node --watch src/index.js",
"test": "node --test"
},
"dependencies": {},
"devDependencies": {}
}
type: "module": Proje dosyalarının ES modülü (import/export) olarak yorumlanmasını sağlar.scripts: Sık kullanılan komutların kısayolları.dependencies: Uygulamanın çalışması için gereken paketler.devDependencies: Yalnızca geliştirme sırasında gereken paketler (test, lint, derleme araçları).
Modüller: import ve export
Kodu dosyalara bölmek için ES modüllerini kullanın. src/hesap.js:
export function ortalama(sayilar) {
if (sayilar.length === 0) return 0;
return sayilar.reduce((a, b) => a + b, 0) / sayilar.length;
}
export const GECME_NOTU = 50;
src/index.js:
import { readFile } from "node:fs/promises";
import { ortalama, GECME_NOTU } from "./hesap.js";
const metin = await readFile(new URL("../notlar.txt", import.meta.url), "utf8");
const notlar = metin.split(/\r?\n/).filter(Boolean).map(Number);
const ort = ortalama(notlar);
console.log(`Ortalama: ${ort.toFixed(2)}`);
console.log(ort >= GECME_NOTU ? "Sınıf geçti" : "Sınıf kaldı");
Proje kökünde her satıra bir sayı yazdığınız notlar.txt dosyasını oluşturup npm start ile çalıştırın. Dikkat: ES modüllerinde göreli içe aktarmalarda dosya uzantısı (.js) zorunludur. node: öneki ise yerleşik modülleri npm paketlerinden ayırt etmeyi kolaylaştırır.
Eski projelerde
require()vemodule.exportsile yazılmış CommonJS sözdizimini göreceksiniz. Yeni projelerde ES modüllerini tercih edin; ama okuyabilmek için CommonJS’i de tanımakta fayda var.
Paket kurmak ve kaldırmak
npm install dayjs # dependencies'e ekler
npm install --save-dev eslint # devDependencies'e ekler
npm uninstall dayjs # kaldırır
npm list --depth=0 # doğrudan bağımlılıkları listeler
npm outdated # güncellenebilir paketleri gösterir
Kurulan paketler node_modules klasörüne iner. Bu klasör çok büyük olabilir ve asla sürüm kontrolüne eklenmez. .gitignore dosyanıza mutlaka node_modules/ satırını ekleyin.
Sürüm aralıkları: ^ ve ~ ne demek?
npm paketleri anlamsal sürümleme (semantic versioning) kullanır: ANA.KÜÇÜK.YAMA (ör. 4.18.2).
| Yazım | İzin verilen güncellemeler | Örnek |
|---|---|---|
"4.18.2" |
Yalnızca tam olarak bu sürüm | 4.18.2 |
"~4.18.2" |
Yama güncellemeleri | 4.18.x |
"^4.18.2" |
Küçük ve yama güncellemeleri | 4.x.x |
"*" |
Her şey (kullanmayın) |
npm install varsayılan olarak ^ ekler. Ana sürüm değişikliği (4’ten 5’e) uyumluluğu bozan değişiklikler içerebileceği için otomatik yapılmaz.
package-lock.json neden önemli?
package.json aralıkları tanımlar; package-lock.json ise o an kurulan tam sürümleri, alt bağımlılıklarla birlikte kaydeder. Bu dosya sayesinde ekipteki herkes ve sunucu aynı paket ağacını kurar. Kurallar:
package-lock.jsondosyasını sürüm kontrolüne ekleyin.- Sürekli entegrasyon ortamlarında ve sunucularda
npm installyerinenpm cikullanın.npm ci, kilit dosyasına birebir uyar,node_modulesklasörünü sıfırdan kurar ve kilit dosyası ilepackage.jsonuyuşmazsa hata verir.
npm scriptleri ve npx
scripts bölümündeki komutlar npm run <ad> ile çalışır. start ve test için run yazmak gerekmez:
npm start
npm test
npm run dev
Scriptlerin güzel yanı, node_modules/.bin klasöründeki araçları yol belirtmeden çağırabilmesidir. Örneğin projeye ESLint kurduysanız "lint": "eslint src" yazmanız yeterli.
npx ise bir paketi kalıcı olarak kurmadan çalıştırmanızı sağlar: npx tsc --init gibi. Bilmediğiniz bir paketi npx ile çalıştırmadan önce adını iki kez kontrol edin; yazım hatası taklitçiliği (typosquatting) gerçek bir saldırı yöntemidir.
Yerleşik geliştirme özellikleri
Güncel Node.js sürümleri, eskiden ek paket gerektiren bazı işleri kendisi yapar:
node --watch dosya.js: Dosya değiştiğinde süreci yeniden başlatır.node --test: Yerleşik test çalıştırıcısı (node:testmodülü).fetch: Node.js 18 ve sonrasında genel kapsamda kullanılabilir.node --env-file=.env app.js: Ortam değişkenlerini bir dosyadan yükler (Node.js 20.6 ve sonrası).
Bağımlılık güvenliği
Her paket, projenize başkasının kodunu getirir. Birkaç temel alışkanlık riski ciddi biçimde azaltır:
npm auditile bilinen açıkları düzenli kontrol edin.- Paket eklemeden önce indirilme sayısına, bakım durumuna ve depo bağlantısına bakın.
- Tek satırlık işler için paket eklemeyin; çoğu zaman dilin kendi özellikleri yeter.
- Kilit dosyasını commit edin ve CI’da
npm cikullanın. - Gizli bilgileri (API anahtarları) koda değil ortam değişkenlerine koyun ve
.envdosyasını.gitignore‘a ekleyin.
Sonuç
Node.js, JavaScript’i tarayıcının dışına çıkaran çalışma ortamı; npm ise bu ekosistemin paket yöneticisidir. package.json ile projenizi tanımlar, ES modülleriyle kodunuzu düzenler, kilit dosyası ve npm ci ile kurulumları tekrarlanabilir kılarsınız. Bu temeller oturduğunda Express veya Fastify ile API yazmak, Vite ile ön yüz geliştirmek ya da kendi komut satırı aracınızı yayınlamak çok daha kolay gelecek.


