TypeScript target ve lib Ayarları Ne İşe Yarar?

target neyi kontrol eder?

Resmî dokümantasyona göre target, hangi JavaScript özelliklerinin eski sürüme indirgeneceğini, hangilerinin olduğu gibi bırakılacağını belirler. Tip açıklamaları her durumda silinir; target yalnızca geriye kalan JavaScript sözdiziminin nasıl yazılacağını etkiler. Aşağıdaki dosyada nullish birleştirme (??) ve optional chaining (?.) kullanılıyor. İki operatör de dile ES2020 ile eklendi.

type Ayar = { port?: number; ad?: string | null };
export function ozet(a: Ayar) {
  const port = a.port ?? 3000;
  const uzunluk = a.ad?.length;
  return `${port}:${uzunluk}`;
}
console.log(ozet({ port: 8080, ad: "api" })); // 8080:3
console.log(ozet({})); // 3000:undefined

npx tsc --target es2019 --module esnext --outDir out2019 a.ts
npx tsc --target es2020 --module esnext --outDir out2020 a.ts

es2019 hedefinde iki operatör de geçici değişken kullanan koşul ifadelerine dönüştü:

export function ozet(a) {
    var _a, _b;
    const port = (_a = a.port) !== null && _a !== void 0 ? _a : 3000;
    const uzunluk = (_b = a.ad) === null || _b === void 0 ? void 0 : _b.length;
    return `${port}:${uzunluk}`;
}

es2020 hedefinde ise çıktı, tip açıklamaları dışında kaynakla aynı kaldı: a.port ?? 3000 ve a.ad?.length hiç değişmedi. İki çıktıyı da Node.js 24 ile çalıştırdık ve ikisi de aynı sonucu yazdı. Yani downleveling davranışı değiştirmez, sadece aynı davranışı eski motorların anlayacağı biçimde yazar.

Dönüşüm bazen yardımcı fonksiyonlar da ekler. #deger adlı özel bir sınıf alanını --target es2021 ile derlediğimizde çıktıya WeakMap tabanlı __classPrivateFieldGet ve __classPrivateFieldSet yardımcıları eklendi. Hedef ne kadar eskiyse çıktı o kadar uzar ve hata ayıklarken okunması zorlaşır.

TypeScript 6.0'da target varsayılanı ve kaldırılan değerler

6.0 sürüm notlarına göre target belirtilmediğinde derleyici desteklediği en yeni ECMAScript sürümünü kullanır. Bu, her yıl ilerleyen "kayan" bir varsayılandır ve şu an es2025 değerine karşılık gelir; derleyicinin tsc --all çıktısı da default: es2025 yazıyor. Daha önceki sürümlerde varsayılan çok daha eskiydi, bu yüzden eski kaynaklarda gördüğünüz varsayılanlar artık geçerli değil.

Aynı sürümde target: es5 kullanımdan kaldırıldı ve desteklenen en düşük hedef ES2015 oldu. Denediğimizde derleyici şu hatayı verdi:

npx tsc --noEmit --target es5 b.ts
# 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ürüm notları, ES5 çıktısına hâlâ ihtiyaç duyanlara kaynağı harici bir derleyiciyle derlemeyi ya da TypeScript çıktısını sonradan başka bir araçla işlemeyi öneriyor. "ignoreDeprecations": "6.0" uyarıyı yalnızca 6.0 için susturur; TypeScript 7.0 bu seçenekleri hiç tanımayacak. Sadece ES5 çıktısını etkileyen --downlevelIteration da kaldırıldı; 6.0'da bu bayrağı hangi değerle verirseniz verin kullanımdan kaldırma hatası alırsınız.

6.0 ayrıca es2025 değerini ekledi. Sürüm notlarına göre ES2025 yeni bir sözdizimi getirmiyor; bu değer RegExp.escape gibi yeni yerleşik API tiplerini ekliyor ve Promise.try, Iterator metotları ile Set metotlarının tanımlarını esnext kümesinden es2025 kümesine taşıyor. Örneğin new Set([1, 2]).union(new Set([3])) çağrısı --target es2024 ile TS2550 hatası verdi, varsayılan ayarla ise sorunsuz derlendi.

