TypeScript Dosyası Nasıl Çalıştırılır: tsc, Node.js, tsx, ts-node

Bir TypeScript dosyası olduğu gibi çalışamaz, çünkü tarayıcılar ve JavaScript motorları tip notasyonlarını anlamaz. Önce bir şeyin tipleri kaldırması gerekir. Bu ya tipleri kontrol de eden TypeScript derleyicisidir (tsc) ya da yalnızca onları silen daha hızlı bir araçtır. Bu sayfadaki kodu çalıştırmanın en hızlı yolu Run düğmesidir:

type Task = { title: string; done: boolean };

const tasks: Task[] = [
    { title: "Install TypeScript", done: true },
    { title: "Run a .ts file", done: false },
];

for (const task of tasks) {
    console.log(`${task.done ? "[x]" : "[ ]"} ${task.title}`);
}

Çıktı:

[x] Install TypeScript
[ ] Run a .ts file

Bu dokümanlardaki her çalıştırılabilir blok aynı şekilde çalışır: kod, strict açıkken TypeScript 7 tarafından tip kontrolünden geçirilir ve yalnızca tip hatası yoksa çalışır. Daha uzun denemeler için TypeScript playground aynı editörü kendi sayfasında sunar. Bu sayfanın geri kalanı .ts dosyalarını kendi makinenizde çalıştırmakla ilgili.

Bir Bakışta Seçenekler

İnsanları şaşırtan ilk sütundur: hızlı seçeneklerin çoğu, içinde tip hatası olan kodu da çalıştırır. Tipik bir proje kodu bunlardan biriyle çalıştırır ve hataları yakalamak için editörde ve CI'da ayrıca tsc --noEmit çalıştırır.

tsc ile Derleyip Node ile Çalıştırmak

Bu yaklaşım her yerde çalışır ve her şeyi kontrol eder. Projeye TypeScript kurulu ve "rootDir": "./src" ile "outDir": "./dist" ayarlayan bir tsconfig.json varken:

npx tsc
node dist/index.js

tsc tüm dosyaların tipini kontrol eder, ardından .js dosyalarını dist klasörüne yazar. Projesiz tek bir dosya için dosya adını verin. Bu durumda varsayılan seçenekleri kullanır ve index.js dosyasını index.ts dosyasının yanına yazar:

npx tsc index.ts
node index.js

(Klasörde bir tsconfig.json varsa tsc dosya adlarını error TS5112 ile reddeder; düz npx tsc çalıştırın ya da --ignoreConfig ekleyin.)

Varsayılan olarak tsc tip hataları olduğunda da JavaScript'i yazar; yani node kontrolden geçemeyen bir programı çalıştırabilir. Bunu önlemek için yapılandırmaya "noEmitOnError": true ekleyin ya da komutları bir betikte zincirleyin, böylece ikinci adım yalnızca ilki başarılı olursa çalışır:

{
    "scripts": {
        "build": "tsc",
        "start": "tsc && node dist/index.js"
    }
}

Geliştirme sırasında npx tsc --watch her kaydetmede yeniden derler.

TypeScript'i Doğrudan Node.js ile Çalıştırmak

Güncel Node.js .ts dosyalarını kendisi çalıştırır:

node index.ts

