TypeScript Kurulumu ve tsc Komutu: npm, tsc --init, watch ve noEmit

Kurulum: global mi, proje içi mi?

Resmî Handbook'taki ilk örnek derleyiciyi global olarak kurar ve aynı yerde, isterseniz npx ile yerel node_modules içindeki tsc'yi kullanabileceğinizi belirtir. Gerçek projelerde proje içi kurulum daha sağlamdır: herkes aynı derleyici sürümünü kullanır ve sürüm package.json içinde kayıtlı kalır.

# Proje içi kurulum (önerilen)
npm install --save-dev typescript
npx tsc --version
# Version 6.0.3

# Global kurulum
npm install -g typescript
tsc --version

Node.js'i henüz kurmadıysanız Node.js nedir yazısından başlayabilirsiniz. Gece derlemelerini denemek isterseniz resmî belgelerde npm install -D typescript@next komutu verilir; üretimde kararlı sürümü kullanın.

İlk derleme

Boş bir klasörde merhaba.ts adlı bir dosya oluşturun. Bilerek bir hata bırakıyoruz: fonksiyon iki argüman beklerken tek argümanla çağrılıyor.

function selamla(kisi: string, tarih: Date) {
  console.log(`Merhaba ${kisi}, bugün ${tarih.toDateString()}!`);
}

selamla("Ayşe");

npx tsc merhaba.ts
# merhaba.ts(5,1): error TS2554: Expected 2 arguments, but got 1.

Klasöre baktığınızda hata olmasına rağmen merhaba.js dosyasının üretildiğini görürsünüz. Bu bilinçli bir tasarım: TypeScript, özellikle JavaScript'ten geçiş sırasında çalışan kodu engellememek için varsayılan olarak hatalara rağmen çıktı üretir. Hata varsa hiç çıktı üretilmesin istiyorsanız --noEmitOnError ekleyin:

npx tsc --noEmitOnError merhaba.ts
# merhaba.ts(5,1): error TS2554: Expected 2 arguments, but got 1.
# (merhaba.js oluşturulmaz)

Terminalde çalıştırdığınızda çıktı renkli ve ayrıntılı olur: hatalı satırı altı çizili gösterir, ilgili parametrenin tanımını da işaret eder ("An argument for 'tarih' was not provided.") ve sonunda kaç hata bulunduğunu yazar. Çıktı bir dosyaya veya başka bir programa yönlendirildiğinde yukarıdaki tek satırlık biçim kullanılır; --pretty false ile bunu her zaman seçebilirsiniz.

Bir not: tsconfig dosyası olmadan, yalnızca dosya adıyla derlediğinizde de TypeScript 6.0 varsayılan olarak strict açık çalışır ve modern bir ECMAScript hedefi kullanır. Denememizde tip ek açıklaması olmayan bir parametre TS7006: Parameter 's' implicitly has an 'any' type. hatası verdi ve sınıf alanları dönüştürülmeden çıktıya aynen yazıldı.

tsc --init ile proje başlatmak

Gerçek bir projede derleyici ayarlarını komut satırında değil tsconfig.json dosyasında tutarsınız. tsc --init bu dosyayı sizin için oluşturur. TypeScript 5.9 ile bu çıktı sadeleştirildi: eskiden yüzlerce yorum satırıyla gelen dosya, artık az sayıda ve daha belirleyici ayarla geliyor. TypeScript 6.0.3 ile ürettiğimiz dosya tam olarak şöyle:

{
  // Visit https://aka.ms/tsconfig to read more about this file
  "compilerOptions": {
    // File Layout
    // "rootDir": "./src",
    // "outDir": "./dist",

    // Environment Settings
    // See also https://aka.ms/tsconfig/module
    "module": "nodenext",
    "target": "esnext",
    "types": [],
    // For nodejs:
    // "lib": ["esnext"],
    // "types": ["node"],
    // and npm install -D @types/node

    // Other Outputs
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // Stricter Typechecking Options
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Style Options
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,
    // "noPropertyAccessFromIndexSignature": true,

    // Recommended Options
    "strict": true,
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

Bu şablonda dikkat çeken birkaç nokta var. module değeri nodenext, target ise esnext olarak geliyor. types boş bir dizi; yani node_modules/@types altındaki paketler otomatik yüklenmiyor, Node.js için yorum satırındaki gibi "types": ["node"] eklemeniz ve @types/node kurmanız gerekiyor. strict açık; ayrıca strict ailesinde olmayan noUncheckedIndexedAccess ve exactOptionalPropertyTypes da açık geliyor. Her ayrıntı için tsconfig.json rehberi yazısına bakın.

tsconfig varken derleme

tsconfig.json olan bir klasörde dosya adı vermeden tsc çalıştırdığınızda derleyici o dosyayı bulur ve projedeki bütün dosyaları ayarlara göre derler. Başka bir yapılandırma dosyası kullanmak için -p (--project) seçeneğini kullanırsınız.

npx tsc                          # en yakın tsconfig.json ile derle
npx tsc -p tsconfig.build.json   # belirli bir yapılandırma dosyasıyla derle
npx tsc --showConfig             # birleşmiş son ayarları yazdır, derleme yapma

TypeScript 6.0 ile önemli bir değişiklik geldi: tsconfig bulunan bir klasörde dosya adı vererek tsc çalıştırmak artık hata veriyor. Eskiden bu durumda tsconfig sessizce yok sayılırdı ve bu çok kafa karıştırıyordu.

npx tsc merhaba.ts
# error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.

npx tsc --ignoreConfig merhaba.ts   # tsconfig'i bilerek yok say

Watch modu

--watch (kısaca -w) derleyiciyi açık tutar ve dosyalar değiştikçe yalnızca gereken kısmı yeniden derler. Kaydettiğiniz anda hataları görürsünüz. Denememizde bir dosyaya hatalı satır eklediğimizde çıktı şöyle oldu:

npx tsc --watch --noEmit
# 21:29:57 - Starting compilation in watch mode...
# 21:29:57 - Found 0 errors. Watching for file changes.
# 21:30:00 - File change detected. Starting incremental compilation...
# hello.ts(8,5): error TS2322: Type 'string' is not assignable to type 'number'.
# 21:30:00 - Found 1 error. Watching for file changes.

İzleme davranışı Node.js'in dosya izleme mekanizmalarına dayanır. Çok büyük projelerde veya bazı Linux ortamlarında izleme sınırlarına takılırsanız tsconfig.json içindeki watchOptions bölümüyle watchFile, watchDirectory ve fallbackPolling gibi stratejileri ayarlayabilirsiniz.

noEmit: yalnızca tip denetimi

noEmit, derleyicinin JavaScript, source map veya declaration dosyası üretmesini tamamen kapatır. Dönüştürme işini Babel, swc veya bir paketleyici (bundler) yapıyorsa TypeScript'i yalnızca tip denetleyicisi ve editör desteği olarak kullanırsınız. Bu kurulumda tipik akış, tsc --noEmit komutunu CI'da ve commit öncesinde çalıştırmaktır.

{
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "dev": "tsc --watch"
  }
}

Node.js tarafında da benzer bir durum var. TypeScript 5.8 sürüm notları, Node.js'in tipleri silerek TypeScript dosyalarını doğrudan çalıştırabilen bir mod sunduğunu ve bu modun yalnızca silinebilir sözdizimini desteklediğini anlatır. Denememizde Node 24 basit bir .ts dosyasını doğrudan çalıştırdı. Bu senaryoda da tip denetimi için tsc --noEmit gerekir; ayrıntılar TypeScript'i Node.js ile kullanma yazısında.

Sık kullanılan tsc seçenekleri

--build modu birden fazla tsconfig içeren projeler içindir; project references yazısında anlatıyoruz.

Sık yapılan hatalar

• Global ve yerel sürümün karışması: Global tsc ile projedeki sürüm farklı olabilir. Projede her zaman npx tsc kullanın.
• TS5112 hatası: tsconfig olan klasörde tsc dosya.ts çalıştırdınız. Dosya adını kaldırın ya da bilerek --ignoreConfig ekleyin.
• process veya require bulunamıyor: 6.0'da types varsayılanı boş dizi. npm install --save-dev @types/node kurup "types": ["node"] ekleyin. Denememizde bu eksikken TS2591: Cannot find name 'process' hatası aldık.
• Çıktının dist/src altına düşmesi: 6.0'da rootDir varsayılanı tsconfig'in bulunduğu klasör. "rootDir": "./src" ekleyin.

Sık Sorulan Sorular

typescript paketini dependencies mi devDependencies mi altına eklemeliyim?

Derleyici yalnızca geliştirme ve derleme sırasında gerekir; çalışan uygulama derlenmiş JavaScript'i kullanır. Bu yüzden genellikle --save-dev (-D) ile geliştirme bağımlılığı olarak eklenir.

tsc --init çıktısı neden internetteki örneklerden farklı?

TypeScript 5.9 ile --init şablonu yeniden tasarlandı. Eski şablonlar uzun yorum listeleri içeriyordu; yenisi daha kısa ve modern varsayılanlarla geliyor. Kendi sürümünüzün ürettiği dosyayı esas alın.

Hata varken neden JavaScript dosyası oluşuyor?

Varsayılan davranış budur; noEmitOnError varsayılan olarak kapalıdır. Böylece geçiş sürecinde çalışan kodunuz durmaz. Üretim derlemelerinde bu ayarı açmak veya çıkış kodunu kontrol etmek mantıklıdır.

Watch modu ile tsc --noEmit birlikte kullanılabilir mi?

Evet. tsc --watch --noEmit, dosya üretmeden sürekli tip denetimi yapar. Paketleyicinin kendi izleme modunu kullandığınız projelerde ikinci bir terminalde çalıştırmak yaygın bir düzendir.

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 strict modu · TypeScript ile Node.js · Node.js nedir