tsconfig.json Rehberi: compilerOptions, include, extends ve Önemli Ayarlar

tsc bu dosyayı nasıl bulur?

tsc komutunu dosya adı vermeden çalıştırdığınızda derleyici bulunduğunuz klasörden başlayarak üst klasörlere doğru bir tsconfig.json arar. -p (--project) ile belirli bir klasörü veya istediğiniz adda bir JSON dosyasını gösterebilirsiniz. Komut satırında dosya adı verirseniz tsconfig kullanılmaz; TypeScript 6.0'da bu durum, klasörde tsconfig varsa TS5112 hatasıyla açıkça bildirilir ve bilerek yok saymak için --ignoreConfig gerekir.

JavaScript projeleri aynı işi jsconfig.json ile yapabilir. Bu dosya neredeyse aynı çalışır, yalnızca JavaScript ile ilgili bazı ayarları varsayılan olarak açık getirir.

Dosyanın yapısı

{
  "extends": "./configs/temel.json",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "sourceMap": false
  },
  "include": ["src"],
  "exclude": ["src/**/*.test.ts"]
}

Dosyada yorum satırları ve sondaki virgüller kabul edilir; tsc --init çıktısı da bunları kullanır. compilerOptions bölümünü tamamen atlarsanız derleyicinin varsayılanları kullanılır. Hangi ayarların sonunda geçerli olduğunu görmek için tsc --showConfig en güvenilir yoldur: miras alınan ve sizin yazdığınız ayarları birleştirip yazdırır, eşleşen dosyaları da listeler.

include, exclude ve files

include, projeye girecek dosya ve klasörleri desenlerle seçer. Yollar tsconfig'in bulunduğu klasöre göre çözülür. Desenlerde * sıfır veya daha fazla karakteri (klasör ayırıcı hariç), ? tek karakteri, **/ ise her derinlikteki klasörü eşler. Son parçada uzantı veya joker karakter yoksa o bir klasör kabul edilir ve içindeki desteklenen uzantılı dosyalar alınır: varsayılan olarak .ts, .tsx ve .d.ts, allowJs açıksa .js ve .jsx de.

exclude yalnızca include'un bulduğu dosyalardan bazılarını çıkarır. Bu ayrım önemlidir: hariç tuttuğunuz bir dosya, başka bir dosyadan import edilirse, bir /// <reference yönergesiyle eklenirse veya files listesinde yer alırsa yine derlemeye girer. Yani exclude bir dosyanın projeye girmesini engelleyen bir mekanizma değildir.

files ise desen değil, tek tek dosya adı listesi alır. Listedeki bir dosya bulunamazsa hata oluşur. Az sayıda dosyası olan projelerde kullanışlıdır; geri kalan her durumda include daha pratiktir.

extends ile ayar paylaşmak

extends, başka bir yapılandırma dosyasının yolunu alır. Önce temel dosya yüklenir, ardından devralan dosyadaki ayarlar onun üzerine yazılır. Yol Node.js tarzı çözümleme kullanabildiği için npm paketlerinden de miras alabilirsiniz; resmî belgeler, farklı çalışma ortamları için hazır temel ayarlar sunan tsconfig/bases topluluk deposunu örnek gösterir.

// configs/temel.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "sourceMap": true
  }
}

Yukarıdaki ana tsconfig bu dosyadan miras alıp yalnızca sourceMap değerini değiştirdiğinde tsc --showConfig şu birleşik sonucu verdi:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "sourceMap": false,
        "rootDir": "./src",
        "outDir": "./dist"
    },
    "files": [
        "./src/merhaba.ts"
    ],
    "include": [
        "src"
    ],
    "exclude": [
        "src/**/*.test.ts"
    ]
}

• Göreli yollar, tanımlandıkları yapılandırma dosyasına göre çözülür.
• files, include ve exclude birleştirilmez; devralan dosyada yazılırsa temel dosyadakinin yerine geçer.
• Kalıtımdan hariç tutulan tek üst düzey alan references'tır.
• Dosyalar birbirini döngüsel olarak devralamaz.

En önemli compilerOptions ayarları

Yüzden fazla ayar var; günlük işin çoğunu aşağıdakiler belirler. Her birinin resmî açıklamasına adına tıklayarak ulaşabilirsiniz: strict, target, lib, module, moduleResolution, outDir, rootDir, types, noEmit, declaration, sourceMap, skipLibCheck, verbatimModuleSyntax, isolatedModules, noUncheckedIndexedAccess, paths.

