TypeScript 6.0 Yenilikleri: Değişen Varsayılanlar, Kalkan Seçenekler ve Geçiş

Değişen varsayılanlar özet tablosu

Sürüm notlarına göre aşağıdaki seçeneklerin varsayılan değeri 6.0 ile değişti. Projeniz bu değerlere güveniyorsa, eski davranışı korumak için değeri tsconfig.json içinde açıkça yazmanız yeterli.

strict değişikliğini hiçbir bayrak vermeden doğrulayabilirsiniz. Aşağıdaki dosya tsc 6.0 ile ek seçenek olmadan derlendiğinde noImplicitAny hatası verir, çünkü bu kontrol strict ailesinin parçasıdır:

// tsc --noEmit topla.ts   (hiçbir bayrak yok)
function topla(a, b) {
  return a + b;
}
// TS7006: Parameter 'a' implicitly has an 'any' type.
// TS7006: Parameter 'b' implicitly has an 'any' type.

Strict ailesinin hangi kontrolleri kapsadığını TypeScript strict modu yazısında ayrıntılı olarak bulabilirsiniz.

Birçok projeyi etkileyen iki değişiklik: types ve rootDir

types artık boş dizi

5.9 ve öncesinde types belirtilmediğinde TypeScript node_modules/@types altındaki tüm paketleri global kapsama yüklerdi. Sürüm notları, bunun büyük depolarda yüzlerce gereksiz bildirim dosyası demek olduğunu ve types değerini doğru ayarlayan projelerde derleme süresinin yüzde 20 ile 50 arasında kısaldığını belirtiyor. 6.0 ile varsayılan [] oldu. Sonuç olarak process, fs veya test çatısının describe gibi globalleri artık kendiliğinden gelmez:

console.log(process.version);
// TS2591: Cannot find name 'process'. Do you need to install type definitions
// for node? Try `npm i --save-dev @types/node` and then add 'node' to the
// types field in your tsconfig.

Çözüm, ihtiyaç duyduğunuz paketleri açıkça listelemektir. Eski "hepsini yükle" davranışı "*" ile geri gelir, ama sürüm notları performans ve öngörülebilirlik için açık liste öneriyor.

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

rootDir artık tahmin edilmiyor

Önceden rootDir verilmezse, bildirim dosyası olmayan tüm girdi dosyalarının ortak klasörü kök kabul edilirdi. 6.0 ile kök her zaman tsconfig.json dosyasının bulunduğu klasördür; tahmin yalnızca tsconfig.json olmadan komut satırından derlerken yapılır. Kaynaklarınız src altındaysa çıktı dist/index.js yerine dist/src/index.js olur. Bizim denememizde tsc 6.0.3, outDir verilip rootDir verilmeyen bir projede şu uyarıyı da gösterdi:

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.

Çözüm "rootDir": "./src" eklemektir. tsconfig.json dosyasının diğer alanları için tsconfig.json rehberi yazısına bakabilirsiniz.

Kullanımdan kaldırılan seçenekler

Aşağıdaki seçenekler 6.0 ile kullanımdan kalktı (deprecated). Kullandığınızda derleme hata ile durur; "ignoreDeprecations": "6.0" bu hataları susturur, ama 7.0 bu seçenekleri tamamen kaldıracak.

• target: es5: en düşük hedef artık ES2015. ES5 çıktısına hâlâ ihtiyacınız varsa sürüm notları harici bir derleyici öneriyor.
• --downlevelIteration: yalnızca ES5 çıktısını etkilediği için anlamını yitirdi. Değeri ne olursa olsun yazmak hata verir.
• --moduleResolution node (diğer adıyla node10): doğrudan Node.js hedefliyorsanız nodenext, paketleyici veya Bun kullanıyorsanız bundler önerilir.
• --moduleResolution classic: kaldırıldı; yerine nodenext veya bundler.
• module için amd, umd, systemjs ve none değerleri: artık desteklenmiyor; amd-module yönergesi de etkisiz.
• --baseUrl: artık modül aramasında kök olarak kullanılmıyor.
• esModuleInterop ve allowSyntheticDefaultImports: false yapılamıyor; güvenli birlikte çalışma davranışı her zaman açık.
• --alwaysStrict false: tüm kod JavaScript katı modunda kabul ediliyor.
• outFile: kaldırıldı; dosya birleştirme işi için paketleyici kullanın.
• Namespace için eski module Foo { } sözdizimi ve importlardaki asserts anahtar sözcüğü.
• /// <reference no-default-lib="true"/> yönergesi: yerine --noLib veya --libReplacement.

