TypeScript, JavaScript'in üzerine tip sistemi ekleyen bir dil. Yazdığınız kod derlendiğinde düz JavaScript'e dönüşüyor ve tarayıcıda ya da Node.js'te normal JavaScript gibi çalışıyor. Fark, kodu çalıştırmadan önce ortaya çıkıyor: yanlış tipte bir değer gönderdiğinizde, olmayan bir alana eriştiğinizde ya da undefined olabilecek bir şeyi kontrol etmeden kullandığınızda TypeScript sizi daha editörde uyarıyor.

TypeScript nedir sorusuna benim pratik cevabım şu: JavaScript'te çalışma anında, çoğu zaman production'da öğrendiğiniz hataların büyük kısmını yazarken öğrenmenizi sağlayan bir araç. Kullandığım diller arasında ilk sırada TypeScript var. Backend servislerini Node.js ve NestJS ile TypeScript'te yazıyorum, açık kaynak web proxy'm girici-web-proxy de TypeScript ve Vue ile yazılı. Bu yazıda TypeScript'in JavaScript'e ne eklediğini küçük örneklerle, sonra da tsconfig.json dosyasının temel ayarlarını anlatıyorum.

TypeScript nedir, JavaScript'ten farkı ne?

TypeScript, Microsoft'un geliştirdiği açık kaynak bir dil. JavaScript'in bir üst kümesi, yani her geçerli JavaScript kodu aynı zamanda geçerli bir TypeScript kodu. Bir .js dosyasının uzantısını .ts yapıp üzerine yavaş yavaş tip eklemeye başlayabiliyorsunuz.

Temel fark şu:

JavaScriptTypeScript
Tip kontrolüÇalışma anında, hata olursaYazarken ve derlerken
Çalıştığı yerTarayıcı, Node.jsÖnce JavaScript'e derleniyor, sonra aynı yerlerde
Editör desteğiSınırlı tahminOtomatik tamamlama, güvenli yeniden adlandırma
ÖğrenmeDaha kısaJavaScript'in üzerine tip sistemi

TypeScript'in tipleri çalışma anında yok. Derleme sırasında siliniyorlar. Yani API'den gelen bir JSON'un gerçekten beklediğiniz şekilde olup olmadığını TypeScript tek başına kontrol edemiyor. Dış dünyadan gelen veriyi yine doğrulamanız gerekiyor. Bunun için Zod gibi kütüphaneler ya da NestJS'te class-validator kullanılıyor.

TypeScript JavaScript'e ne ekler? Küçük örneklerle

Tipler ve hatayı erken yakalamak

Bir sepet toplamı hesaplayan fonksiyon düşünün:

type Urun = {
  ad: string;
  fiyat: number;
};

function toplam(urunler: Urun[]): number {
  return urunler.reduce((t, u) => t + u.fiyat, 0);
}

toplam([
  { ad: "Kahve", fiyat: "120" },
  { ad: "Kurabiye", fiyat: 80 },
]);

JavaScript'te bu kod hata vermeden çalışır ve 200 yerine "012080" döner, çünkü + operatörü sayıyla metni birleştirir. Fiyat bir formdan ya da bir API'den metin olarak geldiğinde bu hata kolayca production'a kadar gidiyor. TypeScript ise kodu çalıştırmadan durduruyor:

error TS2322: Type 'string' is not assignable to type 'number'.

Union tipleri

Bir değerin yalnızca belirli birkaç değerden biri olabileceğini söylemek için:

type Durum = "beklemede" | "hazirlaniyor" | "teslim-edildi";

function etiket(durum: Durum): string {
  switch (durum) {
    case "beklemede":
      return "Sipariş alındı";
    case "hazirlaniyor":
      return "Hazırlanıyor";
    case "teslim-edildi":
      return "Teslim edildi";
  }
}

etiket("iptal");
// error TS2345: Argument of type '"iptal"' is not assignable to parameter of type 'Durum'.

Yazım hatası yapılmış bir durum adı artık bir hata, sessiz bir bug değil. Durum tipine yeni bir değer eklediğinizde, switch içinde onu karşılamayan her fonksiyon da hata veriyor. Büyük bir kod tabanında bir değişikliğin nereleri etkilediğini bulmanın en hızlı yolu bu.

undefined kontrolü

JavaScript'te en sık görülen hatalardan biri Cannot read properties of undefined. TypeScript strict modda bunu derleme anında yakalıyor:

