npm ve Build Tools

Yazılımın Tedarik Zinciri

Bir restoran açtığını düşün. Her yemeği sıfırdan mı yaparsın — unu öğütür, peyniri mayalar, ketçabı domateslerden mi hazırlarsın? Hayır — güvendiğin tedarikçilerden hazır malzeme alırsın. Ama hangi tedarikçiyi seçeceğini bilmen, malzeme listeni yönetmen ve mutfağını düzenlemen gerekir.

JavaScript ekosisteminde npm (Node Package Manager) o tedarikçi ağıdır. Milyonlarca hazır paket — date formatlama, HTTP istekleri, validasyon, UI bileşenleri — hepsi birkaç komutla projenize dahil olur. Ama bu paketleri doğru yönetmek, versiyonlamak ve production'a taşımak (bundling) ayrı bir beceridir. Bu derste npm'in derinliklerini, package.json'un sırlarını ve modern build tool'larını keşfedeceğiz.

package.json: Projenin Kimlik Kartı

Her Node.js/JavaScript projesi bir package.json dosyasıyla başlar. Bu dosya projenin kimliğini, bağımlılıklarını ve komutlarını tanımlar.

{
  "name": "my-awesome-app",
  "version": "1.2.3",
  "description": "Harika bir uygulama",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "type": "module",

  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "test": "jest",
    "test:watch": "jest --watch",
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix",
    "format": "prettier --write src/",
    "prepare": "husky"
  },

  "dependencies": {
    "axios": "^1.6.0",
    "zod": "^3.22.0",
    "date-fns": "^3.0.0"
  },

  "devDependencies": {
    "typescript": "^5.3.0",
    "vite": "^5.0.0",
    "jest": "^29.7.0",
    "eslint": "^9.0.0",
    "prettier": "^3.1.0",
    "@types/node": "^20.10.0"
  },

  "engines": {
    "node": ">=18.0.0"
  },

  "license": "MIT"
}

Önemli Alanlar Detaylı

{
  "name": "my-app",
  // ─ Paket adı. npm'e yayınlıyorsan benzersiz olmalı.
  // ─ Scope: @myorg/my-app (organizasyon paketi)

  "version": "1.2.3",
  // ─ SemVer formatında (aşağıda detaylı)

  "type": "module",
  // ─ "module" → ESM (.js dosyaları import/export kullanır)
  // ─ "commonjs" (veya belirtilmezse) → CJS (require/module.exports)
  // ─ 2025'te yeni projeler için "module" önerilir

  "main": "dist/index.js",
  // ─ CJS entry point (require ile yüklendiğinde)

  "module": "dist/index.mjs",
  // ─ ESM entry point (import ile yüklendiğinde)

  "types": "dist/index.d.ts",
  // ─ TypeScript tip tanım dosyası

  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "types": "./dist/utils.d.ts"
    }
  },
  // ─ Modern paket export tanımı — main/module'dan daha güçlü
  // ─ Subpath exports: import { helper } from "my-app/utils"

  "files": ["dist", "README.md"],
  // ─ npm'e yayınlarken hangi dosyalar dahil edilecek
  // ─ Gereksiz dosyalar (src/, test/) dahil olmaz

  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
  // ─ Minimum Node.js ve npm versiyonu
  // ─ Uyumsuz ortamda uyarı verir
}

dependencies vs devDependencies

Bu ayrım kritik — production'a ne gider, neye gerek yok?

# dependencies — Production'da GEREKLİ
npm install axios           # Uygulama çalışırken ihtiyaç var

# devDependencies — Sadece GELİŞTİRME sırasında gerekli
npm install -D jest         # Test çalıştırmak için
npm install -D typescript   # Derleme için
npm install -D eslint       # Kod kontrolü için

dependencies → Kullanıcının tarayıcısına/sunucuya gider
devDependencies → Sadece geliştiricinin bilgisayarında çalışır