esnext için dokümantasyon açık bir uyarı yapıyor: bu değer farklı TypeScript sürümlerinde farklı anlama gelir ve sürüm yükseltmelerini daha az öngörülebilir kılabilir. Bazı module değerleri de target varsayılanını değiştirir: module: nodenext esnext hedefini, node20 es2023 hedefini, node16 ve node18 ise es2022 hedefini ima eder.

lib neyi kontrol eder?

TypeScript, Math gibi yerleşik JavaScript API'leri ve document gibi tarayıcı nesneleri için hazır tip tanımlarıyla gelir. lib belirtmezseniz bu küme target değerine göre seçilir ve tarayıcı tanımları (DOM) da eklenir. Hedefinizde bulunmayan bir metodu çağırdığınızda derleyici hangi lib değerine ihtiyaç duyduğunuzu açıkça söyler. Aşağıdaki dosyayı --target es2021 ile derledik:

const sayilar = [3, 1, 2];
console.log(sayilar.at(-1));
// TS2550: Property 'at' does not exist on type 'number[]'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2022' or later.
console.log(sayilar.toSorted());
// 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.

target değerini yükseltmek ya da lib listesine es2023 eklemek iki hatayı da giderir. Burada dikkat edilmesi gereken nokta şu: lib değerini elle yazdığınız anda varsayılan küme tamamen sizin listenizle değişir. Aşağıdaki dosyayı --lib es2022 ile derlediğimizde DOM tanımları devreden çıktı ve document ile birlikte console da bulunamadı, çünkü bu kurulumda console tanımı da DOM kütüphanesinden geliyor:

const baslik = document.title;
// TS2584: Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.
console.log(baslik);
// TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.

Node.js projelerinde ihtiyaç farklıdır: tarayıcı API'lerinin görünmesini istemezsiniz, ama console ve process gerekir. TypeScript 5.9 ile gelen tsc --init şablonu Node.js için "lib": ["esnext"] ve "types": ["node"] ayarlarını, ayrıca @types/node paketini öneriyor. Bu kurulumu TypeScript ile Node.js yazısında adım adım gösterdik.

Bu üst düzey değerlerin yanında es2017.string ya da esnext.temporal gibi daha dar bileşenler de vardır. Derleyicinin kabul ettiği tam listeyi tsc --all çıktısındaki --lib satırında görebilirsiniz.

target ve lib birlikte: TypeScript polyfill eklemez

İki seçeneği farklı değerlerle kullanmak serbesttir; dokümantasyon da bunları ihtiyaca göre karıştırabileceğinizi söylüyor. Ancak işlevleri farklıdır: target sözdizimini dönüştürür ama eksik API'leri tamamlamaz, lib ise derleyiciye yalnızca "bu API çalışma ortamında var" bilgisini verir. --target es2015 --lib es2023,dom ile derlediğimiz dosyanın çıktısı şöyle:

"use strict";
const sayilar = [3, 1, 2];
console.log(sayilar.at(-1));
console.log(sayilar.toSorted());

at ve toSorted çağrıları olduğu gibi kaldı. Node.js 24 bu metotları zaten desteklediği için çıktı 2 ve [ 1, 2, 3 ] oldu; bu metotları tanımayan bir ortamda ise aynı kod çalışma anında hata verir. lib dokümantasyonu da bu ayarı değiştirmenin tipik nedenlerinden biri olarak, çalışma ortamının bazı API'leri polyfill ile sağlamasını sayıyor. Polyfill gerekiyorsa onu projeye sizin eklemeniz gerekir.

TypeScript 6.0 ile lib tarafında gelen değişiklikler

• dom artık dom.iterable ve dom.asynciterable içeriğini de kapsıyor. NodeList üzerinde for...of kullanmak için bunları ayrıca yazmanız gerekmiyor; eski değerler boş dosyalar olarak hâlâ kabul ediliyor.
• Temporal API tipleri eklendi. --target esnext, "lib": ["esnext"] ya da daha dar olan esnext.temporal ile kullanılabiliyor.
• Map ve WeakMap için getOrInsert ve getOrInsertComputed tipleri esnext kütüphanesine eklendi.
• libReplacement varsayılanı false oldu. Yerleşik lib dosyalarını @typescript/lib-* paketleriyle değiştiriyorsanız bu seçeneği açıkça true yapmalısınız.

