TypeScript installieren mit npm und Version prüfen

TypeScript ist ein npm-Paket namens typescript. Installiere es in dein Projekt und prüfe, ob es funktioniert:

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

Das Paket stellt den Befehl tsc bereit, den TypeScript-Compiler. Zum Installieren brauchst du Node.js und npm (das mit Node.js mitkommt). Node.js bekommst du von nodejs.org oder über den Paketmanager deines Systems, und mit node --version prüfst du es.

Um TypeScript auszuprobieren, musst du nichts installieren. Dieser Block wird in deinem Browser kompiliert und ausgeführt:

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

TypeScript in einem Projekt installieren

Empfohlen ist die lokale Installation, als Dev-Dependency des Projekts:

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript (Kurzform npm i -D typescript) legt den Compiler in node_modules ab und trägt ihn in package.json ein:

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

Es ist eine Dev-Dependency, weil der Compiler nur zum Bauen des Codes gebraucht wird, nicht zum Ausführen. Wer das Projekt klont und npm install ausführt, bekommt dieselbe Compiler-Version.

Um den lokalen Compiler aufzurufen, stellst du npx davor. Es sucht Befehle in node_modules/.bin:

npx tsc --version

In den Skripten von package.json kannst du tsc ohne npx schreiben, weil npm für Skripte node_modules/.bin zum PATH hinzufügt:

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

Dann kompiliert npm run build, und npm run typecheck prüft die Typen, ohne Dateien zu schreiben.

Die TypeScript-Version prüfen

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

Wenn npx tsc --version und tsc --version unterschiedliche Versionen ausgeben, hat das Projekt einen eigenen Compiler, und der globale ist älter oder neuer. Für den Build des Projekts zählt die Version des Projekts.

TypeScript global installieren

Eine globale Installation gibt dir in jedem Terminal einen tsc-Befehl, ohne npx:

npm install -g typescript
tsc --version

Unter macOS und Linux kann das mit EACCES-Berechtigungsfehlern scheitern, wenn Node.js systemweit installiert wurde. Installierst du Node.js über einen Versionsmanager wie nvm oder fnm, tritt das nicht auf. Von sudo npm install -g wird abgeraten.

Nimm den globalen Befehl für schnelle Experimente. Für ein echtes Projekt behältst du zusätzlich eine lokale Installation: Dann hält package.json die Version fest, und ein Update des globalen Compilers kann nicht ändern, wie das Projekt gebaut wird.

Installieren mit pnpm, Yarn oder Bun

Jeder JavaScript-Paketmanager installiert dasselbe Paket:

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

Den Compiler rufst du mit pnpm tsc, yarn tsc oder bunx tsc auf.

Eine tsconfig.json mit tsc --init anlegen

Eine tsconfig.json markiert einen Ordner als TypeScript-Projekt und enthält die Compiler-Optionen. So erzeugst du eine:

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

Die erzeugte Datei (TypeScript 7) schaltet strict und ein paar weitere Prüfungen ein, verwendet "module": "nodenext" und "target": "esnext" und enthält auskommentierte Zeilen für rootDir und outDir. Kommentiere diese beiden ein, damit der Compiler aus src liest und nach dist schreibt:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

Das ist eine gekürzte Ansicht; die echte Datei hat mehr Optionen, jede mit einem Kommentar. Die tsconfig-Seite erklärt, was sie bewirken. Führst du npx tsc --init im selben Ordner erneut aus, scheitert es mit error TS5054: A 'tsconfig.json' file is already defined, deine Einstellungen werden also nie überschrieben.

Die erste Datei kompilieren

Lege src/index.ts an:

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

Dann kompilieren und ausführen:

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

npx tsc ohne Argumente liest tsconfig.json, prüft die Typen jeder eingeschlossenen Datei und schreibt die Ausgabe nach dist. Mit den erzeugten Einstellungen bekommst du index.js sowie für jede Datei index.d.ts (Typdeklarationen) und .map-Dateien (Source Maps).

Zwei Dinge solltest du über die Ausgabe wissen:

• Typfehler verhindern die Ausgabe standardmäßig nicht. tsc meldet die Fehler, beendet sich mit einem Exit-Code ungleich null und schreibt das JavaScript trotzdem. Setze "noEmitOnError": true, damit nichts geschrieben wird, solange es Fehler gibt.
• Wenn eine tsconfig.json existiert, übergib keine Dateinamen. npx tsc src/index.ts scheitert mit error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Führe einfach npx tsc aus, oder ergänze --ignoreConfig, wenn du wirklich eine einzelne Datei mit den Standardeinstellungen kompilieren willst.

Watch-Modus

--watch (kurz -w) lässt den Compiler weiterlaufen und kompiliert neu, sobald sich eine Datei ändert:

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

Lass ihn in einem Terminal neben deinem Editor offen. Beenden kannst du ihn mit Strg+C.

Eine bestimmte TypeScript-Version installieren

Schreibe die Version nach @:

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6 ist die letzte Version, deren Compiler in JavaScript geschrieben ist. Manche Tools, die die JavaScript-API des Compilers aufrufen, brauchen ihn noch. Das behandelt die Seite zu TypeScript 7, zusammen mit dem Upgrade.

Editor einrichten

VS Code bringt TypeScript-Unterstützung mit: Öffne eine .ts-Datei, und du bekommst Fehlerunterstreichungen, Autovervollständigung, Typen beim Hovern und Umbenennen, ohne etwas zu installieren. Für die Geschwindigkeit von TypeScript 7 im Editor veröffentlicht das TypeScript-Team eine eigene Erweiterung, die VS Code auf den nativen Language Server von TypeScript 7 umstellt. WebStorm und die anderen JetBrains-IDEs unterstützen TypeScript direkt, und Neovim, Vim, Emacs, Zed und Sublime Text nutzen einen TypeScript-Language-Server über ihre LSP-Unterstützung.

Häufige Installationsfehler

This is not the tsc command you are looking for. Du hast npx tsc in einem Ordner ohne installiertes TypeScript ausgeführt, und npx hat ein veraltetes Paket geholt, das zufällig tsc heißt. Installiere das richtige mit npm install --save-dev typescript.

tsc: command not found, oder unter Windows 'tsc' is not recognized as an internal or external command. TypeScript ist nicht global installiert, oder der globale npm-Ordner liegt nicht in deinem PATH. Nutze npx tsc in einem Projekt mit lokaler Installation, oder installiere global und öffne ein neues Terminal.

error TS2591: Cannot find name 'process' (oder require; __dirname ergibt TS2304). Die Typen der Node.js-eigenen APIs stecken in einem separaten Paket. Installiere es mit npm install --save-dev @types/node und ergänze dann "types": ["node"] in compilerOptions: TypeScript 7 lädt nicht mehr automatisch jedes installierte @types-Paket.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Deine Dateien liegen in src, und du hast outDir gesetzt, aber nicht rootDir. Ergänze "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y schreibt "type": "commonjs" in package.json, also behandelt die Konfiguration von tsc --init ("module": "nodenext" mit verbatimModuleSyntax) jede .ts-Datei als CommonJS, wo import und export nicht erlaubt sind. Ändere es auf "type": "module" und schreibe relative Imports mit der Endung .js: import { add } from "./math.js".