Örnek:
├── axios          → API çağrısı yapıyor → dependency ✅
├── react          → UI oluşturuyor → dependency ✅
├── zod            → Validasyon yapıyor → dependency ✅
├── jest           → Test çalıştırıyor → devDependency ✅
├── typescript     → Derleme yapıyor → devDependency ✅
├── prettier       → Kod formatluyor → devDependency ✅
├── @types/node    → Tip tanımı → devDependency ✅
└── husky          → Git hook → devDependency ✅

peerDependencies ve optionalDependencies

{
  "peerDependencies": {
    "react": ">=18.0.0"
  },
  // ─ "Bu paketi kullanmak için react zaten yüklü olmalı"
  // ─ Kütüphane yazarken kullanılır (örn: React component kütüphanesi)
  // ─ Paket react'ı kendi yüklemez, projenin yüklemesini bekler

  "optionalDependencies": {
    "fsevents": "^2.3.0"
  }
  // ─ Kurulmazsa hata vermez, devam eder
  // ─ Platform-specific paketler için (fsevents: sadece macOS)
}

scripts: Komut Kısayolları

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "jest",
    "lint": "eslint src/",

    // Pre/post hook'ları — otomatik çalışır
    "prebuild": "npm run lint && npm run test",  // build'den ÖNCE
    "postbuild": "echo 'Build tamamlandı!'",      // build'den SONRA

    // Özel scriptler
    "db:migrate": "prisma migrate deploy",
    "db:seed": "ts-node prisma/seed.ts",
    "deploy": "npm run build && aws s3 sync dist/ s3://my-bucket",
    
    // Birden fazla komutu paralel çalıştır
    "dev:all": "concurrently \"npm run dev\" \"npm run test:watch\"",
    
    // Ortam değişkeni ile
    "build:prod": "NODE_ENV=production npm run build",
    "build:staging": "NODE_ENV=staging npm run build"
  }
}

# Script çalıştırma
npm run dev           # vite çalışır
npm run build         # prebuild → tsc && vite build → postbuild
npm test              # jest (test, start, stop için "run" gerekmez)
npm run lint          # eslint src/

# npx — paketi kurmadan çalıştır
npx create-vite@latest my-app    # Geçici olarak indirir, çalıştırır
npx tsc --init                    # Proje yüklü değilse geçici indirir
npx eslint --init                 # ESLint yapılandırma wizard'ı

💡 İpucu: npx paketi proje veya global olarak yüklü değilse geçici olarak indirir ve çalıştırır. Tek seferlik işlemler için idealdir — global kirliliği önler.

npm Temel Komutları

# === Paket Yönetimi ===
npm install                 # package.json'daki tüm paketleri kur
npm install axios           # Paket ekle (dependencies)
npm install -D jest         # Paket ekle (devDependencies)
npm install axios@1.5.0     # Belirli versiyon
npm install axios@latest    # En son versiyon

npm uninstall axios         # Paketi kaldır

npm update                  # Tüm paketleri güncelle (semver aralığında)
npm update axios            # Belirli paketi güncelle

npm outdated                # Güncel olmayan paketleri listele
npm list                    # Yüklü paketler ağacı
npm list --depth=0          # Sadece doğrudan bağımlılıklar

# === Güvenlik ===
npm audit                   # Güvenlik açıklarını tara
npm audit fix               # Otomatik düzeltmeyi dene
npm audit fix --force       # Breaking change yaparak düzelt (dikkatli!)

# === Bilgi ===
npm info axios              # Paket bilgisi (versiyonlar, bağımlılıklar)
npm search date             # npm registry'de ara
npm view axios versions     # Tüm versiyonları listele

# === CI/CD ===
npm ci                      # Clean install — lock dosyasına sadık
                            # node_modules'u siler ve sıfırdan kurar
                            # npm install'dan DAHA HIZLI ve daha tutarlı

