12. TypeScript’de tsconfig Ayarları

Bu makalemizde, TypeScript projelerimizin yapılandırma ayarlarını belirleyen ve projenin derlenmesi için kullanılan derleyici ayarlarını yapılandırmamızı sağlayan “tsconfig” dosyasının nasıl oluşturulduğunu görecek, başlıca ayarlarını inceleyecek ve projelerimizde kullanılabilecek örnek birer tsconfig.json dosyası oluşturacağız.

“tsconfig.json” Nedir ve Nasıl Oluşturulur?

TypeScript serisindeki makalelerimizde pek çok kez “*.ts” uzantılı dosyalara yazdığımız kodları “tsc” komutunu kullanarak, yazdığımız kodla aynı işleve sahip “*.js” uzantılı JavaScript dosyalarının oluşturulmasını sağladık. “tsc” komutu ile gerçekleştirdiğimiz bu işleme “derleme” ismi verilir. Derleme sırasında “tsc” komutu pek çok ayarı varsayılan hali ile kabul ederek derleme işlemini gerçekleştirir. Çoğu zaman varsayılan ayarlar projemize uymaz ve bazı ayarları değiştirmek isteriz. Bu ayarları değiştireceğimiz, gerekli konfigürasyon işlemlerini yapabileceğimiz dosya, projemizin kök dizininde bulunan “tsconfig.json” isimli dosyadır.

Ben bu makaleyi yazdığım an itibariyle “tsconfig.json” dosyasında değişiklik yapabileceğimiz ayarların sayısı 194‘dü. Neyse ki genelde çok azı haricinde bu ayarların büyük çoğunluğuna dokunmak zorunda kalmayız ve “tsconfig.json” dosyasının içerisine sadece değiştirmek istediğimiz ayarları yazarız. Bu makalede, değiştirmek isteyebileceğimiz ayarların üzerinden geçeceğiz.

Elbette öncelikle bir dosyaya ihtiyacımız var. “tsconfig.json” dosyamızı oluşturmak için temelde üç seçeneğimiz var.

1. Başka bir projede önceden kullandığımız bir “tsconfig.json” dosyasını yeni projemize kopyalayıp kullanabiliriz.
2. Projemizin kök dizininde boş bir metin belgesi oluşturup ismini “tsconfig.json” olarak değiştirip, içeriğine değiştirmek istediğimiz ayarları yazabiliriz.
3. Projemizin kök dizininde “tsc –init” komutunu çalıştırarak varsayılan ayarlar ile yeni bir “tsconfig.json” dosyasının oluşturulmasını sağlayabiliriz.

Genelde ilk seçenekle devam edecek olsak da, üçüncü yöntemin bir avantajı, oluşturulacak dosyanın içerisinde yüzden fazla varsayılan ayar ve yanında yorum satırı olarak açıklamalar bulunmasıdır.

Birazdan en çok ihtiyaç duyulan ayarlara göz atacağız ancak tüm ayarlar için bir referansa ihtiyacınız varsa, bu bilgiye resmi sitesi üzerinden ulaşabilirsiniz.

“compilerOptions” Seçenekleri

Öncelikle en geniş bölüm olan “compilerOptions” bölümünde kullanılan en yaygın ayarlara bir göz atalım. Makalenin sonunda örnek dosyalar oluşturacağız ama muhtemel seçenekleri bilmekte fayda var.

