TypeScript ist im Kern ein einzelnes npm-Paket — typescript — und ein Kommandozeilen-Compiler namens tsc, der .ts-Dateien zu .js-Dateien übersetzt. Mehr brauchst du nicht, um loszulegen. Spannend wird es trotzdem an den Rändern: lokale oder globale Installation, welche Version dein Editor wirklich nutzt, wie du tsconfig.json initial erzeugst, und warum npx tsc fast immer die richtige Antwort ist. Dieser Artikel führt dich durch das Setup auf macOS, Linux und Windows, erklärt den Compiler in seinen wichtigsten Schaltern und zeigt, wie du Editor und Toolchain so verzahnst, dass keine Versionskonflikte entstehen.

01 · Abschnitt

Welche TypeScript-Version brauche ich?

TypeScript kennt kein offizielles LTS-Konzept. Stattdessen gilt eine klare, vorhersehbare Kadenz:

  • Neue Minor-Releases erscheinen etwa alle drei Monate, neue Hauptzyklen ungefähr alle sechs Monate (5.7, 5.8, 5.9, dann 6.0 usw.).
  • Zum Zeitpunkt dieses Artikels ist TypeScript 5.8 stable der empfohlene Release, 5.9 befindet sich im Release Candidate.
  • Microsoft pflegt grundsätzlich nur die jeweils aktuelle stable. Sicherheits-Backports auf ältere Linien sind die Ausnahme.

Empfehlung für Einsteiger: Installiere die aktuelle stabile Version. TypeScript ist über Minor-Versionen hinweg meist abwärtskompatibel; Breaking Changes betreffen vor allem präzisere Type-Checks, die bestehende Logik selten brechen, aber neue Fehler aufdecken können. Wer eine bestimmte Version pinnen muss, tut das ohnehin über die devDependencies in der package.json — dazu gleich.

02 · Abschnitt

Installation per npm (empfohlen)

Der offizielle und in 99% der Fälle richtige Weg ist die Installation als dev dependency in deinem Projekt. Voraussetzung ist eine funktionierende Node.js-Installation samt npm — typischerweise Node 20 LTS oder neuer.

bash terminal 
# Im Projektordner
npm init -y
npm install --save-dev typescript

Das schreibt einen Eintrag wie diesen in deine package.json:

json package.json 
{
  "name": "mein-projekt",
  "version": "1.0.0",
  "devDependencies": {
    "typescript": "^5.8.2"
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "watch": "tsc --watch"
  }
}

Warum lokal und nicht global?

  • Reproduzierbare Builds: Jeder im Team — und jede CI-Pipeline — nutzt automatisch genau die Version, die in der package.json steht.
  • Mehrere Projekte parallel: Projekt A kann auf 5.4 festgenagelt sein, Projekt B auf 5.8 laufen, ohne dass du irgendwas umschalten musst.
  • Keine PATH-Probleme: Du brauchst keine globalen Binaries.

Aufgerufen wird der Compiler dann über npx, der automatisch das lokale ./node_modules/.bin/tsc findet:

bash terminal 
npx tsc --version
Output 
Version 5.8.2

Globale Installation — der Sonderfall:

bash terminal 
npm install -g typescript

Praktisch für schnelle Spielereien außerhalb eines Projekts (tsc spiel.ts), für seriöse Projekt-Arbeit aber nicht zu empfehlen. Eine globale tsc-Version ist eine Quelle stiller Drift: dein Kollege baut mit 5.6, du mit 5.8, und plötzlich verhalten sich die Type-Checks unterschiedlich.

02b · Abschnitt

Alternative: Bun, Deno, pnpm

npm ist nicht der einzige Weg. Es gibt mehrere ausgereifte Alternativen, die TypeScript entweder verteilen oder direkt verstehen:

  • pnpm und yarn sind drop-in-Ersatz für npm: pnpm add -D typescript bzw. yarn add --dev typescript. Funktional identisch, schneller bzw. mit Workspaces-Vorteilen.
  • Bun bringt einen eigenen TypeScript-Loader mit und führt .ts-Dateien direkt aus — ohne separaten tsc-Schritt. bun run skript.ts funktioniert ohne Setup.
  • Deno kann TypeScript ebenfalls nativ ausführen und nutzt intern eine eigene TS-Toolchain.

