tsconfig.json erklaert: TypeScript richtig konfigurieren

Die tsconfig.json ist das Herzstuck jedes TypeScript-Projekts. Sie steuert, welche Dateien der Compiler verarbeitet, welche JavaScript-Version erzeugt wird und wie strikt die Typueberpruefung ist. Das Verstaendnis dieser Datei ist entscheidend fuer ein stabiles und wartbares Projekt.

Grundstruktur

Eine minimale tsconfig.json sieht so aus:

// tsconfig.json (JSON mit Kommentaren erlaubt)

In der Praxis ist es eine JSON-Datei mit der Endung .json, in der Kommentare erlaubt sind (JSON5-Superset). Hier eine typische Konfiguration fuer eine Node.js-Anwendung:

// Beispiel: Inhalt einer tsconfig.json
// {
//   "compilerOptions": {
//     "target": "ES2022",
//     "module": "NodeNext",
//     "strict": true,
//     "outDir": "./dist",
//     "rootDir": "./src"
//   },
//   "include": ["src/**/*"],
//   "exclude": ["node_modules", "dist"]
// }

Da die tsconfig keine TypeScript-Datei ist, zeige ich die Optionen im Text.

compilerOptions: Das Kernfeld

target: Welches JavaScript erzeugt wird

Die target-Option legt fest, fuer welche JavaScript-Version der Compiler optimiert:

// Haufige Werte:
// "ES5"     - Breite Browser-Kompatibilitaet, aelterer Code
// "ES2020"  - Modernes JavaScript, weitgehend unterstuetzt
// "ES2022"  - Top-Level await, private Klassenfelder
// "ESNext"  - Neueste Features, erfordert aktuelle Laufzeit

Fuer Node.js-Projekte empfiehlt sich ES2022 oder hoeher. Fuer Browser-Bibliotheken haengt es von der Zielgruppe ab.

module: Modulformat

Die module-Option bestimmt, wie Imports und Exports ausgegeben werden:

// "CommonJS"  - require/module.exports, klassisches Node.js
// "ESNext"    - import/export, moderne Browser und Bundler
// "NodeNext"  - Node.js ESM mit .mjs/.cjs-Erkennung
// "Preserve"  - Eingabe unveraendert uebernehmen

Fuer modernes Node.js ab Version 18 empfiehlt sich NodeNext zusammen mit "type": "module" in der package.json.

strict: Strenge Typueberpruefung aktivieren

// strict: true aktiviert alle strikten Pruefungen gleichzeitig:
// - strictNullChecks: null und undefined sind eigene Typen
// - noImplicitAny: Kein automatisches 'any' bei fehlendem Typ
// - strictFunctionTypes: Striktere Pruefung bei Funktionstypen
// - strictPropertyInitialization: Felder muessen im Konstruktor gesetzt werden

strict: true ist die empfohlene Einstellung fuer alle neuen Projekte. Bestehende Projekte sollten diese Option schrittweise einfuehren.

outDir und rootDir: Verzeichnisstruktur

// outDir: "./dist"  - Zielverzeichnis fuer kompilierte JS-Dateien
// rootDir: "./src"  - Quellverzeichnis (spiegelt Struktur in outDir)

Mit diesen beiden Optionen wird die Ordnerstruktur aus src/ exakt in dist/ abgebildet.

Wichtige weitere Optionen

// "declaration": true
// Erzeugt .d.ts-Typdefinitionsdateien neben dem JS-Code
// Pflicht fuer Bibliotheken, die als npm-Pakete veroeffentlicht werden

// "sourceMap": true
// Erzeugt Source-Maps fuer Debugging im Original-TypeScript-Code

// "esModuleInterop": true
// Erleichtert den Import von CommonJS-Modulen in ESM-Projekten
// Erlaubt: import fs from 'fs' statt import * as fs from 'fs'

