TypeScript kompilieren: tsc und Transpilation verstehen

TypeScript-Code laeuft nicht direkt in Browsern oder in Node.js. Er muss zuerst in JavaScript uebersetzt werden. Diesen Prozess nennt man Transpilation. Der offizielle Compiler von TypeScript heisst tsc und ist das Fundament des gesamten TypeScript-Oekosystems.

Was macht tsc?

tsc uebernimmt zwei Aufgaben gleichzeitig: Typueberpruefung und Codegenerierung. Es liest TypeScript-Quelldateien, analysiert die Typen, meldet Fehler und erzeugt JavaScript-Ausgabedateien. Das macht tsc zum einzigen Tool, das TypeScript wirklich vollstaendig versteht.

Installation

tsc wird ueber das typescript-Paket installiert:

// Installation als Entwicklungsabhaengigkeit (empfohlen)
// npm install --save-dev typescript

// Globale Installation (fuer schnelle Experimente)
// npm install -g typescript

// Version pruefen:
// tsc --version

Erstes Kompilieren

Gegeben eine einfache TypeScript-Datei:

// hallo.ts
function begruessen(name: string): string {
  return "Hallo, " + name + "!";
}

console.log(begruessen("TypeScript"));

Der Befehl tsc hallo.ts erzeugt eine hallo.js-Datei im selben Verzeichnis:

// hallo.js (erzeugt von tsc)
function begruessen(name) {
  return "Hallo, " + name + "!";
}
console.log(begruessen("TypeScript"));

Die Typannotationen sind verschwunden, der Code ist sonst identisch. TypeScript ist ein “Zero-Cost”-System: Typen kosten zur Laufzeit nichts.

Kompilieren mit tsconfig.json

In echten Projekten gibt man keine einzelnen Dateien an, sondern verwendet eine tsconfig.json. Der einfache Aufruf tsc ohne Argumente sucht im aktuellen Verzeichnis nach dieser Konfigurationsdatei:

// Projekt kompilieren (liest tsconfig.json)
// tsc

// Spezifische tsconfig verwenden:
// tsc --project tsconfig.prod.json

// Nur Typueberpruefung ohne Dateiausgabe:
// tsc --noEmit

tsc --noEmit ist besonders nuetzlich im CI/CD-Prozess: Es prueft alle Typen, erzeugt aber keine JS-Dateien. So kann man sicherstellen, dass der Code korrekt typisiert ist, ohne den Build-Schritt zu wiederholen.

Watch-Modus fuer die Entwicklung

Waehrend der Entwicklung moechte man nicht nach jeder Aenderung manuell kompilieren. Der Watch-Modus loest das:

// Automatisch neu kompilieren bei Aenderungen:
// tsc --watch

// Oder kurz:
// tsc -w

tsc beobachtet alle eingeschlossenen Dateien und kompiliert bei jeder Aenderung automatisch nach. Fehler erscheinen sofort in der Konsole.

Ausgabeoptionen

tsc bietet viele Optionen fuer die Ausgabe:

// Alle wichtigen Ausgabeoptionen in der tsconfig.json:
//
// "outDir": "./dist"
// Wo die kompilierten JS-Dateien landen
//
// "declaration": true
// Zusaetzlich .d.ts-Typdeklarationsdateien erzeugen
//
// "declarationMap": true
// Source-Maps fuer .d.ts-Dateien (fuer Bibliotheks-Entwickler)
//
// "sourceMap": true
// Source-Maps fuer Debugging im Original-TypeScript
//
// "removeComments": true
// Kommentare aus der Ausgabe entfernen
//
// "noEmitOnError": true
// Keine Ausgabe bei Typfehlern (sichererer Build-Prozess)

Inkrementelles Bauen

Fuer grosse Projekte ist das inkrementelle Bauen wichtig. Mit "incremental": true in der tsconfig speichert tsc Informationen ueber den letzten Build und kompiliert nur geaenderte Teile:

// tsconfig.json mit inkrementellem Build:
// {
//   "compilerOptions": {
//     "incremental": true,
//     "tsBuildInfoFile": ".tsbuildinfo"
//   }
// }

Die .tsbuildinfo-Datei speichert den Build-Zustand und sollte nicht ins Repository eingecheckt werden.

Project References fuer Monorepos

Grosse Projekte mit mehreren Paketen profitieren von Project References:

// tsconfig.json im Root-Paket:
// {
//   "references": [
//     { "path": "./packages/core" },
//     { "path": "./packages/ui" }
//   ]
// }

// Dann kompilieren mit:
// tsc --build
// oder kurz:
// tsc -b

tsc --build beruecksichtigt Abhaengigkeiten zwischen Paketen und kompiliert nur das, was sich veraendert hat.

Moderne Alternativen zu tsc fuer den Build

tsc ist der Standard fuer Typueberpruefung, aber fuer den reinen Build-Schritt gibt es deutlich schnellere Alternativen:

// esbuild: Extrem schnell, in Go geschrieben
// npm install --save-dev esbuild
// esbuild src/index.ts --bundle --outfile=dist/bundle.js

// swc: Rust-basierter TypeScript-Transpiler
// npm install --save-dev @swc/core @swc/cli
// swc src -d dist

// Vite: Bundler mit integriertem TypeScript-Support (via esbuild)
// npm install --save-dev vite
// vite build

Diese Tools fuehren keine Typueberpruefung durch. Sie entfernen einfach die Typannotationen und erzeugen JavaScript. Deshalb kombinieren viele Teams tsc fuer Typueberpruefung und esbuild oder swc fuer den schnellen Build.

Typueberpruefung ohne Build

Das empfohlene Setup fuer moderne Projekte trennt Typueberpruefung und Build:

// package.json scripts:
// {
//   "scripts": {
//     "typecheck": "tsc --noEmit",
//     "build": "vite build",
//     "dev": "vite dev",
//     "ci": "npm run typecheck && npm run build"
//   }
// }

Im CI laeuft typecheck und build getrennt. Fehler in der Typueberpruefung brechen den CI ab, bevor der Build startet.

Debugging kompilierter Dateien

Mit Source-Maps kann der Browser oder Node.js Fehler auf den originalen TypeScript-Code zurueckfuehren, auch wenn nur JavaScript ausgefuehrt wird:

// sourceMap: true in tsconfig erzeugt .js.map-Dateien
// Diese enthalten das Mapping von kompiliertem JS zurueck zu TypeScript

// Node.js mit Source-Map-Unterstuetzung:
// node --enable-source-maps dist/index.js

TypeScript im Playground vs. lokale Kompilierung

Im Playground laeuft die TypeScript-Kompilierung im Browser und zeigt sofort den transpilierten JavaScript-Code. Dort kann man gut verstehen, was tsc aus TypeScript-Code macht. Fuer echte Projekte ist die lokale Installation mit einer tsconfig.json der richtige Weg.

Fazit

tsc ist das offizielle Werkzeug fuer TypeScript-Typueberpruefung und Kompilierung. Fuer Typueberpruefung im CI ist tsc --noEmit unverzichtbar. Fuer schnelle Builds in der Entwicklung koennen Tools wie esbuild oder Vite den Build-Schritt uebernehmen, waehrend tsc die Typen prueft. Das Verstaendnis der wichtigsten Optionen von tsc und deren Zusammenspiel mit der tsconfig.json ist eine wichtige Grundlage fuer jede TypeScript-Arbeit.