# === Yayınlama (kütüphane yazarları için) ===
npm login                   # npm hesabına giriş
npm publish                 # Paketi yayınla
npm version patch           # 1.0.0 → 1.0.1
npm version minor           # 1.0.0 → 1.1.0
npm version major           # 1.0.0 → 2.0.0

Paket Yöneticileri: npm vs pnpm vs Yarn

npm tek seçenek değil. Alternatifleri bilmek iyi olur:

npm (Node Package Manager):
├── Node.js ile birlikte gelir
├── En yaygın, en çok kaynak
├── node_modules/ → flat yapı, hoisting
└── 2025'te npm v10+ — yeterince hızlı

pnpm (Performant npm):
├── Disk alanı tasarrufu (content-addressable store)
├── node_modules/ → symlink yapısı — daha hızlı, daha küçük
├── Phantom dependencies'i engeller
├── Monorepo desteği mükemmel (workspace protocol)
└── Büyük projelerde önerilen ✅

Yarn (Yet Another Resource Negotiator):
├── Facebook tarafından geliştirildi
├── Yarn Classic (v1) → npm benzeri
├── Yarn Berry (v3+) → Plug'n'Play (PnP), node_modules yok
├── Zero-install mümkün
└── PnP uyumluluk sorunları olabilir

# pnpm kullanımı (npm ile neredeyse aynı)
npm install -g pnpm

pnpm install             # npm install
pnpm add axios           # npm install axios
pnpm add -D jest         # npm install -D jest
pnpm remove axios        # npm uninstall axios
pnpm run dev             # npm run dev

# Performans karşılaştırması (yaklaşık):
# npm install  → 30s
# yarn install → 25s
# pnpm install → 15s (ilk kurulum), 5s (cache'den)

⚠️ Dikkat: Lock dosyaları farklıdır ve birlikte kullanılamaz:

• npm → package-lock.json

• pnpm → pnpm-lock.yaml

• Yarn → yarn.lock

Bir projedeki herkes aynı paket yöneticisini kullanmalıdır. .npmrc veya packageManager alanı ile zorunlu kılabilirsin.

Semantic Versioning (SemVer)

npm dünyasında paket versiyonları anlamlıdır — rastgele sayılar değil:

MAJOR.MINOR.PATCH
  1  .  2  .  3

MAJOR → Breaking change (uyumsuz değişiklik) — mevcut kodun kırılabilir
MINOR → Yeni özellik (geriye uyumlu) — mevcut kod çalışmaya devam eder
PATCH → Hata düzeltmesi — sadece bug fix, yeni özellik yok

Versiyon Aralıkları

package.json'daki ^ ve ~ karakterleri versiyon aralığı belirler:

{
  "dependencies": {
    "axios": "1.6.0",     // TAM bu versiyon — sabit
    "axios": "^1.6.0",    // >=1.6.0 ve <2.0.0 — minor ve patch güncellenir
    "axios": "~1.6.0",    // >=1.6.0 ve <1.7.0 — sadece patch güncellenir
    "axios": ">=1.5.0",   // 1.5.0 ve üstü — herhangi biri
    "axios": "*"           // Herhangi bir versiyon — TEHLİKELİ! ❌
  }
}

Pratikte ^ (caret) en yaygın ve önerilir — minor güncelleme genelde güvenlidir.