Für klassisches Web- und Backend-Tooling bleibt npm + lokales typescript-Paket der pragmatische Default. Bun und Deno sind hervorragend für neue Projekte ohne Legacy-Last — aber das ist Thema eigener Artikel.

03 · Abschnitt

Der tsc-Compiler

tsc ist das Kernstück: ein in TypeScript geschriebener Compiler, der .ts/.tsx-Dateien einliest, typcheckt und nach JavaScript transpiliert. Was er konkret tut:

  1. Parsen: Quellcode in einen AST überführen.
  2. Type-Checking: Statische Typprüfung gegen Annotationen und Inferenz.
  3. Emit: JavaScript-Output erzeugen (Default) oder unterdrücken (--noEmit).

Einzelne Datei kompilieren:

bash terminal 
npx tsc hallo.ts

Das erzeugt hallo.js direkt neben der Eingabe-Datei. Praktisch zum Ausprobieren, in echten Projekten arbeitest du immer mit tsconfig.json.

Projekt initialisieren:

bash terminal 
npx tsc --init

Das generiert eine ausführlich kommentierte tsconfig.json mit sinnvollen Defaults (strict: true, target: es2016, module: commonjs etc.). Anschließend reicht ein nacktes npx tsc — der Compiler findet die Config automatisch.

Wichtige Flags im Überblick:

FlagZweck
--initErzeugt eine tsconfig.json mit Defaults und Kommentaren.
--watch (-w)Beobachtet Dateien und re-compiliert bei Änderungen.
--noEmitNur Type-Checken, keine .js-Dateien schreiben.
--targetJS-Sprachversion des Outputs (es2020, es2022, esnext ...).
--outDirZiel-Ordner für emittierte Dateien, z. B. ./dist.
--strictAktiviert alle strikten Type-Checks. Default bei tsc --init.
--versionDruckt die aktive Compiler-Version.
--project (-p)Pfad zu einer Config-Datei oder einem Ordner mit tsconfig.json.

Typische Aufrufe:

bash terminal 
# Einmaliger Build gegen tsconfig.json
npx tsc

# Watch-Mode für die Entwicklung
npx tsc --watch

# Nur Type-Check, ohne JS-Output (z. B. in CI)
npx tsc --noEmit

# Mehrere tsconfigs in einem Monorepo
npx tsc -p packages/api/tsconfig.json
04 · Abschnitt

Editor-Integration

TypeScript bringt einen eigenen Language Server mit (tsserver), der Autocomplete, Hover-Infos, Goto-Definition, Refactorings und Inline-Diagnostics liefert. Jeder ernsthafte Editor spricht dieses Protokoll.

Visual Studio Code:

VS Code enthält eine eigene TypeScript-Version ab Werk — angenehm, weil sofort funktional, gleichzeitig eine Stolperfalle, weil sie oft nicht zur Projekt-Version passt. Lösung: Workspace-Setting setzen.