• target: Derlenen JavaScript kodunda hangi ECMAScript sürümünün hedefleneceğini belirler. Örneğin es5, es6, es2015, es2016, es2017, es2018, es2019, es2020 ve esnext gibi değerler kullanılabilir. Eğer Browser üzerinde çalışan bir uygulama yazıyorsak, tüm tarayıcıların desteklediği bir sürümü seçmek mantıklı olabilir ancak node.js üzerinde sunucuda çalışan bir uygulama yazıyorsak son versiyonu seçmemizde bir sıkıntı yoktur. Burada unutmayalım ki, ne kadar eski bir versiyon seçersek, modern komutlar kullanılamayacağından aynı fonksiyonaliteyi oluşturmak için gereken JavaScript çıktısı o kadar uzun ver karmaşık olacaktır.
• module: Derlenen JavaScript kodunun hangi modül yöntemi ile oluşturulacağını belirler. Örneğin commonjs, amd, es6, system, umd ve none gibi değerler kullanılabilir.
• outDir: Derlenen JavaScript kodunun hangi klasöre kaydedileceğini belirler (Her ne kadar derlenen JavaScript dosyalarını başka bir klasöre koymak paketleme sırasında kolaylık sağlayacak gibi gözükse de, özellikle WebStorm kullananlar için bu dosyaları TypeScript dosyalarının yanında bırakmak ve paketleme için ayrı bir npm Script’i çalıştırmanın daha pratik olduğunu tecrübe ettim).
• sourceMap: Derlenen JavaScript kodunun yanında kaynak haritalarının oluşturulup oluşturulmayacağını belirler. Kaynak haritaları debug işlemi için gereklidir.
• strict: TypeScript dosyalarının hangi derleme seçeneklerine göre doğrulanacağını belirler. Bu ayar, genel olarak projenin daha güvenli ve hatasız olmasını sağlar. “strict” ayarı direk “true” olarak ayarlanabileceği gibi birçok alt seçenek ile de kullanılabilir:
  • noImplicitAny: Belirsiz bir türü olan değişkenler için uyarı verir.
  • noImplicitThis: this anahtar kelimesi için uyarı verir.
  • alwaysStrict: Her dosyada “use strict” kullanımını zorlar.
  • strictFunctionTypes: Fonksiyon türlerinde esneklik kısıtlamaları getirir.
  • strictNullChecks: null veya undefined değerlerinin kullanımını kısıtlar.
  • strictBindCallApply: bind, call, ve apply yöntemlerinde yanlış kullanımı engeller.
  • strictPropertyInitialization: Sınıf özelliklerinin başlatılmasını zorlar.
• esModuleInterop: CommonJS modülleri ile ES modülleri arasındaki farklılıkları düzeltmek için import ve export ifadelerinde uygun düzenlemeler yapar.
• declaration: Derlenen JavaScript kodunun yanı sıra, deklarasyon dosyalarının da üretilip üretilmeyeceğini belirler (Deklarasyon dosyalarının ne kadar önemli olduğunu modüller ile ilgili makalemizde işlemiştik).
• declarationDir: Oluşturulan deklarasyon dosyalarının hangi klasöre kaydedileceğini belirler.
• noUnusedParameters: Kullanılmayan fonksiyon parametrelerini tespit eder ve uyarı verir.
• noImplicitReturns: Bütün fonksiyonların return ifadesi ile sonuçlanması gerektiğini kontrol eder.
• noFallthroughCasesInSwitch: switch ifadelerinde break ifadesinin kullanımını zorlar.
• noUncheckedIndexedAccess: Dizi erişimlerinde olası undefined veya null değerleri için uyarı verir.
• noImplicitOverride: Bir sınıfta ezilmemiş bir üyenin kullanımını engeller.
• noPropertyAccessFromIndexSignature: İndeks imzalarının özellik erişimine kullanılmasını engeller.
• removeComments: Yorum satırlarının ve meta verilerin derlenen JavaScript kodundan kaldırılmasını sağlar.
• baseUrl: import ve require ifadelerindeki başvuru yollarının temel dizinini belirler.
• paths: import ve require ifadelerindeki başvuru yollarını yeniden tanımlamak için kullanılır.
• lib: TypeScript tarafından sağlanan ve projede kullanılacak JavaScript kütüphanelerinin belirtilmesini sağlar.
• typeRoots: Proje kapsamında kullanılacak tanımlama dosyalarının bulunacağı klasörleri belirler.
• types: Proje kapsamında kullanılacak tür tanımlama dosyalarını belirler.

Aşağıda bu bölüm için özelleştirilmiş basit bir örnek görüyoruz.

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "sourceMap": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "removeComments": true,
    "noUnusedParameters": true,
    "declaration": true
  }
}