Tablodaki konuların ayrıntıları için: strict modu, target ve lib ayarları, modül çözümleme, declaration dosyaları, paths ayarları.

outDir ve rootDir

outDir verilmezse .js dosyaları kaynak dosyaların yanına yazılır. Verilirse kaynak klasör yapısı, rootDir'e göre korunarak oraya taşınır. TypeScript 6.0 ile rootDir artık tahmin edilmiyor; tsconfig varken varsayılanı tsconfig'in bulunduğu klasör. Denememizde rootDir vermeden "outDir": "./dist" ve "include": ["src"] kullandığımızda derleyici şu hatayı verdi ve çıktıyı dist/src/merhaba.js konumuna yazdı:

tsconfig.json(3,5): error TS5011: The common source directory of 'tsconfig.json' is './src'.
The 'rootDir' setting must be explicitly set to this or another path to adjust your output's file layout.

"rootDir": "./src" eklediğimizde çıktı beklendiği gibi dist/merhaba.js oldu. rootDir derlemeye hangi dosyaların gireceğini değiştirmez; yalnızca çıktı düzenini belirler.

types

types, global kapsama eklenecek @types paketlerini belirler. TypeScript 6.0'dan önce varsayılan olarak görünür durumdaki bütün @types paketleri yükleniyordu; 6.0 ile varsayılan boş dizi oldu. Sürüm notlarına göre bu değişiklik birçok projede derleme süresini belirgin biçimde kısaltıyor, ama process veya describe gibi globalleri kullanan projelerin listeyi açıkça yazması gerekiyor. Bu ayar, import ettiğiniz paketlerin tiplerini etkilemez; yalnızca globalleri ve otomatik import önerilerini etkiler.

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

TypeScript 6.0 ile değişen varsayılanlar

İnternetteki tsconfig örneklerinin çoğu eski varsayılanlara göre yazıldı. 6.0 sürüm notlarındaki değişiklikler şöyle:

Bunlara ek olarak bazı ayarlar kullanımdan kaldırıldı: target: es5, downlevelIteration, moduleResolution için node (node10) ve classic, module için amd, umd ve systemjs, baseUrl, esModuleInterop ve allowSyntheticDefaultImports ayarlarının false yapılması, alwaysStrict: false. outFile ise tamamen kaldırıldı. Kullanımdan kaldırılmış bir ayar derlemeyi hatayla durdurur:

error TS5107: Option 'target=ES5' is deprecated and will stop functioning in TypeScript 7.0.
Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.

Sık yapılan hatalar

• exclude ile dosyayı tamamen dışarıda tuttuğunu sanmak: import edilen dosya yine derlenir.
• Komut satırında dosya adı verip tsconfig ayarlarını beklemek: Dosya adı verildiğinde tsconfig kullanılmaz; 6.0 bunu TS5112 ile bildirir.
• Eski örnekleri kopyalamak: "moduleResolution": "node", "target": "es5" veya baseUrl içeren şablonlar 6.0'da hata verir.
• extends ile include'un birleşeceğini sanmak: Devralan dosyada yazılan include temeldekinin yerine geçer.
• Ayarların sonucunu tahmin etmeye çalışmak: tsc --showConfig ile gerçek birleşik yapılandırmayı görün.

Sık Sorulan Sorular

tsconfig.json'da yorum yazabilir miyim?

Evet. TypeScript bu dosyada yorumlara ve sondaki virgüllere izin verir; tsc --init çıktısı da yorum satırları içerir. Dosyayı okuyan başka araçlar kullanıyorsanız onların da bu biçimi desteklediğinden emin olun.

Birden fazla tsconfig dosyası kullanabilir miyim?

Evet. Örneğin geliştirme ve derleme için ayrı dosyalar tutup ortak kısmı extends ile paylaşabilir, tsc -p tsconfig.build.json ile seçebilirsiniz. Birbirine bağlı birden çok proje için project references kullanılır.

Ayarların tam listesi nerede?

Resmî TSConfig Reference sayfası bütün ayarları açıklamalarıyla listeler. Editörler de tsconfig içinde otomatik tamamlama ve açıklama gösterir.

compilerOptions boşsa hangi ayarlar geçerli olur?

Derleyicinin varsayılanları. TypeScript 6.0'da bu, strict açık, module esnext ve target en yeni desteklenen ES sürümü demektir. Varsayılanlar sürümden sürüme değişebildiği için önemli ayarları açıkça yazmak daha öngörülebilirdir.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: TypeScript öğrenme rehberi · TypeScript kurulumu · strict modu · target ve lib · modül çözümleme · TypeScript 6.0 yenilikleri