tsconfig.json Kapsamlı Rehberi: Her Seçenek Açıklamalı

tsconfig.json Kapsamlı Rehberi: Her Seçenek Açıklamalı

tsconfig.json, TypeScript derleyicisinin davranışını belirleyen yapılandırma dosyasıdır. Doğru yapılandırma, projenizin kalitesini ve geliştirici deneyimini doğrudan etkiler. Bu yazıda tsconfig.json'ın en önemli seçeneklerini kategorilere ayırarak detaylı bir şekilde açıklayacağız.

tsconfig.json Oluşturma

# Varsayılan tsconfig oluşturma
npx tsc --init

# Önerilen başlangıç yapılandırması
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Target ve Module Seçenekleri

{
  "compilerOptions": {
    // target: Derleme çıktısının JavaScript sürümü
    // ES5, ES6/ES2015, ES2016-ES2023, ESNext
    "target": "ES2022",

    // module: Kullanılacak modül sistemi
    // commonjs, es2015, es2020, es2022, esnext, node16, nodenext
    "module": "ESNext",

    // moduleResolution: Modüllerin nasıl bulunacağı
    // classic, node, node16, nodenext, bundler
    "moduleResolution": "bundler",

    // lib: Dahil edilecek tip tanım kütüphaneleri
    "lib": ["ES2022", "DOM", "DOM.Iterable"],

    // Diğer modül seçenekleri
    "esModuleInterop": true,    // CommonJS/ESM uyumluluğu
    "allowImportingTsExtensions": false,
    "resolveJsonModule": true,  // JSON dosyalarını import etme
    "isolatedModules": true     // Her dosyanın bağımsız derlenmesi
  }
}

Strict Mode Seçenekleri

{
  "compilerOptions": {
    // strict: true tüm strict seçenekleri etkinleştirir
    "strict": true,

    // strict: true şunları açar:
    "noImplicitAny": true,           // Örtük any kullanımını yasaklar
    "strictNullChecks": true,        // null/undefined kontrolünü zorunlu kılar
    "strictFunctionTypes": true,     // Fonksiyon parametreleri contravariant
    "strictBindCallApply": true,     // bind/call/apply tip kontrolü
    "strictPropertyInitialization": true, // Class özelliklerinin init kontrolü
    "noImplicitThis": true,          // Örtük this kullanımını yasaklar
    "useUnknownInCatchVariables": true,  // catch(e) => e: unknown
    "alwaysStrict": true,            // "use strict" ekler

    // Ek kontroller (strict'te dahil değil)
    "noUnusedLocals": true,          // Kullanılmayan değişken uyarısı
    "noUnusedParameters": true,      // Kullanılmayan parametre uyarısı
    "noImplicitReturns": true,       // Tüm dalların dönüş yapmasını zorunlu kılar
    "noFallthroughCasesInSwitch": true, // Switch'te break zorunluluğu
    "noUncheckedIndexedAccess": true,   // Index erişimde undefined kontrolü
    "exactOptionalPropertyTypes": true  // Opsiyonel özellik hassasiyeti
  }
}

Output Seçenekleri

{
  "compilerOptions": {
    "outDir": "./dist",              // Çıktı dizini
    "rootDir": "./src",              // Kaynak dizini
    "declaration": true,             // .d.ts dosyaları oluştur
    "declarationMap": true,          // .d.ts.map dosyaları
    "sourceMap": true,               // .js.map dosyaları (debug)
    "inlineSourceMap": false,        // Inline source map
    "removeComments": false,         // Yorumları kaldır
    "noEmit": false,                 // Çıktı dosyası oluşturma
    "emitDeclarationOnly": false,    // Sadece .d.ts oluştur
    "importHelpers": true,           // tslib'den helper import et
    "downlevelIteration": true,      // ES5'e iteration desteği
    "preserveConstEnums": false      // const enum'ları koru
  }
}

Path Mapping ve Project References

// Path alias yapılandırması
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["./*"],
      "@components/*": ["./components/*"],
      "@hooks/*": ["./hooks/*"],
      "@services/*": ["./services/*"],
      "@utils/*": ["./utils/*"],
      "@types/*": ["./types/*"]
    }
  }
}

// Project references (monorepo için)
// tsconfig.json (root)
{
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/frontend" },
    { "path": "./packages/backend" }
  ],
  "files": [],
  "compilerOptions": {
    "composite": true
  }
}

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

// packages/frontend/tsconfig.json
{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "../shared" }
  ]
}

Proje Tiplerine Göre Önerilen Yapılandırmalar

// React + Vite projesi
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true
  },
  "include": ["src"]
}

// Node.js (ES Modules) projesi
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Sonuç

tsconfig.json, TypeScript projenizin kalitesini belirleyen kritik bir dosyadır. Strict mode'u etkinleştirmek, doğru module resolution stratejisini seçmek ve path alias'ları yapılandırmak, üretken bir geliştirme ortamı için vazgeçilmezdir. Projenizin türüne göre uygun yapılandırmayı seçerek başlayın ve ihtiyaçlarınıza göre özelleştirin.

Kaynaklar

• TSConfig Reference
• Project References
• TSConfig Bases