“include” ve “exclude” Seçenekleri

“include” ve “exclude” seçenekleri TypeScript tarafından hangi dosyaların derleneceğini belirlemek için kullanılır. “include” seçeneği, derlenmesi gereken dosyaların bir listesini içerir ve “*” gibi wildcard şablonlar kullanılabilir. Bu seçeneği kullanarak, derlenmesi gereken dosyaların hangi dizinlerde olduğunu belirtebiliriz. “exclude” seçeneği ise görmezden gelinmesi gereken dosyaların bir listesini içerir ve yine “*” gibi wildcard şablonlar kullanılabilir. Bu seçeneği kullanarak, derlenmesi gerekmeyen dosyaların hangi dizinlerde olduğunu belirtebiliriz.

Eğer bu iki seçeneğe hiçbir değer atamazsak, varsayılan değer olarak “include” seçeneği, projenin kök dizinindeki tüm “.ts“, “.tsx“, “.d.ts” ve “.js” dosyalarını içerecek şekilde ayarlanır. “exclude” seçeneği ise varsayılan olarak “node_modules“, “bower_components“, “jspm_packages” ve “outDir” dizinlerindeki tüm dosyaları derleme sürecinden çıkarır. Bu varsayılan ayarlar, birçok proje için yeterli olabilir ancak proje ihtiyaçlarına göre özelleştirilebilir.

Aşağıda bu bölüm için özelleştirilmiş basit bir örnek görüyoruz.

{
  "include": [
    "src/**/*.ts",
    "lib/**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "bower_components"
  ]
}

“extends” Seçeneği

“extends” seçeneği, bir “tsconfig.json” dosyasının diğer bir “tsconfig.json” dosyasından ayarları miras almasını sağlayan bir seçenektir. Bu seçenek, büyük ölçekli projelerde farklı konfigürasyonların oluşturulmasını ve tekrarlanan kod yazımının önlenmesini sağlar.

Örneğin, bir proje, belirli bir “tsconfig.json” dosyası içinde belirli bir “compilerOptions” ayarlarını gerektirebilir. Bu ayarlar, proje boyunca birçok alt proje veya modül tarafından kullanılabilir. Bu durumda, her bir alt proje veya modül için aynı ayarları yeniden tanımlamak yerine, “tsconfig.json” dosyalarını birleştirebilir ve extends seçeneği ile birbirlerine referans verebiliriz.

Aşağıda bu yapıyı kullanan iki config dosyası bulunuyor, inceleyelim.

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true
  },
  "include": [
    "src/**/*"
  ]
}

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist"
  }
}

Yukarıdaki örnekte, “tsconfig.json” dosyası, “tsconfig.base.json” dosyasındaki “compilerOptions” ayarlarını miras alır ve “outDir” ayarını ekler. Bu şekilde, “tsconfig.json” dosyasındaki ayarlar, “tsconfig.base.json” dosyasındaki ayarlarla birleştirilir. Bu yöntem, büyük ölçekli projelerde ayarların yönetimini kolaylaştırır.

“typeAcquisition” Seçeneği

“typeAcquisition” seçeneği, TypeScript derleyicisinin, tanımlama dosyalarını otomatik olarak indirme veya kurma şeklinde çalışmasını sağlayan bir seçenektir. Bu seçenek, proje geliştiricilerinin tanımlama dosyalarını manuel olarak yüklemek veya yapılandırmak zorunda kalmamasını sağlar.

“typeAcquisition” seçeneği, “enable” ve “include” şeklinde iki alt seçenek içerir. “enable” seçeneği, tanımlama dosyalarının otomatik olarak yüklenmesini veya kurulmasını etkinleştirir. “include” seçeneği ise, hangi paketlerin veya modüllerin tanımlama dosyalarının yüklenmesi veya kurulması gerektiğini işaret eder.

Aşağıdaki örnek, “typeAcquisition” seçeneği ile “lodash” paketinin tanımlama dosyasının otomatik olarak indirilmesini sağlamaktadır.