^ (caret) örnekleri:
^1.6.0 → 1.6.0, 1.6.5, 1.7.0, 1.9.9 ✅ | 2.0.0 ❌
^0.5.0 → 0.5.0, 0.5.5 ✅ | 0.6.0 ❌ (0.x'te minor = breaking!)
^0.0.3 → 0.0.3 ✅ | 0.0.4 ❌ (0.0.x'te patch = breaking!)

~ (tilde) örnekleri:
~1.6.0 → 1.6.0, 1.6.5 ✅ | 1.7.0 ❌
~0.5.0 → 0.5.0, 0.5.5 ✅ | 0.6.0 ❌

⚠️ Dikkat: 0.x.y versiyonlarında (pre-release), ^ davranışı farklıdır! ^0.5.0 sadece 0.5.x aralığını kapsar, 0.6.0'ı kapsamaz. Çünkü pre-release döneminde her minor versiyon breaking olabilir.

package-lock.json: Kesin Versiyon Kilidi

package.json'da ^1.6.0 yazıyorsa, bu 1.6.0, 1.6.5, 1.7.0, 1.9.9 olabilir. Aynı projeyi iki farklı bilgisayarda kurduğunda farklı versiyonlar gelebilir. Tutarsızlık!

package-lock.json bu sorunu çözer — her paketin tam versiyonunu ve bağımlılık ağacını kilitler:

# package-lock.json'u dikkate alarak KURULUm yap
npm ci        # ← CI/CD'de bunu kullan (clean install)

# package-lock.json'u GÜNCELLEyerek kurulum yap
npm install   # ← Geliştirme sırasında bunu kullan

⚠️ Dikkat: package-lock.json'u .gitignore'a EKLEME — repo'ya commit et! Bu dosya sayesinde tüm ekip aynı versiyonları kullanır. CI/CD'de npm ci kullanarak tutarlılığı garanti et.

Bundlers: Kodu Paketleme

Tarayıcılar yüzlerce .js dosyasını ayrı ayrı yükleyemez — yavaş olur. Bundler, tüm JavaScript dosyalarını (ve CSS, resim gibi varlıkları) tek veya birkaç dosyaya paketler. Ayrıca modern JavaScript'i eski tarayıcılar için dönüştürür, kodu küçültür (minify), kullanılmayan kodu atar (tree shake).

Analoji: Bir fabrikayı düşün. Hammaddeler (kaynak dosyalar) gelir, montaj hattında (bundler) işlenir, paketlenir ve sevkiyata (production'a) hazır hale getirilir. Gereksiz malzeme atılır (tree shaking), ürün küçültülür (minify), kalite kontrolden geçer.

Vite: Modern Standart

Vite (Fransızca "hızlı"), Evan You (Vue.js yaratıcısı) tarafından geliştirildi. İki modda çalışır:

1. Geliştirme: Native ES modules kullanır, bundleme yapmaz → anında başlar

2. Production: Rollup ile optimize bundle üretir

# Vite ile proje oluştur
npm create vite@latest my-app -- --template react-ts

# Mevcut projeye Vite ekle
npm install -D vite

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";

export default defineConfig({
  plugins: [react()],

  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@components": path.resolve(__dirname, "./src/components"),
      "@utils": path.resolve(__dirname, "./src/utils"),
    },
  },

  build: {
    outDir: "dist",
    sourcemap: true,
    rollupOptions: {
      output: {
        // Vendor chunk — kütüphaneleri ayır
        manualChunks: {
          vendor: ["react", "react-dom"],
          utils: ["date-fns", "lodash-es"],
        },
      },
    },
  },

  server: {
    port: 3000,
    proxy: {
      "/api": {
        target: "http://localhost:8080",
        changeOrigin: true,
      },
    },
  },

  // Ortam değişkenleri
  // .env dosyasında VITE_ prefix'li değişkenler client'ta kullanılabilir
  // VITE_API_URL=https://api.example.com
  // import.meta.env.VITE_API_URL
});

# Geliştirme sunucusu
npm run dev     # localhost:3000 — anında başlar (HMR ile)

# Production build
npm run build   # dist/ klasörüne optimize bundle üretir

# Build sonucunu önizle
npm run preview # dist/ klasörünü sunar

Vite'ın Neden Bu Kadar Hızlı?

Geleneksel bundler (webpack):
  Tüm dosyaları oku → Dependency graph oluştur → Bundle → Serve
  İlk başlatma: 5-30 saniye (proje boyutuna göre)

Vite (geliştirme modunda):
  Sadece istenen dosyayı oku → Native ESM ile serve et
  İlk başlatma: <1 saniye (proje boyutu farketmez!)

  ┌─────────┐    HTTP Request     ┌─────────┐
  │ Tarayıcı │ ──────────────────→ │  Vite   │
  │          │ ← /src/App.tsx     │ Server  │
  │          │   (sadece bu dosya) │         │
  └─────────┘                     └─────────┘
  
  Tarayıcı sadece ihtiyacı olan modülü ister
  Vite sadece o modülü dönüştürüp (esbuild ile) gönderir
  node_modules → pre-bundled (bir kez esbuild ile optimize)

esbuild: Süper Hızlı Bundler

esbuild, Go dilinde yazılmış ve webpack'ten 10-100x hızlı çalışan bir bundler. Vite zaten geliştirme modunda esbuild kullanır.

npm install -D esbuild

# Basit bundle
npx esbuild src/index.ts --bundle --outfile=dist/bundle.js --platform=browser

# Minified production bundle
npx esbuild src/index.ts \
  --bundle \
  --minify \
  --sourcemap \
  --target=es2020 \
  --outfile=dist/bundle.min.js

// esbuild.config.js — JavaScript API
import * as esbuild from "esbuild";

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ["es2020"],
  outdir: "dist",
  splitting: true,  // Code splitting
  format: "esm",
  // Kütüphaneler için external
  external: ["react", "react-dom"], // Bundle'a dahil etme
});