Node tip notasyonlarını boşluklarla değiştirerek siler (böylece stack trace'lerdeki satır numaraları yine eşleşir) ve kalanı çalıştırır. Bu özellik Node.js 23.6.0 ve 22.18.0'dan beri varsayılan olarak açıktır, 24.3.0 ve 22.18.0'dan beri uyarı yazdırmaz ve Node.js 24.12.0 ile 25.2.0'da kararlı olarak işaretlendi. Özelliğe sahip daha eski sürümler (22.6 ile 22.17 arası ve 23.0 ile 23.5 arası) bayrak ister: node --experimental-strip-types index.ts.

Bununla birlikte dört kural gelir:

• Tip kontrolü yok. const age: number = "forty" içeren bir dosya çalışır ve forty yazdırır.
• Yalnızca silinebilen sözdizimi. Yok olmak yerine JavaScript koduna dönüşmesi gereken her şey reddedilir: enum, çalışma zamanı kodu içeren namespace blokları, constructor(private name: string) gibi constructor parametre özellikleri ve import x = require() alias'ları. Node SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode ile durur.
• tsconfig.json yok sayılır. paths veya target gibi seçeneklerin etkisi olmaz.
• Import'lar gerçek dosya adları ister. Uzantısıyla birlikte import { add } from "./math.ts" yazın ve yalnızca tip içeren import'ları type ile işaretleyin: import { add, type Pair } from "./math.ts". type olmadan Node, Pair adında bir çalışma zamanı export'u arar ve SyntaxError: The requested module './math.ts' does not provide an export named 'Pair' ile başarısız olur.

İki derleyici seçeneği tsc'nin de aynı kuralları uygulamasını sağlar, böylece editör sizi Node'dan önce uyarır: "erasableSyntaxOnly": true bir enum üzerinde error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. bildirir, "verbatimModuleSyntax": true ise yalnızca tip içeren import'larda type anahtar kelimesini zorunlu kılar. Import'larda .ts uzantısı yazmaya devam edip yine de tsc ile derlemek için "rewriteRelativeImportExtensions": true ekleyin; bu seçenek çıktıda ./math.ts yolunu ./math.js yapar.

Node.js 24'te ayrıca --experimental-transform-types vardır; enum'ları ve parametre özelliklerini reddetmek yerine onlar için kod üretir. Bir ExperimentalWarning yazdırır ve Node.js 26 bu bayrağı kaldırdı, bu yüzden üzerine bir şey kurmayın.

Bu blok, node index.ts komutunun reddettiği iki özellik kullanıyor. Burada çalışır, çünkü editör onu ikisi için de JavaScript üreten TypeScript derleyicisiyle derler:

enum Level {
    Low = 1,
    High = 3,
}

class Counter {
    constructor(private count: number) {} // a parameter property

    add(level: Level): number {
        this.count += level;
        return this.count;
    }
}

const c = new Counter(0);
console.log(c.add(Level.Low), c.add(Level.High)); // 1 4

Aynı kodun silinebilir sürümü bir const nesne ve sıradan bir alan kullanır; Node bunu olduğu gibi çalıştırabilir:

const Level = { Low: 1, High: 3 } as const;
type Level = (typeof Level)[keyof typeof Level]; // 1 | 3

class Counter {
    private count: number;

    constructor(count: number) {
        this.count = count;
    }

    add(level: Level): number {
        this.count += level;
        return this.count;
    }
}

const c = new Counter(0);
console.log(c.add(Level.Low), c.add(Level.High)); // 1 4

tsx

tsx bir TypeScript dosyasını yapılandırma olmadan ve sözdizimi kısıtlaması olmadan tek adımda çalıştırır:

npm install --save-dev tsx
npx tsx index.ts
npx tsx watch index.ts   # rerun on every change

Kodu esbuild ile dönüştürür; bu yüzden enum'lar, namespace'ler ve parametre özellikleri çalışır, uzantısız import'lar da bir bundler'daki gibi çözümlenir. Node'un type stripping özelliği gibi tip kontrolü yapmaz. Type stripping öncesi Node.js sürümlerinde ya da kod Node'un reddettiği sözdizimini kullandığında betikler, geliştirme sunucuları ve testler için yaygın tercihtir.

ts-node

ts-node yıllarca Node.js üzerinde TypeScript çalıştırmanın standart yoluydu ve pek çok eğitim ile eski proje hâlâ onu kullanır (npx ts-node index.ts, node -r ts-node/register). TypeScript derleyicisinin JavaScript API'sini kullanarak varsayılan olarak tip kontrolü yapar.

Bu API tam da TypeScript 7'nin içermediği şeydir: derleyicisi yerel bir programdır ve typescript 7 paketi JavaScript'e hiçbir derleyici API'si sunmaz. TypeScript 7 kuruluyken ts-node hiçbir şey çalıştırmadan çöker:

TypeError: Cannot read properties of undefined (reading 'fileExists')
    at readConfig (/project/node_modules/ts-node/dist/configuration.js:91:33)

ts-node'un en son sürümü 10.9.2, Aralık 2023 tarihlidir. Yeni kod için tsx veya node index.ts kullanın. ts-node'a bağımlı mevcut bir kurulum, proje TypeScript 6'da kalırsa (npm install --save-dev typescript@6) ve bir tsconfig.json dosyası varsa (boş bir {} bile olsa) çalışmaya devam eder. Bu dosya yoksa ts-node, TypeScript 6'nın kullanımdan kaldırdığı node10 modül çözümlemesini içeren yerleşik varsayılanlara döner ve npx ts-node index.ts dosyayı çalıştırmadan ve hata yazdırmadan çıkar.

Deno ve Bun

İki çalışma ortamı da TypeScript'i birinci sınıf bir dosya tipi olarak ele alır:

deno run index.ts    # runs without checking
deno check index.ts  # type-checks, reports errors, runs nothing

bun index.ts         # runs without checking

İkisi de typescript kurulumuna veya bir tsconfig.json dosyasına ihtiyaç duymaz ve ikisi de enum ile silinemeyen diğer özellikleri destekler. Deno, deno check için TypeScript derleyicisinin kendi kopyasını içerir. Bun yalnızca tipleri siler; bu yüzden bir Bun projesinde tip hatalarını bulmak için yine typescript kurar ve tsc --noEmit çalıştırırsınız.

Tip Hataları Programı Yalnızca tsc ile Durdurur

Tip hatası olan bir programı çalıştırmayı yalnızca önce tsc çalıştıran yollar reddeder. Bu sayfadaki editör de onlardan biridir, bu yüzden bu blok derleyicide durur:

// This does not compile: the editor type-checks before it runs anything.
function area(width: number, height: number): number {
    return width * height;
}

console.log(area(3, "4"));

index.ts(6,21): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Aynı kod bir dosyaya kaydedilip node index.ts, npx tsx index.ts veya bun index.ts ile çalıştırılırsa çalışır ve 12 yazdırır, çünkü 3 * "4" string'i dönüştürür. Kodu daha hızlı bir araç çalıştırsa bile tsc --noEmit komutunu döngüde tutmanın nedeni budur:

{
    "scripts": {
        "dev": "tsx watch src/index.ts",
        "typecheck": "tsc --noEmit"
    }
}

Hangisini Kullanmalısınız?

• Öğrenme ya da hızlı bir deneme: bu sayfalardaki Run düğmesi veya playground.
• Güncel bir Node.js üzerinde bir betik ya da küçük bir araç: node index.ts, yapılandırmada erasableSyntaxOnly ile; böylece editör Node'un reddedeceği her şeyi işaretler.
• Her Node.js projesi, her sözdizimi: çalıştırmak için tsx, kontrol için tsc --noEmit.
• Bir kütüphane ya da yayınladığınız her şey: tsc, çünkü kullanıcılarınızın ihtiyaç duyduğu .d.ts dosyalarını da yazar.
• Frontend kodu: bundler'ınız veya framework'ünüz (Vite, Next.js, Angular CLI) TypeScript'i sizin için çalıştırır; kontrol için tsc --noEmit ekleyin.