Jak uruchomić plik TypeScript: tsc, Node.js, tsx, ts-node

Pliku TypeScript nie da się uruchomić w takiej postaci, bo przeglądarki i silniki JavaScript nie rozumieją adnotacji typów. Coś musi najpierw usunąć typy. Tym czymś jest albo kompilator TypeScript (tsc), który przy okazji sprawdza typy, albo szybsze narzędzie, które tylko je wycina. Najszybszy sposób na uruchomienie kodu z tej strony to przycisk Run:

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}`);
}

Wynik:

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

Każdy uruchamialny blok w tej dokumentacji działa tak samo: kod jest sprawdzany przez TypeScript 7 z włączonym strict i uruchamia się tylko wtedy, gdy nie ma błędów typów. Do dłuższych eksperymentów służy edytor online TypeScript, ten sam edytor na osobnej stronie. Reszta tej strony dotyczy uruchamiania plików .ts na własnym komputerze.

Opcje w skrócie

Najbardziej zaskakuje pierwsza kolumna: większość szybkich opcji uruchamia kod, w którym są błędy typów. Typowy projekt uruchamia kod jednym z nich, a osobno, w edytorze i w CI, puszcza tsc --noEmit, żeby wyłapać błędy.

Kompilacja przez tsc, potem uruchomienie w Node

To podejście działa wszędzie i sprawdza wszystko. Z TypeScriptem zainstalowanym w projekcie i tsconfig.json, który ustawia "rootDir": "./src" i "outDir": "./dist":

npx tsc
node dist/index.js

tsc sprawdza typy we wszystkich plikach, a potem zapisuje pliki .js w dist. Dla pojedynczego pliku bez projektu przekaż nazwę pliku. Wtedy używane są domyślne opcje, a index.js powstaje obok index.ts:

npx tsc index.ts
node index.js

(Jeśli w folderze jest tsconfig.json, tsc odrzuca nazwy plików z error TS5112; uruchom samo npx tsc albo dodaj --ignoreConfig.)

Domyślnie tsc zapisuje JavaScript nawet wtedy, gdy są błędy typów, więc node może uruchomić program, który nie przeszedł sprawdzenia. Dodaj "noEmitOnError": true do konfiguracji, żeby temu zapobiec, albo połącz polecenia w skrypcie, tak by drugi krok uruchamiał się tylko po udanym pierwszym:

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

Podczas pracy npx tsc --watch kompiluje ponownie przy każdym zapisie.

Uruchamianie TypeScript bezpośrednio w Node.js

Aktualne Node.js samo uruchamia pliki .ts:

node index.ts

Node wycina adnotacje typów, zastępując je białymi znakami, żeby numery linii w stack trace'ach nadal się zgadzały, i uruchamia to, co zostaje. Jest to włączone domyślnie od Node.js 23.6.0 i 22.18.0, nie wypisuje ostrzeżenia od 24.3.0 i 22.18.0, a jako stabilne zostało oznaczone w Node.js 24.12.0 i 25.2.0. Wcześniejsze wersje, które mają tę funkcję (od 22.6 do 22.17 oraz od 23.0 do 23.5), potrzebują flagi: node --experimental-strip-types index.ts.

Wiążą się z tym cztery zasady:

• Brak sprawdzania typów. Plik z const age: number = "forty" się uruchamia i wypisuje forty.
• Tylko składnia, którą da się usunąć. Wszystko, co musi stać się kodem JavaScript, a nie zniknąć, zostaje odrzucone: enum, bloki namespace z kodem wykonywalnym, parameter properties w konstruktorze, takie jak constructor(private name: string), i aliasy import x = require(). Node zatrzymuje się z SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.
• tsconfig.json jest ignorowany. Opcje takie jak paths czy target nie mają wpływu.
• Importy wymagają prawdziwych nazw plików. Pisz import { add } from "./math.ts", z rozszerzeniem, i oznaczaj importy samych typów przez type: import { add, type Pair } from "./math.ts". Bez type Node szuka eksportu wykonywalnego o nazwie Pair i kończy się błędem SyntaxError: The requested module './math.ts' does not provide an export named 'Pair'.

Dwie opcje kompilatora sprawiają, że tsc egzekwuje te same zasady, więc edytor ostrzega cię, zanim zrobi to Node: "erasableSyntaxOnly": true zgłasza error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. przy enum, a "verbatimModuleSyntax": true wymaga słowa type przy importach samych typów. Aby dalej pisać rozszerzenia .ts w importach i nadal kompilować przez tsc, dodaj "rewriteRelativeImportExtensions": true, co w wyniku zamienia ./math.ts na ./math.js.

Node.js 24 ma też --experimental-transform-types, które generuje kod dla enumów i parameter properties zamiast je odrzucać. Wypisuje ExperimentalWarning, a Node.js 26 usunął tę flagę, więc nie opieraj się na niej.

Ten blok używa dwóch funkcji, które node index.ts odrzuca. Tutaj działa, bo edytor kompiluje go kompilatorem TypeScript, który generuje JavaScript dla obu:

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

Wersja tego samego kodu, którą da się wyczyścić z typów, używa obiektu const i zwykłego pola, co Node może uruchomić bez zmian:

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 uruchamia plik TypeScript w jednym kroku, bez konfiguracji i bez ograniczeń składni:

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

Przekształca kod przez esbuild, więc enumy, namespace'y i parameter properties działają, a importy bez rozszerzeń są rozwiązywane tak jak w bundlerze. Podobnie jak type stripping w Node, nie sprawdza typów. To popularny wybór dla skryptów, serwerów deweloperskich i testów na wersjach Node.js sprzed type strippingu albo gdy kod używa składni, którą Node odrzuca.

ts-node

ts-node przez lata był standardowym sposobem uruchamiania TypeScriptu w Node.js i nadal używa go wiele tutoriali i starszych projektów (npx ts-node index.ts, node -r ts-node/register). Domyślnie sprawdza typy, korzystając z JavaScriptowego API kompilatora TypeScript.

Tego właśnie API TypeScript 7 nie dostarcza: jego kompilator to natywny program, a pakiet typescript 7 nie udostępnia JavaScriptowi żadnego API kompilatora. Z zainstalowanym TypeScript 7 ts-node wywala się, zanim cokolwiek uruchomi:

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

Najnowsze wydanie ts-node, 10.9.2, pochodzi z grudnia 2023. W nowym kodzie używaj tsx lub node index.ts. Istniejąca konfiguracja oparta na ts-node działa dalej, jeśli projekt zostaje przy TypeScript 6 (npm install --save-dev typescript@6) i ma tsconfig.json, nawet pusty {}. Bez niego ts-node wraca do wbudowanych ustawień domyślnych, które zawierają rozwiązywanie modułów node10 oznaczone przez TypeScript 6 jako przestarzałe, i npx ts-node index.ts kończy działanie bez uruchomienia pliku i bez wypisania błędu.

Deno i Bun

Oba środowiska traktują TypeScript jako pełnoprawny typ pliku:

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

bun index.ts         # runs without checking

Żadne nie wymaga zainstalowanego typescript ani tsconfig.json i oba obsługują enum oraz inne funkcje, których nie da się po prostu usunąć. Deno dostarcza własną kopię kompilatora TypeScript dla deno check. Bun tylko wycina typy, więc w projekcie Bun nadal instalujesz typescript i uruchamiasz tsc --noEmit, żeby znaleźć błędy typów.

Błędy typów zatrzymują program tylko z tsc

Tylko ścieżki, które najpierw uruchamiają tsc, odmawiają uruchomienia programu z błędami typów. Edytor na tej stronie jest jedną z nich, więc ten blok zatrzymuje się na kompilatorze:

// 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'.

Zapisany jako plik i uruchomiony przez node index.ts, npx tsx index.ts lub bun index.ts, ten sam kod działa i wypisuje 12, bo 3 * "4" konwertuje string. Dlatego warto trzymać tsc --noEmit w obiegu, nawet gdy kod uruchamia szybsze narzędzie:

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

Którego użyć?

• Nauka albo szybki test: przycisk Run na tych stronach albo edytor online.
• Skrypt lub małe narzędzie na aktualnym Node.js: node index.ts, z erasableSyntaxOnly w konfiguracji, żeby edytor oznaczał wszystko, co Node by odrzucił.
• Dowolny projekt Node.js, dowolna składnia: tsx do uruchamiania, tsc --noEmit do sprawdzania.
• Biblioteka lub cokolwiek, co publikujesz: tsc, bo generuje też pliki .d.ts potrzebne twoim użytkownikom.
• Kod front-endowy: twój bundler lub framework (Vite, Next.js, Angular CLI) uruchamia TypeScript za ciebie; dodaj tsc --noEmit do sprawdzania.