tsconfig-Grundlagen

Was die tsconfig.json macht

Die tsconfig.json markiert die Wurzel eines TypeScript-Projekts. Sie legt fest, welche Dateien zum Projekt gehören und mit welchen Optionen der Compiler tsc sie verarbeitet. Ohne diese Datei kennt TypeScript weder dein Ziel-JS noch deine Modulauflösung — tsc fällt dann auf hartcodierte Defaults zurück, die selten zu deinem Setup passen.

Auffinden: Wenn du tsc ohne Argumente startest, sucht der Compiler im aktuellen Verzeichnis nach tsconfig.json und arbeitet sich anschliessend die Verzeichnis-Hierarchie nach oben durch, bis er fündig wird. Du kannst auch explizit eine Konfiguration angeben:

tsc --project ./tsconfig.build.json
# oder kurz:
tsc -p ./tsconfig.build.json

Wichtig: Sobald du tsc mit konkreten Dateinamen aufrufst (tsc src/index.ts), wird tsconfig.json ignoriert. Das ist ein häufiger Stolperstein in CI-Skripten — bau immer per tsc -p.

Generator tsc --init: Eine sinnvolle Start-Konfiguration bekommst du mit:

npx tsc --init

Die generierte Datei enthält viele auskommentierte Optionen mit Kurzbeschreibung — sehr nützlich zum Stöbern, aber für reale Projekte zu lang. In der Praxis startet man besser mit einer schlanken Datei oder einer fertigen Base-Konfiguration über extends (siehe Specials am Ende).

Minimalkonfiguration

Die kleinste sinnvolle tsconfig.json für ein modernes Node-Projekt sieht so aus:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "nodenext",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "outDir": "dist"
    },
    "include": ["src/**/*"]
}

Was hier passiert:

• target: es2022 — Output ist modernes JavaScript, Node 18+ versteht das ohne Probleme.
• module: nodenext — Echtes ESM-/CommonJS-Handling nach Node-Spezifikation; setzt automatisch moduleResolution: nodenext mit.
• strict: true — Alle strikten Checks aktivieren (siehe Abschnitt 5).
• esModuleInterop: true — Interop zwischen ESM-Imports und CommonJS-Modulen; quasi Pflicht.
• skipLibCheck: true — .d.ts-Dateien aus node_modules werden nicht typgeprüft, was Build-Zeit massiv spart.
• outDir: dist — Kompiliertes JavaScript landet unter dist/.

Mehr brauchst du für den Anfang nicht. Alles Weitere ist Optimierung.

target und lib

target bestimmt, welche JavaScript-Version tsc als Output erzeugt — wichtig, weil neueres Syntax-Sugar (optional chaining, nullish coalescing, top-level await, decorators) je nach Target entweder direkt emittiert oder zu älterem JS umgeschrieben wird.

lib bestimmt, welche eingebauten Typen (DOM-API, ES-API) dir während der Typprüfung zur Verfügung stehen. Wenn du lib nicht setzt, leitet TypeScript es aus target ab.

Praxisregel: Wenn ein Bundler (Vite, esbuild, Rollup, Next.js) am Werk ist, ist target: esnext oder es2022 fast immer die richtige Wahl — der Bundler kümmert sich um Browser-Kompatibilität. Wenn tsc selbst der finale Compiler ist (klassische Node-Library), wähle das niedrigste target, das deine Ziel-Node-Version garantiert versteht.

lib getrennt setzen: In einer Browser-App brauchst du explizit dom:

{
    "compilerOptions": {
        "target": "es2022",
        "lib": ["es2022", "dom", "dom.iterable"]
    }
}

In einer reinen Node-Library lässt du dom weg — dann meckert TypeScript zu Recht, wenn jemand versehentlich document.querySelector schreibt.

module und moduleResolution

Diese beiden Optionen sind die häufigste Fehlerquelle in tsconfigs. Sie bestimmen:

• module — wie der Output aussieht (CommonJS require oder ESM import).
• moduleResolution — wie TypeScript Imports auflöst (welche Dateien finde ich hinter import x from 'y').

moduleResolution-Werte:

• node — alter Default, kennt keine .mjs/.cjs-Unterscheidung. Nicht mehr verwenden.
• node16 / nodenext — Node-konformes Verhalten, inkl. expliziter Datei-Extensions in Imports.
• bundler — seit TypeScript 5.0, der pragmatische Modus für Vite, Webpack, Next.js, esbuild. Erlaubt extensionslose Imports und Auflösung über package.json-exports, ohne dass tsc selbst Code erzeugt.
• classic — Legacy, ignorieren.

Faustregel:

• Bundler im Spiel (Vite, Next, Remix, Webpack)? → module: esnext + moduleResolution: bundler.
• Reine Node-Library, die per tsc gebaut wird? → module: nodenext (moduleResolution: nodenext wird automatisch mitgesetzt).
• Etwas dazwischen? → meistens auch nodenext.

Die strict-Family

strict: true ist der wichtigste Schalter in der ganzen Datei. Er aktiviert auf einen Schlag alle strikten Typchecks:

Empfehlung ohne Wenn und Aber: In jedem neuen Projekt strict: true setzen. Die geringe Mehrarbeit beim Schreiben wird durch wegfallende Laufzeitfehler um Grössenordnungen aufgewogen — gerade strictNullChecks ist der Hauptgrund, warum sich TypeScript-Code von JavaScript-Code spürbar sicherer anfühlt.

Wer noch strenger fahren will, ergänzt:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noFallthroughCasesInSwitch": true,
        "noImplicitOverride": true,
        "noImplicitReturns": true,
        "exactOptionalPropertyTypes": true
    }
}

noUncheckedIndexedAccess ist besonders wertvoll: Es zwingt dich, bei Array- und Objekt-Index-Zugriffen undefined zu behandeln.

rootDir, outDir, include, exclude

Diese vier Optionen bestimmen den Datei-Scope des Projekts.

• rootDir — der Quellordner. Wenn nicht gesetzt, leitet TypeScript ihn aus den include-Patterns ab. Wichtig, weil outDir die Verzeichnis-Struktur relativ zu rootDir spiegelt.
• outDir — wohin der kompilierte JavaScript-Output geschrieben wird.
• include — Glob-Patterns, welche Dateien zum Projekt gehören.
• exclude — Glob-Patterns, was ausgeschlossen wird. Default schliesst node_modules, bower_components, jspm_packages und outDir aus.

{
    "compilerOptions": {
        "rootDir": "src",
        "outDir": "dist"
    },
    "include": ["src/**/*"],
    "exclude": ["**/*.test.ts", "**/*.spec.ts"]
}

Stolperfalle rootDir: Wenn du Imports ausserhalb von rootDir machst (z. B. import { x } from '../shared/utils', während rootDir auf src zeigt), bricht tsc mit einer kryptischen Meldung ab. Lösung: entweder rootDir weiter oben ansetzen oder die Quelldatei nach src ziehen.

include vs. files: Statt Glob-Patterns kannst du auch files: ["src/index.ts", "src/server.ts"] schreiben — sinnvoll, wenn du wirklich nur einzelne Einstiegspunkte hast (selten).

paths und baseUrl