jsonc .vscode/settings.json 
{
  // Nutzt die TypeScript-Version aus node_modules statt der eingebauten
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

In der Status-Leiste (unten rechts beim Öffnen einer .ts-Datei) kannst du außerdem mit Klick auf die Versionsnummer zwischen „VS Code's Version" und „Workspace Version" umschalten.

WebStorm / IntelliJ:

JetBrains-IDEs erkennen die lokale Version automatisch, sofern typescript in den devDependencies steht. Unter Settings → Languages & Frameworks → TypeScript lässt sich die genutzte Toolchain explizit setzen.

Neovim:

Mit nvim-lspconfig und typescript-language-server (oder dem neueren vtsls) als LSP-Backend. Für Formatierung dazu prettier oder dprint über conform.nvim.

Faustregel: Egal welcher Editor — die TypeScript-Version, mit der dein Editor checkt, sollte mit der Version aus node_modules identisch sein. Sonst zeigt der Editor Fehler, die tsc nicht meldet (oder umgekehrt).

05 · Abschnitt

Häufige Probleme beim Setup

tsc: command not found:

Tritt fast immer bei globaler Installation auf, wenn das npm-Global-Bin-Verzeichnis nicht im PATH ist. Prüfen mit:

bash terminal 
npm config get prefix
Output 
/usr/local

Das bin-Unterverzeichnis dieses Pfads muss im PATH stehen (/usr/local/bin im Beispiel). Bei lokaler Installation umgehst du das Problem komplett, indem du npx tsc oder ./node_modules/.bin/tsc aufrufst.

Editor zeigt andere Fehler als tsc:

Klassiker. VS Code nutzt die eingebaute TS-Version, dein Projekt eine andere. Lösung wie oben: typescript.tsdk setzen und in der Status-Leiste „Workspace Version" wählen.

Cannot find module 'typescript':

Du rufst tsc lokal auf, aber node_modules fehlt oder ist veraltet. Heilung:

bash terminal 
rm -rf node_modules package-lock.json
npm install

Alter Build-Cache:

tsc --incremental legt eine .tsbuildinfo-Datei an, die unter ungünstigen Umständen veraltete Type-Informationen einfriert. Wenn Fehler unerklärlich auftauchen oder verschwinden:

bash terminal 
npx tsc --build --clean
# oder manuell
rm -f tsconfig.tsbuildinfo

Mehrere TS-Versionen auf einem System:

Globales tsc (z. B. 5.6), Projekt-tsc (5.8), VS-Code-internes tsc (5.7) — drei Versionen, drei Verhaltensweisen. Konsequent über npx aufrufen und die Editor-Version aufs Workspace pinnen, dann gibt es nur eine Wahrheit.

06 · Abschnitt

Häufige Stolperfallen

Globale vs. lokale Installation — lokal ist die Norm.

Viele alte Tutorials zeigen npm install -g typescript als ersten Schritt. Für ernsthafte Projekte ist das ein Anti-Pattern: jedes Team-Mitglied hat dann eine potenziell andere Version, CI baut mit einer dritten. Lokal als devDependency installieren und mit npx tsc aufrufen — fertig. Global nur für Wegwerf-Spielereien.

VS Code nutzt eigene TS-Version, nicht zwangsläufig die im node_modules.

VS Code bringt einen eigenen TypeScript-Server mit. Solange du nicht typescript.tsdk setzt und in der Status-Leiste auf „Workspace Version" umschaltest, kann der Editor andere Fehler anzeigen als tsc im Terminal — besonders schmerzhaft bei neuen Sprachfeatures, die in der gebundelten Version noch fehlen.

npx tsc vs. ./node_modules/.bin/tsc.

Beides ruft den lokalen Compiler auf, npx ist nur der bequemere Weg und funktioniert plattformübergreifend. Achtung: npx tsc ohne lokale Installation lädt eine Version aus dem Cache nach (oder die neueste vom Registry) — kann unerwartet zu falscher Version führen. Immer erst npm install --save-dev typescript.

Mehrere TS-Versionen auf einem System.

Global, Projekt-lokal, Editor-intern — drei Quellen, drei mögliche Versionen. Konsequent über die lokale Projekt-Version arbeiten, Editor mit typescript.tsdk auf node_modules/typescript/lib zeigen lassen, globale Installation nach Möglichkeit ganz vermeiden.

tsconfig.json automatisch via tsc --init generieren.

Von Hand schreiben ist unnötig und fehleranfällig. npx tsc --init erzeugt eine vollständig kommentierte tsconfig.json mit aktuellen Defaults (strict: true ist gesetzt). Anschließend nur das anpassen, was du wirklich brauchst — den Rest stehen lassen, damit zukünftige TS-Versionen mit ihren Defaults wachsen können.

Falsches target führt zu fehlenden Lib-Typen.

Setzt du target: es5 in der tsconfig.json, fehlen automatisch Typdefinitionen für moderne Built-ins wie Promise, Map, Set oder Array.prototype.includes. Lösung: lib explizit setzen (z. B. ["es2020", "dom"]) oder gleich ein modernes target wie es2020/es2022 wählen.

.tsbuildinfo-Cache hält veraltete Diagnosen fest.

Bei aktiviertem incremental- oder Project-References-Build cached tsc Build-Informationen in tsconfig.tsbuildinfo. Nach größeren Refactorings oder Versionswechseln kann dieser Cache veraltete Fehler einfrieren. npx tsc --build --clean oder die Datei manuell löschen, dann neu bauen.

Weiterführende Ressourcen

Externe Quellen

/ Weiter

Zurück zu Grundlagen

Zur Übersicht