Eski seçenekleri içeren bir tsconfig.json dosyasını tsc 6.0.3 ile derlediğimizde aldığımız mesajlar şöyle (ilk satırlar kısaltıldı):

tsconfig.json(3,15): error TS5107: Option 'target=ES5' is deprecated and will stop
  functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"'
  to silence this error.
tsconfig.json(4,25): error TS5107: Option 'moduleResolution=node10' is deprecated ...
tsconfig.json(6,5): error TS5101: Option 'baseUrl' is deprecated and will stop
  functioning in TypeScript 7.0. ...
  Visit https://aka.ms/ts6 for migration information.

baseUrl nasıl kaldırılır?

Sürüm notlarına göre çoğu proje baseUrl değerini yalnızca paths girdilerine önek olarak kullanıyor. Bu durumda baseUrl satırını silip öneki doğrudan paths içine yazmanız yeterli:

{
  "compilerOptions": {
    "paths": {
      "@app/*": ["./src/app/*"],
      "@lib/*": ["./src/lib/*"]
    }
  }
}

Eğer baseUrl değerini gerçekten arama kökü olarak kullanıyorsanız, "*": ["./src/*"] biçiminde bir eşleme ekleyerek eski davranışı koruyabilirsiniz; notlar bunun çok nadir olduğunu söylüyor. Ayrıntılar için paths ve alias ayarları yazısına bakın.

namespace ve import attributes

module Eski {
  export const deger = 10;
}
// TS1540: A 'namespace' declaration should not be declared using the 'module'
// keyword. Please use the 'namespace' keyword instead.

declare module "paket-adi" { } biçimindeki ortam (ambient) modül bildirimleri etkilenmez. JSON importlarında da asserts { type: "json" } yerine with { type: "json" } yazmalısınız.

Yeni dil ve tip özellikleri

this kullanmayan metotlarda daha iyi çıkarım

Generic bir fonksiyona nesne verirken, parametre tipi yazılmamış metotlar (bağlama duyarlı fonksiyonlar) çıkarımda sona bırakılır. Metot sözdizimi örtük bir this taşıdığı için önceki sürümlerde aşağıdaki çağrıda y parametresi unknown kalıyor ve hata veriyordu. 6.0, gövdede this hiç kullanılmıyorsa fonksiyonu bağlama duyarlı saymaz; örnek artık hatasız derlenir:

declare function cagir<T>(nesne: {
  uret: (x: number) => T;
  tuket: (y: T) => void;
}): void;

cagir({
  tuket(y) { return y.toFixed(); }, // 6.0: y number olarak çıkarılır
  uret(x: number) { return x * 2; },
});

es2025 hedefi, RegExp.escape, Temporal ve upsert

target ve lib için es2025 değeri eklendi. Notlara göre ES2025 yeni bir dil sözdizimi getirmiyor, ama RegExp.escape gibi yerleşik API tiplerini ekliyor ve Promise.try, iterator metotları ile Set metotlarını esnext kütüphanesinden es2025 kütüphanesine taşıyor. Varsayılan hedef zaten es2025 olduğu için aşağıdaki kod bayraksız derlenir; Node.js 24 ile çalıştırdığımızda çıktı yorumdaki gibidir:

const kelime = "a.b*c";
const desen = new RegExp(`^${RegExp.escape(kelime)}$`);
console.log(desen.test("a.b*c"), desen.test("aXb*c")); // true false

Temporal API tipleri ve Map ile WeakMap üzerindeki getOrInsert ve getOrInsertComputed metotları ise esnext kütüphanesindedir. Varsayılan ayarla derlerseniz şu hatayı alırsınız; "lib": ["esnext"] (Temporal için daha dar olarak esnext.temporal) ile hata kalkar:

const ayarlar = new Map<string, unknown>();
const katiMi = ayarlar.getOrInsert("strict", true);
// TS2550: Property 'getOrInsert' does not exist on type 'Map<string, unknown>'.
// Do you need to change your target library? Try changing the 'lib' compiler
// option to 'esnext' or later.

Bu API'lerin çalışma zamanındaki davranışı için JavaScript tarih, saat ve Temporal ile Map, Set ve WeakMap yazılarına bakabilirsiniz. Hedef ve kütüphane seçimini target ve lib ayarları yazısı anlatıyor.

