NCA Social Media
Aktualisiert:
Autor:
Roland Golla
Grünes Schaltpult mit gelbem Schild TSCONFIG, Frau bewegt den Hebel

Was ist die tsconfig.json?

Die tsconfig.json ist die Konfigurationsdatei eines TypeScript Projekts. Sie markiert das Stammverzeichnis, legt die zu prüfenden Dateien fest und steuert über Compiler Optionen, wie streng TypeScript arbeitet. Ein Aufruf von tsc ohne Dateinamen sucht genau nach dieser Datei.
Code: 
          
{
  "compilerOptions": {
    "target": "es2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}
Das ist bereits eine brauchbare Grundlage für ein Projekt mit Bundler. Der Bundler baut das JavaScript, tsc prüft nur die Typen.
Inhalt
NCA KI Workshop für Developer

Agentic Coding im Team, nicht nur im Glossar

Ein Tag inhouse mit Benjamin Klein für Developer, Tester und Admins. Context Engineering, Harness, ADRs und zwei Hands on Blöcke mit KI Agenten in eurem Setup.

  1. 1
    Kostenloses Vorgespräch
    Stand, Rollen und Ziele klären
  2. 2
    Workshoptag bei euch
    Praxis am Vormittag, Hands on danach
  3. 3
    Praxistag optional
    Agenten im eigenen Projekt
Benjamin Klein
Benjamin Klein
Senior Consultant
Zum Workshop für Developer arrow_forward

Wir schärfen deine tsconfig Schritt für Schritt

In gewachsenen Projekten ist die tsconfig oft Jahre alt und niemand traut sich ran. Wir lesen sie mit dir durch, schalten Prüfungen stufenweise ein und halten die Zahl der Fundstellen bearbeitbar. Das gehört zu unserer Arbeit im Frontend Development und bei der TypeScript 7 Migration.

Die Regeln für KI Agents setzen auf derselben Konfiguration auf. Das zeigen die AI Coding Guidelines für TypeScript und das Vibe Coding Consulting.

Diese Optionen solltest du kennen

Option Aufgabe Typischer Wert
target JavaScript Version der Ausgabe und Standardbibliothek es2022 oder neuer
module Modulformat im erzeugten Code esnext oder nodenext
moduleResolution Wie Importe aufgelöst werden bundler oder nodenext
strict Bündelt die strengen Prüfungen true
noEmit Nur prüfen, nichts ausgeben true bei Projekten mit Bundler
include, exclude Welche Dateien zum Projekt gehören src, Tests nach Bedarf

Diese Prüfungen gehen über strict hinaus

Was strict im Einzelnen einschaltet, steht im Beitrag zu TypeScript und strict Mode in Astro. Einige nützliche Prüfungen sind darin aber nicht enthalten und müssen eigens gesetzt werden.

Code: 
          
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}
  • noUncheckedIndexedAccess: Ein Zugriff wie liste[0] kann auch undefined liefern. Das fängt viele echte Laufzeitfehler ab und bringt in alten Projekten die meisten Fundstellen.
  • noImplicitOverride: Überschriebene Methoden müssen als solche markiert sein.
  • noFallthroughCasesInSwitch: Ein case ohne break oder return fällt auf.
  • exactOptionalPropertyTypes: Ein optionales Feld darf fehlen, aber nicht ausdrücklich undefined sein. Das ist streng und lohnt sich eher bei neuen Projekten.

Mit extends und paths bleibt die Konfiguration kurz

Über extends erbst du eine Basis und schreibst nur noch die Abweichungen. Astro bringt dafür eigene Vorlagen mit. Kurze Importpfade legst du mit paths an, und zwar relativ zum Projekt, denn baseUrl wird in TypeScript 7 nicht mehr unterstützt.
Code: 
          
{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
Wichtig: paths ändert nur die Sicht des Compilers. Das Laufzeitverhalten bestimmt dein Bundler oder Node.js, die den Alias ebenfalls kennen müssen. Sonst ist der Type Check grün, und der Import scheitert erst beim Start.

Monorepos teilen sich über Project References auf

In einem Monorepo bekommt jedes Paket seine eigene tsconfig.json. Eine Datei im Stammverzeichnis verweist auf die Pakete, und tsc --build baut sie in der richtigen Reihenfolge. Pakete, auf die andere verweisen, brauchen dafür composite.
Code: 
          
// tsconfig.json im Stammverzeichnis
{
  "files": [],
  "references": [
    { "path": "./packages/ui" },
    { "path": "./packages/web" }
  ]
}

// packages/ui/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src"]
}
Ein Fehler zeigt dann genauer, in welchem Paket er entstanden ist. Unveränderte Pakete werden außerdem nicht jedes Mal neu geprüft.

indicates that the directory is the root of a TypeScript project

TypeScript Handbook, Offizielle TypeScript Dokumentation von Microsoft – typescriptlang.org, What is a tsconfig.json

Eine strenge Konfiguration wirkt erst mit einem Check in der Pipeline

Die beste tsconfig hilft wenig, wenn der Type Check nur lokal läuft. Als eigener Schritt gehört er in die CI CD Pipeline und in die Quality Gates für KI Code. Für Agents kommt ein Verweis in die AGENTS.md dazu.

Sichtbar werden dann vor allem verstecktes any und vergessene Fälle. Einen Überblick zur Sprache gibt der TypeScript Eintrag, Astro Projekte finden die Grundlagen in unserem Astro Beitrag.

CYPRESS.IO Ambassador und IT Consultant für QA Engenieering und Qualität in PHP Projekten.
Frontend: Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile der Barrierefreiheit

Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile einer schnellen, sicheren und barrierefreien Webseite. Erfüllen Sie die gesetzlichen Anforderungen und verbessern Sie die Benutzererfahrung Ihrer Webseite. Mit Astro JS können Sie die Ladezeit reduzieren, die Sicherheit maximieren und die SEO-Optimierung verbessern. Kontaktieren Sie uns, um mehr zu erfahren und um Ihre Webseite auf ein neues Level zu heben.

E-Mail Kontakt

Häufige Fragen zur tsconfig.json

Die häufigsten Fragen rund um die Konfiguration.
Was macht die tsconfig.json 2026?

Sie markiert das Stammverzeichnis eines TypeScript Projekts und enthält die Compiler Optionen. Darin steht, welche Dateien dazugehören, wie Importe aufgelöst werden und wie streng geprüft wird. Ein Aufruf von tsc ohne Dateinamen liest diese Datei automatisch.

Wie erstelle ich 2026 eine tsconfig.json?

Am schnellsten mit npx tsc --init. Der Befehl legt eine Datei mit sinnvollen Vorgaben an. Bei Frameworks wie Astro erbst du besser über extends deren Vorlage. Danach ergänzt du nur noch, was in deinem Projekt anders sein soll.

Welche tsconfig Optionen ändern sich 2026 mit TypeScript 7?

strict ist jetzt Standard, module steht auf esnext, und types ist standardmäßig leer. rootDir zeigt auf das Projektverzeichnis. baseUrl, moduleResolution node und target es5 werden nicht mehr unterstützt. Prüfe bei einer Migration vor allem rootDir und types.

Welcher moduleResolution Wert passt 2026?

Mit einem Bundler wie Vite passt bundler. Für Code, der direkt in Node.js läuft, ist nodenext die richtige Wahl. Die alte Einstellung node ist in TypeScript 7 entfernt. Passe module dabei passend an, sonst meldet der Compiler einen Konflikt.

Hilft eine strenge tsconfig 2026 bei KI generiertem Code?

Ja, denn sie legt fest, wie viel der Compiler einem Agent durchgehen lässt. Mit strict und noUncheckedIndexedAccess fallen viele Annahmen sofort auf. Der Agent liest die Fehler und korrigiert sie im selben Lauf, bevor jemand den Diff öffnet.

Was bringt noUncheckedIndexedAccess?

Zugriffe über einen Index liefern zusätzlich undefined im Typ. Ein liste[0] ist damit nicht mehr automatisch vorhanden, und du musst den Fall behandeln. In älteren Projekten erzeugt das viele Fundstellen, deshalb schaltest du es am besten gesondert ein.

Warum funktioniert mein paths Alias nicht zur Laufzeit?

paths gilt nur für den Compiler und schreibt Importe beim Bauen nicht um. Dein Bundler oder Node.js braucht den Alias zusätzlich in der eigenen Konfiguration. Stimmt beides nicht überein, ist der Type Check grün, aber der Import schlägt beim Start fehl.

Was ist skipLibCheck und sollte ich es nutzen?

skipLibCheck überspringt die Prüfung von Deklarationsdateien, auch aus node_modules. Das spart Zeit und verhindert Fehler aus fremden Paketen. In Anwendungen ist das üblich. Bei einer veröffentlichten Bibliothek solltest du deine eigenen Deklarationen trotzdem anders absichern.

Brauche ich mehrere tsconfig Dateien?

Oft reicht eine. Mehrere lohnen sich, wenn Teile unterschiedlich laufen, etwa Browser Code und Node Skripte, oder im Monorepo. Eine gemeinsame Basis mit extends verhindert, dass die Dateien auseinanderlaufen.

Wie schalte ich strenge Optionen in einem alten Projekt ein?

Einzeln und nacheinander. Schalte eine Option ein, zähle die Fundstellen und behebe zuerst die Ränder wie API Zugriffe und Formulare. Bleibt die Pipeline danach grün, folgt die nächste. Ein einziger großer Pull Request lässt sich kaum sinnvoll prüfen.