webpack: Eski ama Güçlü

webpack, 2012'den beri JavaScript ekosisteminin standart bundler'ıydı. Hâlâ birçok büyük projede kullanılır:

// webpack.config.js — basit örnek
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
  entry: "./src/index.ts",
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "[name].[contenthash].js",
    clean: true,
  },
  module: {
    rules: [
      { test: /\.tsx?$/, use: "ts-loader", exclude: /node_modules/ },
      { test: /\.css$/, use: ["style-loader", "css-loader"] },
      { test: /\.(png|jpg|gif)$/, type: "asset/resource" },
    ],
  },
  resolve: {
    extensions: [".ts", ".tsx", ".js"],
  },
  plugins: [
    new HtmlWebpackPlugin({ template: "./src/index.html" }),
  ],
  devServer: {
    port: 3000,
    hot: true,
  },
};

webpack vs Vite vs esbuild Karşılaştırma

💡 İpucu: 2025'te yeni proje başlıyorsan Vite seç. webpack sadece mevcut projeler veya çok özel ihtiyaçlar için gerekli. esbuild ise kütüphane geliştirme veya Vite'ın arkasında çalışan motor olarak kullanılır.

Tree Shaking: Kullanılmayan Kodu At

Tree shaking, kullanılmayan kodu final bundle'dan çıkaran optimizasyon tekniği. Bir ağacı salladığında kuru yapraklar düşer — kullanılmayan export'lar bundle'dan düşer.

// utils.js — 10 fonksiyon export ediyor
export function add(a, b) { return a + b; }
export function subtract(a, b) { return a - b; }
export function multiply(a, b) { return a * b; }
export function divide(a, b) { return a / b; }
export function power(a, b) { return a ** b; }
// ... 5 fonksiyon daha

// app.js — sadece 2'sini kullanıyor
import { add, multiply } from "./utils";

console.log(add(2, 3));
console.log(multiply(4, 5));

// Tree shaking sonrası: subtract, divide, power... bundle'a dahil OLMAZ
// Bundle boyutu küçülür!

Tree Shaking'in Çalışması İçin

// ✅ ESM (import/export) kullan — tree shaking çalışır
import { debounce } from "lodash-es"; // Sadece debounce gelir (~1KB)

// ❌ CommonJS (require) kullanma — tree shaking ÇALIŞMAZ
const _ = require("lodash"); // Tüm lodash gelir (~70KB)
const { debounce } = require("lodash"); // Yine tüm lodash gelir!