Modül tarafındaki yenilikler

• Node.js'in #/ ile başlayan subpath imports desteği ("imports": { "#/*": "./dist/*" }) artık --moduleResolution nodenext ve bundler altında tanınıyor.
• --moduleResolution bundler artık --module commonjs ile birlikte kullanılabiliyor; notlar bunu node10 çözümlemesinden çıkarken uygun bir ara yol olarak görüyor.
• dom kütüphanesi artık dom.iterable ve dom.asynciterable içeriğini kapsıyor; "lib": ["dom"] yeterli.

--stableTypeOrdering bayrağı

TypeScript 7.0 paralel tip denetimi yaptığı için tipleri ve sembolleri içeriğe dayalı, belirlenimci bir sırayla dizer. 6.0 ise tip kimliklerini karşılaşma sırasına göre verir; bu yüzden bir birleşim tipi .d.ts çıktısında 100 | 500 yerine 500 | 100 görünebilir. --stableTypeOrdering bayrağı 6.0'ın sıralamasını 7.0'a benzetir ve iki sürümün çıktısını karşılaştırırken gürültüyü azaltır. Notlar, bayrağın tip denetimini yüzde 25'e kadar yavaşlatabileceğini ve kalıcı kullanım için tasarlanmadığını vurguluyor.

tsconfig.json varken dosya adı vermek artık hata

Önceden tsc dosya.ts komutunu tsconfig.json bulunan bir klasörde çalıştırdığınızda yapılandırma sessizce yok sayılırdı. 6.0 bu durumu açık bir hataya çeviriyor. Yapılandırmayı bilerek atlamak istiyorsanız yeni --ignoreConfig bayrağını kullanırsınız:

$ tsc src/a.ts --noEmit
error TS5112: tsconfig.json is present but will not be loaded if files are
specified on commandline. Use '--ignoreConfig' to skip this error.

$ tsc --ignoreConfig src/a.ts --noEmit

Adım adım geçiş önerisi

• TypeScript'i 6.0'a yükseltip tsc --noEmit çalıştırın ve hataları gruplayın.
• Bulunamayan global isimler (process, describe) görüyorsanız "types" dizisini doldurun.
• Çıktı dist/src altına düşüyorsa "rootDir": "./src" ekleyin.
• Kullanımdan kalkan seçenekleri tek tek değiştirin. Hemen çözemediklerinizi geçici olarak "ignoreDeprecations": "6.0" ile susturun ve bir iş kaydı açın.
• Sürüm notlarında adı geçen deneysel ts5to6 aracı baseUrl ve rootDir düzeltmelerini otomatik yapabiliyor; yine de değişiklikleri gözden geçirin.
• Uyarı kalmadığında 7.0 native önizlemelerini denemeye hazırsınız.

Sık Sorulan Sorular

TypeScript 6.0 mevcut kodumu bozar mı?

Notlara göre 6.0, 5.9 ile API uyumludur ve dil bilginiz geçerliliğini korur. Bozulmalar daha çok yapılandırma kaynaklıdır: types ve rootDir varsayılanları ile kullanımdan kalkan seçenekler. Strict açık olmadan yazılmış projelerde de yeni tip hataları görebilirsiniz.

Strict modu kapatmam gerekir mi?

Gerekmez. Projeniz eski varsayılana dayanıyorsa "strict": false yazarak eski davranışı koruyabilirsiniz, ancak strict açıkken yakalanan hatalar genellikle gerçek hatalardır. Kademeli geçiş için tek tek strict bayraklarını açıp kapatabilirsiniz.

Node.js projemde hangi modül ayarını seçmeliyim?

Sürüm notları doğrudan Node.js hedefleyen projeler için --module nodenext, paketleyiciyle derlenen web uygulamaları veya Bun için --module preserve ile --moduleResolution bundler öneriyor. Ayrıntılar modül çözümleme, ESM ve CJS ile TypeScript ve Node.js yazılarında.

ES5 çıktısı almaya devam edebilir miyim?

tsc ile hayır; target: es5 kullanımdan kalktı. Notlar, ES5 gerekiyorsa TypeScript kaynağını doğrudan derleyen ya da tsc çıktısını sonradan işleyen harici bir derleyici kullanmanızı öneriyor.

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 5.x yenilikleri · tsconfig.json rehberi · Strict modu · Modül çözümleme · paths ayarları · TypeScript ileri seviye