{
  "compilerOptions": {
    "target": "es6",
    "module": "es6"
  },
  "typeAcquisition": {
    "enable": true,
    "include": [
      "lodash"
    ]
  }
}

“typeAcquisition” seçeneği, “@types” kütüphanesi gibi tanımlama dosyalarının otomatik olarak indirilmesi veya kurulmasına da olanak tanır. Bu seçenek, tanımlama dosyalarının yönetimini kolaylaştırır ve geliştirme sürecini hızlandırır.

“watch” Modunda Çalıştırmak

Normalde Visual Studio Code veya WebStorm gibi IDE’leri kullandığımız taktirde, kaynak kodlarda yaptığımız değişiklik sonrasında derleme işlemi otomatik olarak tekrarlanır. Ancak not defteri veya doğrudan terminal gibi bir ortamlarda kod yazmak zorunda kalırsak, “watch” modunu etkinleştirerek değişiklik sonrasında otomatik derleme işleminin gerçekleştirilmesini sağlayabiliriz.

“watch” modu, terminalde “tsc -w” komutu ile çalıştırılabilir. Ayrıca, “tsconfig.json” dosyasında da watch modu etkinleştirilebilir. “tsconfig.json” dosyasında “watch” modunu etkinleştirmek için, “compilerOptions” nesnesine “watch” seçeneği eklenir ve seçeneğin değeri “true” olarak ayarlanır.

{
  "compilerOptions": {
    "target": "es6",
    "module": "es6",
    "watch": true
  },
  "include": [
    "src/**/*"
  ]
}

“tsconfig.json” Dosyası Örnekleri

Gelelim projelerimizde kullanabileceğimiz genel geçer birer “tsconfig.json” dosyası oluşturmaya. Elbette her projenin kendine göre ihtiyaçları ve özelleştirilmiş konfigürasyonları olabilir. Ancak şablon olarak kullanabileceğimiz bir konfigürasyon dosyası işimizi kolaylaştıracaktır.

Geliştireceğimiz projelerin tipleri her ne kadar çok farklı çeşitte olabilse de, ihtiyacımız olan “tsconfig.json” dosyalarını iki kategoriye ayırmamız mümkündür.

1. Angular, React, Vue ve benzeri Framework’ler ile tarayıcı üzerinde çalışması gereken uygulamalar
2. Node.js ile sunucu üzerinde çalışması gereken uygulamalar

Tarayıcı üzerinde çalışması gereken uygulamalar için “target” seçeneğinin, mobil dahil geniş tarayıcı yelpazesinde desteklenmesi önemlidir. Bu sebeple an itibariyle “es6” kabul edilebilir bir seçenek olabilir. Aşağıdaki seçenekler böyle bir uygulama için güzel bir başlangıç olabilir (“outDir” seçeneğini özellikle eklemedim, tercih edenler ekleyebilir).

{
  "compilerOptions": {
    "target": "es6",
    "module": "es6",
    "moduleResolution": "node",
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "removeComments": true,
    "noUnusedParameters": true,
    "declaration": true,
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ]
  },
  "include": [
    "**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

Sunucu üzerinde çalışan uygulamalar için durum biraz daha farklıdır. Böyle ortamlarda kurulu olan node.js versiyonunu biliriz ve uyum sorunumuz yoktur. Bu sebeple “target” seçeneğinde elimiz daha özgürdür. Aşağıdaki seçenekler böyle bir uygulama için güzel bir başlangıç olabilir (“outDir” seçeneğini özellikle eklemedim, tercih edenler ekleyebilir).

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "resolveJsonModule": true,
    "removeComments": true,
    "noUnusedParameters": true,
    "declaration": true,
    "lib": [
      "es2020",
      "esnext.asynciterable",
      "dom"
    ]
  },
  "include": [
    "**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

Böylece hem tsconfig ayarlarının hem de TypeScript serimizin sonuna geldik. Farklı bir seride tekrar görüşme üzere,

Herkese iyi çalışmalar…