// "skipLibCheck": true
// Ueberspringt Typueberpruefung in node_modules/.d.ts-Dateien
// Beschleunigt die Kompilierung und vermeidet Fehler aus Fremd-Paketen

// "resolveJsonModule": true
// Erlaubt den Import von JSON-Dateien als typisierte Module

// "paths": {...}
// Pfadaliasse fuer saubere Imports ohne relative Pfade

Pfadaliasse konfigurieren

Mit paths lassen sich kurze Import-Pfade einrichten:

// In der tsconfig.json:
// {
//   "compilerOptions": {
//     "baseUrl": ".",
//     "paths": {
//       "@utils/*": ["src/utils/*"],
//       "@components/*": ["src/components/*"]
//     }
//   }
// }

Damit sind Importe der folgenden Form moeglich:

import { formatDatum } from "@utils/datum";
import { Button } from "@components/Button";

Wichtig: Pfadaliasse in der tsconfig funktionieren nur fuer den TypeScript-Compiler. Bundler wie Vite oder Webpack benoetigen eine separate Konfiguration fuer dieselben Aliasse.

include, exclude und files

Diese drei Felder steuern, welche Dateien der Compiler verarbeitet:

// include: Glob-Muster fuer einzuschliessende Dateien
// ["src/**/*"] schliesst alle Dateien in src/ ein

// exclude: Dateien, die ausgeschlossen werden
// ["node_modules", "dist", "**/*.test.ts"]

// files: Explizite Liste einzelner Dateien
// Selten benoetigt, da include flexibler ist

Standardmaessig schließt TypeScript node_modules und outDir automatisch aus.

Vererbung mit extends

Fuer Projekte mit mehreren Build-Varianten (Entwicklung, Tests, Produktion) empfiehlt sich eine Basis-Konfiguration:

// tsconfig.base.json: Gemeinsame Einstellungen
// {
//   "compilerOptions": {
//     "strict": true,
//     "target": "ES2022",
//     "esModuleInterop": true
//   }
// }

// tsconfig.json: Erbt und ergaenzt
// {
//   "extends": "./tsconfig.base.json",
//   "compilerOptions": {
//     "outDir": "./dist",
//     "declaration": true
//   },
//   "include": ["src"]
// }

// tsconfig.test.json: Fuer Jest/Vitest
// {
//   "extends": "./tsconfig.base.json",
//   "compilerOptions": {
//     "module": "CommonJS"
//   },
//   "include": ["src", "tests"]
// }

Empfohlene Startkonfiguration fuer neue Projekte

Fuer moderne Node.js-Projekte:

// Ausgangspunkt fuer eine solide tsconfig.json:
// {
//   "compilerOptions": {
//     "target": "ES2022",
//     "module": "NodeNext",
//     "moduleResolution": "NodeNext",
//     "strict": true,
//     "outDir": "dist",
//     "rootDir": "src",
//     "declaration": true,
//     "sourceMap": true,
//     "esModuleInterop": true,
//     "skipLibCheck": true,
//     "forceConsistentCasingInFileNames": true
//   },
//   "include": ["src"],
//   "exclude": ["node_modules", "dist"]
// }

Fuer Frontend-Projekte mit Bundlern wie Vite unterscheiden sich vor allem module und moduleResolution.

tsconfig und das Playground

Das Playground hat eine vereinfachte Version der Compiler-Optionen in seiner Einstellungsleiste. Dort kannst du strict, target und weitere wichtige Optionen direkt ausprobieren und sofort beobachten, wie sich die Ergebnisse der Typueberpruefung veraendern.

Fazit

Die tsconfig.json ist der zentrale Hebel fuer das Verhalten des TypeScript-Compilers. strict: true als Ausgangspunkt, passende target- und module-Werte fuer die Laufzeitumgebung, und eine klare Verzeichnisstruktur mit rootDir und outDir bilden das Fundament. Mit dem extends-Muster laesst sich die Konfiguration sauber aufteilen und wiederverwenden.