// ❌ Namespace import — dikkatli ol
import * as utils from "./utils"; // Tüm export'lar dahil OLABILIR
// (bundler akıllıysa kullanılmayanları atar ama garanti değil)

// ✅ Named export kullan — tree shaking kolay
export function helper() {}
export function utils() {}
// Kullanılmayan otomatik atılır

// ⚠️ Default export — tree shaking zor olabilir
export default {
  helper() {},
  utils() {},
};
// Nesne olarak export edildiğinde bundler hangi property'nin
// kullanıldığını anlamakta zorlanabilir

Side Effects ve sideEffects Flag

// package.json — kütüphane geliştiricileri için
{
  "sideEffects": false
  // "Bu paketteki hiçbir modülün import edilmekle yan etkisi yoktur"
  // Bundler güvenle kullanılmayanları atabilir
}

// Veya spesifik dosyaları belirt
{
  "sideEffects": [
    "*.css",          // CSS import'ları yan etkili (DOM'a eklenir)
    "./src/polyfills.js" // Polyfill import'u yan etkili
  ]
}

// Yan etki (side effect) nedir?
// ✅ Yan etkisiz — import edilmezse hiçbir şey olmaz
export function add(a, b) { return a + b; }

// ❌ Yan etkili — import edildiğinde bir şey olur
console.log("Bu modül yüklendi!"); // Sadece import etmek bile çalıştırır
window.myGlobal = true;             // Global state değiştiriyor
Array.prototype.myMethod = () => {}; // Prototype kirletme

Bundle Analizi

Bundle'ının ne kadar büyük olduğunu ve hangi kütüphanenin ne kadar yer kapladığını görmek kritik:

# Vite ile bundle analizi
npm install -D rollup-plugin-visualizer

// vite.config.ts
import { visualizer } from "rollup-plugin-visualizer";

export default defineConfig({
  plugins: [
    visualizer({
      open: true,          // Tarayıcıda aç
      filename: "stats.html",
      gzipSize: true,
    }),
  ],
});

# Build ve analiz
npm run build
# stats.html açılır — hangi paket ne kadar yer kaplıyor gösterir

Bundle Boyutu Kontrolü

# Paket boyutunu kontrol et (yüklemeden)
npx bundlephobia axios
# axios@1.6.0 — minified: 13.4kB, gzipped: 4.7kB

# Alternatifleri karşılaştır
# axios (4.7kB gzip) vs ky (3.1kB gzip) vs got (sadece Node.js)
# moment.js (72kB gzip) vs date-fns (tree-shakeable, ~3KB kullanılan)
# lodash (71kB gzip) vs lodash-es (tree-shakeable)

