TypeScript-Datei ausführen: tsc, Node.js, tsx, ts-node

Eine TypeScript-Datei lässt sich nicht so, wie sie ist, ausführen, weil Browser und JavaScript-Engines keine Typannotationen verstehen. Irgendetwas muss die Typen vorher entfernen. Das ist entweder der TypeScript-Compiler (tsc), der die Typen dabei auch prüft, oder ein schnelleres Tool, das sie nur entfernt. Am schnellsten führst du den Code auf dieser Seite mit dem Run-Button aus:

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

Ausgabe:

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

Jeder ausführbare Block in dieser Dokumentation funktioniert gleich: TypeScript 7 prüft den Code mit eingeschaltetem strict, und er läuft nur, wenn es keine Typfehler gibt. Für längere Experimente ist der TypeScript-Playground derselbe Editor auf einer eigenen Seite. Der Rest dieser Seite behandelt das Ausführen von .ts-Dateien auf deinem eigenen Rechner.

Die Optionen im Überblick

Die Spalte, die viele überrascht, ist die erste: Die meisten schnellen Optionen führen Code aus, der Typfehler enthält. Ein typisches Projekt führt Code mit einer davon aus und startet tsc --noEmit separat, im Editor und in der CI, um die Fehler zu finden.

Mit tsc kompilieren, dann mit Node ausführen

Dieser Ansatz funktioniert überall und prüft alles. Mit TypeScript im Projekt und einer tsconfig.json, die "rootDir": "./src" und "outDir": "./dist" setzt:

npx tsc
node dist/index.js

tsc prüft die Typen aller Dateien und schreibt dann .js-Dateien nach dist. Für eine einzelne Datei ohne Projekt übergibst du den Dateinamen. Dann werden die Standardoptionen verwendet, und index.js landet neben index.ts:

npx tsc index.ts
node index.js

(Hat der Ordner eine tsconfig.json, lehnt tsc Dateinamen mit error TS5112 ab; führe einfach npx tsc aus oder ergänze --ignoreConfig.)

Standardmäßig schreibt tsc das JavaScript auch dann, wenn es Typfehler gibt, node kann also ein Programm ausführen, das die Prüfung nicht bestanden hat. Ergänze "noEmitOnError": true in der Konfiguration, um das zu verhindern, oder verkette die Befehle in einem Skript, sodass der zweite Schritt nur läuft, wenn der erste erfolgreich war:

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

Für die Entwicklung kompiliert npx tsc --watch bei jedem Speichern neu.

TypeScript direkt mit Node.js ausführen

Aktuelle Node.js-Versionen führen .ts-Dateien selbst aus:

node index.ts

Node entfernt die Typannotationen, ersetzt sie durch Leerzeichen, damit die Zeilennummern in Stacktraces weiter stimmen, und führt aus, was übrig bleibt. Das ist seit Node.js 23.6.0 und 22.18.0 standardmäßig aktiv, gibt seit 24.3.0 und 22.18.0 keine Warnung mehr aus und wurde in Node.js 24.12.0 und 25.2.0 als stabil markiert. Ältere Versionen mit dieser Funktion (22.6 bis 22.17 sowie 23.0 bis 23.5) brauchen das Flag: node --experimental-strip-types index.ts.

Dabei gelten vier Regeln:

• Keine Typprüfung. Eine Datei mit const age: number = "forty" läuft und gibt forty aus.
• Nur entfernbare Syntax. Alles, was zu JavaScript-Code werden muss, statt einfach zu verschwinden, wird abgelehnt: enum, namespace-Blöcke mit Laufzeitcode, Parameter Properties im Konstruktor wie constructor(private name: string) und Aliase mit import x = require(). Node bricht ab mit SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.
• tsconfig.json wird ignoriert. Optionen wie paths oder target haben keine Wirkung.
• Imports brauchen echte Dateinamen. Schreibe import { add } from "./math.ts" mit Endung und markiere reine Typ-Imports mit type: import { add, type Pair } from "./math.ts". Ohne type sucht Node nach einem Laufzeit-Export namens Pair und scheitert mit SyntaxError: The requested module './math.ts' does not provide an export named 'Pair'.

Zwei Compiler-Optionen lassen tsc dieselben Regeln durchsetzen, sodass der Editor dich warnt, bevor Node es tut: "erasableSyntaxOnly": true meldet bei einem enum den Fehler error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled., und "verbatimModuleSyntax": true verlangt das Schlüsselwort type bei reinen Typ-Imports. Um weiter .ts-Endungen in Imports zu schreiben und trotzdem mit tsc zu kompilieren, ergänze "rewriteRelativeImportExtensions": true. Das macht in der Ausgabe aus ./math.ts ein ./math.js.