Aliase wie @/components/Button statt ../../../components/Button machen Imports lesbar. Konfiguriert wird das über paths plus optional baseUrl.

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": ["src/*"],
            "@components/*": ["src/components/*"],
            "@utils": ["src/utils/index.ts"]
        }
    }
}

Seit TypeScript 5.0 ist baseUrl optional, wenn du paths mit relativen Patterns angibst — der Compiler löst dann ab dem Verzeichnis der tsconfig.json auf.

Die grosse Falle: paths ist nur eine Information für den Typchecker. Zur Laufzeit weiss weder Node noch der Browser etwas davon. Wenn dein Bundler (Vite, Webpack, esbuild) den Alias nicht parallel auflöst, knallt es beim Start mit „module not found".

Lösung — Alias muss zweimal eingetragen werden:

import { defineConfig } from "vite";
import path from "node:path";

export default defineConfig({
    resolve: {
        alias: {
            "@": path.resolve(__dirname, "src"),
        },
    },
});

Tools wie vite-tsconfig-paths oder tsconfig-paths für Node lesen die Konfiguration direkt aus tsconfig.json aus — komfortabler, aber eine zusätzliche Abhängigkeit.

tsBuildInfoFile, incremental, noEmit

Drei Optionen, die du je nach Workflow brauchst.

• incremental: true — TypeScript speichert nach jedem Build einen kleinen Snapshot (.tsbuildinfo), aus dem der nächste Build nur noch die Diffs berechnet. Beschleunigt grosse Projekte enorm.
• tsBuildInfoFile — wohin diese Info geschrieben wird. Standard ist neben dem Output. In Monorepos oft sinnvoll, sie an einen zentralen Ort zu legen.
• noEmit: true — TypeScript prüft Typen, schreibt aber keine Dateien. Das ist der Normalfall, wenn ein Bundler den eigentlichen Build macht: tsc --noEmit läuft dann als reiner Linter in der CI.

{
    "compilerOptions": {
        "incremental": true,
        "tsBuildInfoFile": "./.tsbuildinfo",
        "noEmit": true
    }
}

In package.json taucht das dann typischerweise so auf:

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

Beispiel: moderne strict-tsconfig für Node-Library

Eine produktionsreife Konfiguration für eine klassische, per tsc gebaute Node-Library:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "nodenext",
        "lib": ["es2022"],
        "rootDir": "src",
        "outDir": "dist",
        "declaration": true,
        "declarationMap": true,
        "sourceMap": true,
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true,
        "exactOptionalPropertyTypes": true,
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "incremental": true
    },
    "include": ["src/**/*"],
    "exclude": ["**/*.test.ts", "dist"]
}

Highlights:

• declaration/declarationMap — .d.ts-Dateien plus Mappings, damit Konsumenten der Library direkt in deine Quellen springen können.
• verbatimModuleSyntax — erzwingt explizites import type/export type, klare Trennung von Werten und Typen.
• isolatedModules — stellt sicher, dass jede Datei auch einzeln kompiliert werden kann (Pflicht für Babel/SWC-Konsumenten).
• forceConsistentCasingInFileNames — verhindert die klassische macOS-vs-Linux-Falle, bei der User.ts und user.ts auf dem Mac dasselbe sind, in der CI aber nicht.

Beispiel: tsconfig für Vite/Next.js/Bundler

Wenn ein Bundler den eigentlichen Build macht und tsc nur Typchecker ist:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "esnext",
        "moduleResolution": "bundler",
        "lib": ["es2022", "dom", "dom.iterable"],
        "jsx": "react-jsx",
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noEmit": true,
        "allowImportingTsExtensions": true,
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "esModuleInterop": true,
        "resolveJsonModule": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "incremental": true,
        "baseUrl": ".",
        "paths": {
            "@/*": ["src/*"]
        }
    },
    "include": ["src", "vite.config.ts"]
}

Highlights:

• moduleResolution: bundler + module: esnext — der Bundler löst auf, tsc schreibt nichts.
• noEmit: true — TypeScript ist hier nur Typchecker.
• allowImportingTsExtensions — erlaubt import x from './foo.ts', was Vite und moderne Bundler problemlos verarbeiten.
• jsx: react-jsx — moderner JSX-Transform ohne import React from 'react'-Pflicht.

Weiterführende Ressourcen

Externe Quellen

• tsconfig Reference – TypeScript
• What is a tsconfig.json – Handbook
• TSConfig Bases – @tsconfig

Verwandte Artikel

• Setup und tsc
• Erstes Programm
• Was ist TypeScript?
• Type System – Übersicht
• Primitive Typen – Übersicht