Ters yöndeki ihtiyaç için noLib seçeneği vardır: tüm lib dosyalarını devre dışı bırakır ve lib ayarını yok sayar. Bu durumda Array, String, Object gibi temel arayüzlerin tanımlarını sizin sağlamanız gerekir; sıradan uygulama projelerinde kullanılmaz.

Hangi değeri seçmelisiniz?

Dokümantasyon herkese uyan tek bir değer önermiyor; karar, kodun çalışacağı ortama bağlı. Genel kural şudur: target, desteklemek istediğiniz en eski ortamın anladığı sözdizimine göre seçilir; lib ise o ortamda gerçekten bulunan API'leri tarif etmelidir. Node gibi platformlar için sürüme göre hazırlanmış topluluk tsconfig şablonları tsconfig/bases deposunda toplanmıştır ve target dokümantasyonu da bu depoyu gösterir.

• Node.js uygulaması: module: nodenext zaten target: esnext anlamına gelir. Daha sabit bir taban istiyorsanız module: node20 es2023 hedefini ima eder.
• Tarayıcıda çalışan kod: lib içinde dom bulunmalı; target ise desteklediğiniz en eski tarayıcının anladığı sürümden yüksek olmamalı.
• ES5 gerektiren eski ortam: TypeScript 6.0 ile doğrudan mümkün değil; sürüm notlarının önerdiği gibi harici bir derleyici gerekir.

Sık yapılan hatalar

• lib yazıp dom eklemeyi unutmak: Tarayıcı kodunda document ve window için TS2584 hatası alırsınız.
• lib değerini yükseltince API'nin çalışma anında da var olacağını sanmak: TypeScript polyfill eklemez; yukarıdaki örnekte olduğu gibi çağrılar çıktıda aynen kalır.
• esnext değerini sabit sanmak: TypeScript sürümünü yükselttiğinizde çıktının sözdizimi de değişebilir.
• 6.0'a geçerken eski varsayılana güvenmek: target yazmayan projelerde çıktı artık es2025 sözdizimiyle üretilir. Daha eski bir ortamı hedefliyorsanız değeri açıkça yazın.
• ignoreDeprecations ayarını kalıcı çözüm saymak: Bu ayar yalnızca geçiş süresi kazandırır; TypeScript 7.0 kaldırılan değerleri desteklemeyecek.

Sık Sorulan Sorular

target ile lib arasındaki fark nedir?

target çıktıdaki JavaScript sözdizimini belirler ve gerekirse yeni sözdizimini eskisine çevirir. lib ise yalnızca tip denetiminde hangi yerleşik API tanımlarının görüneceğini belirler, çıktıya hiçbir şey eklemez.

TypeScript 6.0'da varsayılan target nedir?

Desteklenen en yeni ECMAScript sürümüdür; TypeScript 6.0 için bu es2025 değeridir. module: nodenext gibi bazı ayarlar bu varsayılanı değiştirebilir.

target: es5 neden hata veriyor?

TypeScript 6.0 bu değeri kullanımdan kaldırdı ve TS5107 hatası üretiyor. "ignoreDeprecations": "6.0" geçici olarak susturur, ama 7.0 bu değeri desteklemeyecek. ES5 çıktısı için harici bir derleyici kullanmanız gerekir.

TypeScript eksik API için polyfill ekler mi?

Hayır. target yalnızca sözdizimini dönüştürür. Array.prototype.at gibi bir metot çalışma ortamında yoksa polyfill'i sizin eklemeniz gerekir.

lib listesine dom.iterable eklemem gerekiyor mu?

TypeScript 6.0 ile gerekmiyor; dom bu içeriği zaten kapsıyor. Listede kalması hata vermez, çünkü bu değerler artık boş dosyalar olarak tutuluyor.

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 · tsconfig.json rehberi · TypeScript ile Node.js · TypeScript 6.0 yenilikleri · modül çözümleme: ESM ve CJS · JavaScript optional chaining ve ??