Node.js 24 hat außerdem --experimental-transform-types, das für Enums und Parameter Properties Code erzeugt, statt sie abzulehnen. Es gibt eine ExperimentalWarning aus, und Node.js 26 hat das Flag entfernt, also bau nicht darauf.

Dieser Block nutzt zwei Features, die node index.ts ablehnt. Hier läuft er, weil der Editor ihn mit dem TypeScript-Compiler kompiliert, der für beide JavaScript erzeugt:

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

Die entfernbare Variante desselben Codes nutzt ein const-Objekt und ein gewöhnliches Feld, die Node direkt ausführen kann:

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 führt eine TypeScript-Datei in einem Schritt aus, ohne Konfiguration und ohne Einschränkungen bei der Syntax:

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

Es transformiert den Code mit esbuild, also funktionieren Enums, Namespaces und Parameter Properties, und Imports ohne Endung werden so aufgelöst wie in einem Bundler. Wie das Type Stripping von Node prüft es keine Typen. Es ist die übliche Wahl für Skripte, Dev-Server und Tests auf Node.js-Versionen ohne Type Stripping, oder wenn der Code Syntax nutzt, die Node ablehnt.

ts-node

ts-node war jahrelang der Standardweg, TypeScript auf Node.js auszuführen, und viele Tutorials und ältere Projekte verwenden es noch (npx ts-node index.ts, node -r ts-node/register). Es prüft standardmäßig die Typen und nutzt dafür die JavaScript-API des TypeScript-Compilers.

Genau diese API liefert TypeScript 7 nicht mit: Sein Compiler ist ein natives Programm, und das Paket typescript 7 stellt JavaScript keine Compiler-API bereit. Mit installiertem TypeScript 7 stürzt ts-node ab, bevor es irgendetwas ausführt:

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

Die neueste Version von ts-node, 10.9.2, stammt vom Dezember 2023. Für neuen Code nimm tsx oder node index.ts. Ein bestehendes Setup, das von ts-node abhängt, funktioniert weiter, wenn das Projekt bei TypeScript 6 bleibt (npm install --save-dev typescript@6) und eine tsconfig.json hat, und sei es ein leeres {}. Ohne eine solche Datei greift ts-node auf eingebaute Standardwerte zurück, zu denen die Modulauflösung node10 gehört, die TypeScript 6 als veraltet markiert hat, und npx ts-node index.ts beendet sich, ohne die Datei auszuführen oder einen Fehler auszugeben.

Deno und Bun

Beide Laufzeitumgebungen behandeln TypeScript als vollwertigen Dateityp:

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

bun index.ts         # runs without checking

Keine der beiden braucht ein installiertes typescript oder eine tsconfig.json, und beide unterstützen enum und die anderen nicht entfernbaren Features. Deno bringt für deno check eine eigene Kopie des TypeScript-Compilers mit. Bun entfernt nur Typen, in einem Bun-Projekt installierst du also trotzdem typescript und führst tsc --noEmit aus, um Typfehler zu finden.

Nur tsc hält ein Programm mit Typfehlern an

Nur die Wege, die zuerst tsc ausführen, verweigern ein Programm mit Typfehlern. Der Editor auf dieser Seite ist einer davon, also bleibt dieser Block beim Compiler hängen:

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

Als Datei gespeichert und mit node index.ts, npx tsx index.ts oder bun index.ts ausgeführt, läuft derselbe Code und gibt 12 aus, weil 3 * "4" den String umwandelt. Deshalb gehört tsc --noEmit in den Ablauf, auch wenn ein schnelleres Tool den Code ausführt:

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

Welchen Weg solltest du nehmen?

• Zum Lernen oder für einen schnellen Test: den Run-Button auf diesen Seiten oder den Playground.
• Ein Skript oder kleines Tool auf aktuellem Node.js: node index.ts, mit erasableSyntaxOnly in der Konfiguration, damit der Editor alles markiert, was Node ablehnen würde.
• Jedes Node.js-Projekt, jede Syntax: tsx zum Ausführen, tsc --noEmit zum Prüfen.
• Eine Bibliothek oder alles, was du veröffentlichst: tsc, weil es auch die .d.ts-Dateien schreibt, die deine Nutzer brauchen.
• Frontend-Code: Dein Bundler oder Framework (Vite, Next.js, Angular CLI) führt das TypeScript für dich aus; ergänze tsc --noEmit für die Prüfung.