interface Kullanici {
  id: number;
  ad: string;
  email?: string;
}

function selamla(k: Kullanici) {
  return k.email.toLowerCase();
  // error TS18048: 'k.email' is possibly 'undefined'.
}

Düzeltmek için ya kontrol ediyorsunuz (if (k.email)) ya da k.email?.toLowerCase() yazıyorsunuz.

Generic'ler

Her tiple çalışan ama tip bilgisini kaybetmeyen fonksiyonlar için:

function ilk<T>(liste: T[]): T | undefined {
  return liste[0];
}

const sayi = ilk([1, 2, 3]);        // number | undefined
const isim = ilk(["Ali", "Ayşe"]); // string | undefined

T burada bir yer tutucu. Fonksiyonu çağırdığınızda TypeScript onun ne olduğunu kendisi çıkarıyor.

Narrowing

Bir API çağrısının sonucu başarılı ya da hatalı olabilir. Bunu tipte göstermek:

type Sonuc =
  | { ok: true; veri: Kullanici }
  | { ok: false; hata: string };

function yazdir(s: Sonuc) {
  if (s.ok) {
    console.log(s.veri.ad); // burada TypeScript s'nin başarılı olduğunu biliyor
  } else {
    console.log(s.hata);
  }
}

if (s.ok) kontrolünden sonra TypeScript hangi dalda hangi alanların var olduğunu biliyor. Başarısız bir sonuçta s.veri'ye erişmeye çalışırsanız hata alıyorsunuz.

TypeScript nasıl kurulur ve çalıştırılır?

TypeScript bir npm paketi. Projeye geliştirme bağımlılığı olarak ekleyin:

npm install -D typescript
npx tsc --init

tsc TypeScript derleyicisi. npx tsc komutu tsconfig.json dosyasını okuyup kodu kontrol ediyor ve JavaScript çıktısını üretiyor. Yalnızca tip kontrolü yapıp dosya üretmemesini istiyorsanız npx tsc --noEmit kullanın. CI'da çalıştırmak için uygun olan komut bu.

Güncel sürüm TypeScript 7. Bu sürümle derleyici native koda taşındı ve TypeScript ekibinin açıklamasına göre çoğu projede 6.0'dan yaklaşık 10 kat daha hızlı. 6.0'da temiz derlenen kod 7.0'da da aynı şekilde derleniyor.

Node.js tarafında da işler kolaylaştı. Node.js 22.18 ve 23.6'dan itibaren yalnızca tip açıklaması içeren .ts dosyalarını doğrudan çalıştırabiliyor:

node src/index.ts

Node.js burada tipleri silip kodu çalıştırıyor, tip kontrolü yapmıyor. enum, çalışma anı kodu içeren namespace ve constructor parametre property'leri gibi JavaScript'e çevrilmesi gereken özellikler desteklenmiyor. Bu yüzden Node.js'e doğrudan verilecek kodda enum yerine yukarıdaki gibi union tipleri kullanmak daha güvenli. Bir uyarı: Ubuntu'nun kendi deposundan kurulan nodejs paketinde bu özellik kapalı gelebiliyor. node -p process.features.typescript komutu false dönüyorsa Node.js'i nodejs.org üzerinden ya da bir sürüm yöneticisiyle kurun.

Node.js'in kendisini merak ediyorsanız Node.js nedir yazısında event loop'tan HTTP sunucusuna kadar anlattım.

tsconfig.json temel ayarları

tsconfig.json, TypeScript'e kodunuzu nasıl kontrol edip nasıl derleyeceğini söyleyen dosya. npx tsc --init TypeScript 7'de şuna benzer bir dosya üretiyor (yorum satırları çıkarılmış hali):

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "types": [],
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "strict": true,
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true
  }
}

Bir Node.js backend'i için daha sade bir başlangıç:

{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "types": ["node"],
    "sourceMap": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Ayarların ne işe yaradığı:

  • target: Çıktının hangi JavaScript sürümüne göre üretileceği. Güncel Node.js için es2024 gibi yeni bir hedef seçebilirsiniz, eski tarayıcıları desteklemeniz gerekiyorsa daha eski bir hedef.
  • module: Modül sistemi. Node.js projeleri için nodenext, Vite gibi bir bundler kullanan frontend projeleri için genelde esnext ile birlikte "moduleResolution": "bundler".
  • rootDir ve outDir: Kaynak dosyaların nerede olduğu ve derlenmiş JavaScript'in nereye yazılacağı. src/index.ts derlenince dist/index.js oluyor.
  • strict: Bütün katı kontrolleri açıyor. undefined kontrolü dahil yukarıdaki örneklerin çoğu bunun sayesinde çalışıyor. TypeScript 6.0'dan beri varsayılan olarak açık. Kapatmayın.
  • types: Hangi @types/* paketlerinin otomatik yükleneceği. TypeScript 6.0 ile varsayılanı boş liste oldu, yani @types/node kurduysanız burada "node" yazmanız gerekiyor. Yazmazsanız process ya da Buffer için "bulunamadı" hatası alıyorsunuz.
  • skipLibCheck: node_modules içindeki tip dosyalarının kontrolünü atlıyor. Derlemeyi hızlandırıyor, kendi kodunuzun kontrolünü etkilemiyor.
  • sourceMap: Hata mesajlarında derlenmiş JavaScript yerine TypeScript dosyasındaki satırı görmenizi sağlıyor.

module: "nodenext" kullanıyorsanız package.json dosyasına "type": "module" eklemeyi unutmayın. Eklemezseniz TypeScript dosyalarınızı CommonJS sayıyor ve --init'in açtığı verbatimModuleSyntax ile birlikte her import ve export satırında hata veriyor.

TypeScript'i neden kullanıyorum?

Küçük bir script için TypeScript gereksiz gelebilir. Fark, bir projede birden fazla kişi çalışmaya başladığında ya da kod birkaç ayı geçtiğinde ortaya çıkıyor.

En çok işime yarayan şey yeniden düzenlemenin güvenli olması. Bir fonksiyonun parametresini değiştirdiğinizde onu yanlış çağıran her yer editörde kırmızıya dönüyor. JavaScript'te bunu ancak testleriniz yakalarsa öğreniyorsunuz. Bir fonksiyonun ne alıp ne döndürdüğünü de dokümana bakmadan tipinden okuyabiliyorsunuz.

Backend ile frontend aynı tipleri paylaşabiliyor. Bir API'nin döndürdüğü veri için yazdığınız tipi hem NestJS servisinde hem Nuxt arayüzünde kullanabiliyorsunuz. Full stack çalışırken bu, iki taraf arasındaki uyumsuzlukları daha yazarken yakalamak demek.

Açık kaynak projelerimde de durum aynı. shotsnap ve temp-mail-plus-api TypeScript ile yazılı, random-memes JavaScript olsa da TypeScript tipleriyle birlikte geliyor. Kütüphane kullanan biri için tip dosyası otomatik tamamlama ve dokümantasyon demek.

TypeScript'in de bir bedeli var: ilk başta tip hatalarıyla uğraşmak yavaşlatıyor, generic'li karmaşık tipleri okumak zaman alıyor. Bu bedel, projenin ömrü uzadıkça kendini geri ödüyor.

Sık sorulan sorular

TypeScript öğrenmek için önce JavaScript bilmek gerekir mi?

Evet. TypeScript JavaScript'in üzerine kurulu. Değişkenler, fonksiyonlar, nesneler ve async/await konularını bilmeden TypeScript öğrenmek, iki şeyi aynı anda öğrenmeye çalışmak demek. Yazılıma yeni başlıyorsanız yazılımcı nasıl olunur yazısına da bakabilirsiniz.

TypeScript kodu tarayıcıda doğrudan çalışır mı?

Hayır. Tarayıcılar TypeScript'i anlamıyor. Kodu önce tsc ya da Vite gibi bir araçla JavaScript'e çevirmeniz gerekiyor. Vue, Nuxt, React gibi framework'lerin proje şablonları bunu sizin yerinize yapıyor.

TypeScript performansı etkiler mi?

Çalışma anında etkilemez, çünkü tipler derleme sırasında siliniyor ve ortaya çıkan JavaScript aynı hızda çalışıyor. Etkilediği şey derleme süresi, o da TypeScript 7 ile ciddi şekilde kısaldı.

type mı interface mi kullanmalıyım?

Nesne şekilleri için ikisi de iş görüyor. Union tipleri ve daha karmaşık tip ifadeleri için type gerekiyor. Bir projede birini seçip tutarlı kullanmak, hangisini seçtiğinizden daha önemli.

any kullanmak kötü mü?

any o değer için tip kontrolünü kapatıyor. Gerçekten bilinmeyen veri için unknown kullanın: TypeScript, unknown bir değeri kontrol etmeden kullanmanıza izin vermiyor.