tsconfig.json Nedir: Seçenekler, Varsayılanlar ve Örnekler

tsconfig.json, bir TypeScript projesinin yapılandırma dosyasıdır. tsc komutunu argümansız çalıştırdığınızda derleyici onu mevcut klasörde (sonra üst klasörlerde) arar, compilerOptions içindeki seçenekleri okur ve include ile listelenen dosyaları kontrol eder. Küçük ama eksiksiz bir örnek:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "nodenext",
        "strict": true,
        "rootDir": "./src",
        "outDir": "./dist"
    },
    "include": ["src"]
}

Bu yapılandırma src içindeki her TypeScript dosyasını, Node.js'in modül kurallarıyla ve tüm strict kontroller açıkken, ES2022 kodu olarak dist içindeki JavaScript'e derler. npx tsc --init her seçeneğe yorum eklenmiş daha uzun bir başlangıç dosyası oluşturur.

Dosya yorumlu JSON'dur: // yorumları, /* */ yorumları ve sondaki virgüllerin hepsi kabul edilir.

Önerilen Başlangıç Yapılandırması

Bir Node.js uygulaması veya betiği için:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",

        "target": "es2024",
        "lib": ["es2024"],
        "module": "nodenext",
        "types": ["node"],

        "strict": true,
        "noUncheckedIndexedAccess": true,
        "verbatimModuleSyntax": true,
        "skipLibCheck": true,
        "sourceMap": true
    },
    "include": ["src"]
}

Node.js tipleri için npm install --save-dev @types/node gerekir. module: "nodenext" ile package.json içindeki "type" alanı, bir .ts dosyasının ES modülü mü ("type": "module") yoksa CommonJS mi (npm init -y komutunun yazdığı "type": "commonjs") olduğunu belirler. import ve export kullanan yeni projeler için "type": "module" kullanın.

Vite, esbuild veya webpack gibi bir bundler'ın derlediği kodda JavaScript'i bundler yazar, tsc yalnızca kontrol eder:

{
    "compilerOptions": {
        "target": "es2022",
        "lib": ["es2022", "dom"],
        "module": "preserve",
        "noEmit": true,

        "strict": true,
        "noUncheckedIndexedAccess": true,
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "skipLibCheck": true,
        "jsx": "react-jsx"
    },
    "include": ["src"]
}

Framework başlangıç şablonları (Vite, Next.js, Angular) kendi tsconfig.json dosyalarını oluşturur. Onu değiştirmek yerine onunkinden başlayın.

Önemli Seçenekler

target ve lib

target, çıktının hangi JavaScript sürümünde çalışması gerektiğini söyler. Hedeften daha yeni sözdizimi yeniden yazılır: "target": "es2017" ile bir sınıf alanı veya ??= daha eski koda dönüştürülür. TypeScript 7'nin kabul ettiği en düşük hedef es2015 (es6) sürümüdür; es5 kaldırıldı.

target eksik çalışma zamanı API'lerini eklemez. Onları tanımlamak lib seçeneğinin, sağlamak ise bir polyfill'in işidir. lib, denetleyiciye hangi yerleşik nesnelerin ve metotların var olduğunu söyler. Varsayılanı target değerini izler ve tarayıcı DOM tiplerini de içerir; bu yüzden lib değerini kendiniz ayarlamadıkça bir Node.js projesinde bile document tip kontrolünden geçer. lib değerinizden daha yeni bir standarttaki bir metodu kullanmak derleme hatasıdır:

src/b.ts(1,24): error TS2550: Property 'toSorted' does not exist on type 'number[]'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2023' or later.

Bu dokümanlardaki çalıştırılabilir örnekler es2022 lib'ini kullanır; bu yüzden toSorted, Object.groupBy ve yeni Set metotları onlarda kullanılamaz.

module ve moduleResolution

Yeni kod için module seçeneğinin üç mantıklı değeri vardır:

• nodenext: Node.js'in çalıştırdığı kod için. Her dosya, tıpkı Node'un karar verdiği gibi, uzantısına (.mts, .cts) veya en yakın package.json dosyasındaki "type" alanına göre ESM ya da CommonJS'tir. ES modüllerindeki göreli import'lar bir dosya uzantısı ister ve kaynak .ts olsa bile .js olarak yazılır: import { add } from "./math.js". moduleResolution otomatik olarak ona uyar.
• preserve: bir bundler'ın işlediği kod için. Import'lar yazıldığı gibi bırakılır ve çözümleme, uzantısız import'lara izin veren bundler kurallarını kullanır.
• esnext: bundler çözümlemesiyle düz ES modülü çıktısı. module ayarlanmadığında varsayılan budur.

tsc --init yapılandırmasıyla alınan yaygın bir ilk hata, npm init -y komutunun "type": "commonjs" yazmasından kaynaklanır:

src/main.ts(1,10): error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'.

Dosya import kullanıyor ama package.json projenin CommonJS olduğunu söylüyor. "type" değerini "module" yapın. Import ve export'ları modüller sayfası ayrıntılı anlatıyor.

strict ve Kontrol Seçenekleri

"strict": true bir grup kontrolü birden açar: noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, strictBuiltinIteratorReturn, noImplicitThis ve useUnknownInCatchVariables. TypeScript 7'de varsayılandır ve buradaki her çalıştırılabilir örnekte açıktır. Strict mod için yazılmış kod, eksik olabilecek bir değeri kullanmadan önce daraltır:

function initials(fullName: string | undefined): string {
    if (fullName === undefined) {
        return "?";
    }
    return fullName
        .split(" ")
        .map((part) => part[0])
        .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(undefined));      // ?

Notasyon olmadan bir parametrenin tipi çıkarılamaz ve noImplicitAny bunu bildirir:

// This does not compile: noImplicitAny is part of strict.
function double(n) {
    return n * 2;
}

console.log(double(21));

index.ts(2,17): error TS7006: Parameter 'n' implicitly has an 'any' type.

strict her yararlı kontrolü içermez. Eklemeye değer iki tanesi noUncheckedIndexedAccess (bir dizi elemanı veya index signature araması T | undefined tipindedir) ve exactOptionalPropertyTypes (opsiyonel bir özellik açıkça undefined olarak atanamaz) seçenekleridir; tsc --init ikisini de açar. noUnusedLocals, noImplicitReturns ve noFallthroughCasesInSwitch gibi stil kontrolleri varsayılan olarak kapalıdır.

Hangi Dosyalar: include, exclude, rootDir, outDir

include veya files yoksa proje, klasördeki ve alt klasörlerindeki her .ts, .tsx ve .d.ts dosyasını içerir. node_modules her zaman dışarıda bırakılır. outDir de dışarıda bırakılır, ama yalnızca exclude ayarlamadığınız sürece: özel bir exclude listesi bu varsayılanın yerini alır, bu yüzden çıktı klasörünü ona ekleyin. include ve exclude glob kalıpları alır:

{
    "include": ["src", "scripts/**/*.ts"],
    "exclude": ["src/**/*.test.ts"]
}

exclude yalnızca include seçeneğinin bulduklarını filtreler. Dahil edilen başka bir dosyanın import ettiği bir dosya yine derlenir.

outDir çıktının gideceği yerdir, rootDir ise kaynak ağacının oraya yansıtılan kısmıdır: "rootDir": "./src" ile src/api/users.ts dosyası dist/api/users.js olur. İkisini de ayarlayın. rootDir varsayılan olarak tsconfig.json dosyasını içeren klasördür; bu yüzden kaynaklar src içindeyken yalnızca outDir ayarlarsanız TypeScript 7 şu hatayla durur:

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.

Çıktı Seçenekleri: noEmit, declaration, sourceMap

• "noEmit": true, tsc komutunu saf bir tip denetleyicisine dönüştürür. JavaScript'i başka bir araç (bir bundler, tsx, Node.js type stripping) ürettiğinde kullanın.
• "declaration": true her modül için bir .d.ts dosyası, yani kodsuz tipleri yazar. Kullanıcılarının tip alabilmesi için kütüphanelerin buna ihtiyacı vardır. declarationMap, .ts kaynağına "go to definition" için map dosyaları ekler.
• "sourceMap": true, debugger'ların ve stack trace'lerin .ts satırlarını göstermesi için .js.map dosyaları yazar.
• "noEmitOnError": true, tip hataları varken hiçbir şey yazmaz. Bu seçenek olmadan tsc hataları bildirir ve yine de JavaScript'i yazar.

types, esModuleInterop ve skipLibCheck

types, import olmadan global olarak yüklenen @types paketlerini listeler. TypeScript 7'nin varsayılanı boş bir listedir; bu yüzden npm install --save-dev @types/node sonrasında "types": ["node"] de eklersiniz, aksi halde process ve require bilinmez kalır (error TS2591: Cannot find name 'process'). Jest'in describe fonksiyonu gibi global fonksiyonlara sahip test çalıştırıcıları da aynı listeye girer.

esModuleInterop, CommonJS paketlerinin default import'larının çalışmasını sağlar (import express from "express"). TypeScript 7'de her zaman açıktır ve false yapmak hatadır.

skipLibCheck, bildirim dosyalarının tip kontrolünü atlar. Derlemeleri hızlandırır ve node_modules içindeki, düzeltemeyeceğiniz hataları önler; bedeli, iki kütüphanenin tipleri arasındaki çakışmaları fark etmemektir. Çoğu proje bunu açar.

extends ile Ayarları Paylaşmak

extends başka bir yapılandırmayı yükler ve bu dosyanın onun bazı kısımlarını geçersiz kılmasına izin verir:

{
    "extends": "./tsconfig.base.json",
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist"
    },
    "include": ["src"]
}

compilerOptions seçenek seçenek birleştirilir; include, exclude ve files ise bu dosya onları ayarlarsa temel dosyadakilerin yerini alır, birleştirilmez. Temel dosyadaki yollar temel dosyaya göre çözümlenir. extends bir paket de kabul eder: @tsconfig/bases projesi her ortam için bir tane yayınlar; örneğin npm install --save-dev @tsconfig/node24 ve ardından "extends": "@tsconfig/node24/tsconfig.json".

Tüm extends ve varsayılanlar uygulandıktan sonraki son ayarları görmek için şunu çalıştırın:

npx tsc --showConfig

TypeScript 7'de Kaldırılan Seçenekler

TypeScript 6 bu ayarları kullanımdan kaldırdı (deprecated), TypeScript 7 ise tamamen sildi. Hâlâ bunlardan birini kullanan bir yapılandırma error TS5108 veya TS5102 ile başarısız olur; örneğin Option 'baseUrl' has been removed. Please remove it from your configuration.

Bu sürümdeki diğer değişiklikleri, bu tablonun kapsamadığı yeni varsayılanlar dahil, TypeScript 7 sayfası listeliyor.