💡 İpucu: [bundlephobia.com](https://bundlephobia.com) ile yüklemeden önce paket boyutunu kontrol et. 100KB'lık bir "date picker" kütüphanesi, 5KB'lık alternatifi varken gereksiz şişkinlik.

Monorepo ve Workspaces

Büyük projelerde birden fazla paket/uygulama aynı repo'da yönetilir. npm workspaces bunu kolaylaştırır:

// package.json (kök)
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

my-monorepo/
├── package.json          ← Kök (workspaces tanımı)
├── packages/
│   ├── shared-utils/     ← Ortak yardımcı fonksiyonlar
│   │   └── package.json
│   └── ui-components/    ← Paylaşılan UI bileşenleri
│       └── package.json
├── apps/
│   ├── web/              ← Frontend uygulaması
│   │   └── package.json
│   └── api/              ← Backend API
│       └── package.json

# Tüm workspace'leri kur
npm install

# Belirli workspace'te script çalıştır
npm run dev -w apps/web
npm run build -w packages/shared-utils

# Tüm workspace'lerde test çalıştır
npm run test --workspaces

# Workspace'ler arası bağımlılık
# apps/web/package.json:
# "dependencies": { "@my-monorepo/shared-utils": "workspace:*" }

💡 İpucu: Büyük monorepo'larda Turborepo veya Nx kullanarak build cache, parallel execution ve incremental build yapabilirsin. Özellikle CI/CD süresini dramatik olarak azaltır.

Pratik: Modern Proje Kurulumu

Sıfırdan modern bir TypeScript projesi kuralım:

# 1. Vite + TypeScript + React
npm create vite@latest my-app -- --template react-ts
cd my-app

# 2. Bağımlılıklar
npm install axios zod date-fns

# 3. Dev bağımlılıklar
npm install -D eslint @eslint/js typescript-eslint eslint-config-prettier
npm install -D prettier
npm install -D husky lint-staged
npm install -D @testing-library/react @testing-library/jest-dom vitest

# 4. Husky kurulumu
npx husky init
echo 'npx lint-staged' > .husky/pre-commit

# 5. Scripts

// package.json
{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "test:coverage": "vitest run --coverage",
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix",
    "format": "prettier --write src/",
    "type-check": "tsc --noEmit",
    "quality": "npm run lint && npm run format:check && npm run type-check"
  },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

# 6. Geliştirmeye başla!
npm run dev

Yaygın Hatalar

1. node_modules'u Commit Etmek

# .gitignore — MUTLAKA ekle
node_modules/
dist/
coverage/
.env
.env.local
*.log

2. dependencies ve devDependencies Karıştırmak

# ❌ Jest'i dependency olarak yüklemek
npm install jest  # Production bundle'a dahil olur!

# ✅ Doğru
npm install -D jest  # Sadece geliştirme sırasında

3. package-lock.json'u Yoksaymak

# ❌ CI/CD'de npm install kullanmak — farklı versiyonlar gelebilir
npm install

# ✅ CI/CD'de npm ci kullan — lock dosyasına sadık kalır, daha hızlı
npm ci

4. Paket Boyutunu Kontrol Etmemek

# ❌ Düşünmeden paket eklemek
npm install moment  # 72KB gzip — sadece tarih formatı için çok büyük

# ✅ Alternatif araştır
npm install date-fns  # Tree-shakeable, kullandığın kadar (~3KB)
# veya
npm install dayjs     # 2KB gzip — moment API uyumlu

5. npm audit Uyarılarını Yoksaymak

# ❌ Güvenlik açıklarını görmezden gelme
npm install  # "6 vulnerabilities found" — yoksayma!

# ✅ Düzenli olarak kontrol et
npm audit
npm audit fix
# Otomatik düzeltemiyorsa: bağımlılığı güncelle veya alternatif bul

Özet

• package.json: Projenin kimlik kartı — bağımlılıklar, scripts, metadata. dependencies (production) ve devDependencies (geliştirme) ayrımını doğru yap. "type": "module" ile ESM kullan.

• SemVer: MAJOR.MINOR.PATCH. ^ (caret) minor+patch günceller, ~ (tilde) sadece patch. package-lock.json ile versiyonları kilitle. CI/CD'de npm ci kullan.

• npm Alternatifleri: pnpm (hız + disk tasarrufu), Yarn (PnP). Ekipte herkes aynı paket yöneticisini kullanmalı.

• Bundlers: Vite (modern standart, hızlı dev server, Rollup build), esbuild (süper hızlı, minimal), webpack (eski ama geniş ekosistem). Yeni projede Vite seç.

• Tree Shaking: ESM import/export kullan, kullanılmayan kod otomatik atılır. CommonJS'te çalışmaz. sideEffects: false ile bundler'a yardım et.

• Bundle Analizi: rollup-plugin-visualizer ile görselleştir. bundlephobia.com ile yüklemeden önce kontrol et. Paket boyutunu düzenli izle.

• Monorepo: npm workspaces ile birden fazla paketi tek repo'da yönet. Turborepo/Nx ile build performansını artır.