info@teknoedu.com
Yazılım

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.

Node.js ve npm Rehberi: package.json, Modüller, Bağımlılıklar ve npm Scriptleri

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() ve module.exports ile 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.json dosyasını sürüm kontrolüne ekleyin.
  • Sürekli entegrasyon ortamlarında ve sunucularda npm install yerine npm ci kullanın. npm ci, kilit dosyasına birebir uyar, node_modules klasörünü sıfırdan kurar ve kilit dosyası ile package.json uyuş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:test modü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 audit ile 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 ci kullanın.
  • Gizli bilgileri (API anahtarları) koda değil ortam değişkenlerine koyun ve .env dosyası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.