Standards für TypeScript-Codebasen: tsconfig, Lint und Modulgrenzen

TypeScript-Codestandards für Teams: strikte tsconfig, typescript-eslint-Regeln, Prettier, Modulgrenzen, Erzeugung von API-Typen und Typ-/Lint-Prüfung in der CI.
Technische Zusammenfassung
Technologie
TypeScript, ESLint (flat config), typescript-eslint, Prettier, openapi-typescript
Thema
TypeScript-Codebasis-Standard für das Team
Niveau
Mittel
Voraussetzungen
  • Erfahrung in der Projektentwicklung mit TypeScript
  • Kenntnisse der npm/Node.js-Toolchain
In diesem Beitrag7 Abschnitte

Arbeiten fünf Entwickler an derselben TypeScript-Codebasis, bestimmen gemeinsame Regeln die Qualität, nicht individuelle Sorgfalt. Werden Compilereinstellungen, Lint-Regeln, Ordnerstruktur und CI-Prüfungen nicht an einen schriftlichen Standard gebunden, bringt jeder seine eigenen Gewohnheiten mit; nach sechs Monaten ist die Codebasis in einander unähnliche Teile zerfallen, und jede Änderung bricht etwas anderes. Im Folgenden finden Sie einen umsetzbaren TypeScript-Standard für eine Unternehmens-Webanwendung: Beispiel-tsconfig, ESLint-Konfiguration, Regeln für Modulgrenzen und CI-Schritte.

Zweck eines Codestandards

Ein Codestandard existiert nicht, um Stildiskussionen zu beenden, sondern um Fehler zur Kompilierzeit zu fangen und die Auswirkung von Änderungen vorhersehbar zu machen. Jede Regel sollte eine von drei Fragen beantworten: Verhindert sie einen Laufzeitfehler? Beschleunigt sie Lesen und Review des Codes? Schützt sie Architekturgrenzen? Nehmen Sie keine Regel in den Standard auf, die keine dieser drei berührt; sie erzeugt im Code-Review nur Reibung.

Damit der Standard Bestand hat, gibt es drei Bedingungen: Regeln müssen mit Werkzeugen automatisch durchgesetzt werden, dieselben Werkzeuge müssen auf dem Entwicklerrechner und in der CI in derselben Version laufen, und Ausnahmen müssen mit Begründung im Code sichtbar sein. Eine Regel, die nur auf einer Wiki-Seite steht, wird nicht angewendet.

Strikte tsconfig-Einstellungen

"strict": true aktiviert allein eine Familie von Flags; dazu gehören noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, alwaysStrict und useUnknownInCatchVariables (neue TypeScript-Versionen können dieser Familie Flags hinzufügen). In einem neuen Projekt steht das nicht zur Debatte. Flags, die nicht in strict enthalten sind und deren Ergänzung wir empfehlen:

Flag Was es fängt Hinweis
noUncheckedIndexedAccess Möglichkeit von undefined beim Zugriff auf array[i] und Records Wertvollstes Zusatzflag; erzwingt Prüfungen im Code
exactOptionalPropertyTypes Explizite Zuweisung von undefined an ein optionales Feld Streng bei API-Mustern; per Teamentscheidung
noImplicitOverride Unbeabsichtigtes Überschreiben einer Methode der Oberklasse Nützlich in Code mit Klassen
noFallthroughCasesInSwitch Vergessenes break in switch Geringe Kosten
verbatimModuleSyntax Reine Typimporte, die zur Laufzeit erhalten bleiben Erzwingt die Verwendung von import type
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "preserve",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "noEmit": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src", "tests"],
  "exclude": ["node_modules", "dist"]
}

Dieses Beispiel gilt für ein Frontend-Projekt, dessen Build-Ausgabe ein Bundler (Next.js, Vite) erzeugt; mit noEmit arbeitet TypeScript nur als Typprüfer. In einem Backend-Dienst, der direkt auf Node.js läuft, sind "module": "NodeNext" und "moduleResolution": "NodeNext" richtiger, weil sie die ESM/CommonJS-Auflösungsregeln von Node exakt abbilden. paths-Aliase sind nur eine Wegbeschreibung für den Compiler; sie schreiben Importe nicht um. Das ist die häufige Ursache von Diensten, deren Build sauber durchläuft und die in der Produktion den Fehler „Cannot find module“ werfen. In reinem Node.js wird für denselben Zweck das Feld "imports" in package.json (Subpath-Imports wie #lib/*) verwendet.

Aktivieren Sie in einem bestehenden Projekt alle strengen Einstellungen auf einmal, entstehen Hunderte Fehler, und die Änderung wird meist zurückgenommen. Der praktische Weg: Flags einzeln aktivieren, Fehler an die Modulverantwortlichen verteilen und während der Umstellung statt // @ts-ignore ein kommentiertes // @ts-expect-error verwenden. Letzteres meldet selbst einen Fehler, sobald der darunterliegende Fehler behoben ist; überflüssige Ausnahmen werden so sichtbar.

Lint- und Formatierungsregeln

Die Aufgabenteilung ist klar: Prettier formatiert, ESLint prüft Korrektheits- und Architekturregeln. Einrückung, Anführungszeichen oder Zeilenlänge sollten im Code-Review nie Thema sein. Eine Beispielkonfiguration im seit ESLint 9 standardmäßigen „Flat Config“-Format mit typescript-eslint-Regeln, die Typinformationen nutzen:

// eslint.config.mjs
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import prettier from 'eslint-config-prettier';

export default [
  { ignores: ['dist/**', '.next/**', 'src/generated/**'] },
  js.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
    },
    rules: {
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': 'error',
      '@typescript-eslint/consistent-type-imports': 'error',
      '@typescript-eslint/switch-exhaustiveness-check': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/ban-ts-comment': ['error', { 'ts-expect-error': 'allow-with-description' }],
    },
  },
  { files: ['**/*.{js,mjs,cjs}'], ...tseslint.configs.disableTypeChecked },
  prettier,
];

Begründung der Regelauswahl:

  • no-floating-promises und no-misused-promises: Nicht abgewartete Promises sind die häufigste Ursache von Störungen, bei denen ein Fehler stillschweigend verschluckt wird und ein Datensatz halb fertig bleibt. Im Log gibt es keine Spur, die Daten sind unvollständig. Diese Regeln brauchen Typinformationen; deshalb wurde das Set recommendedTypeChecked gewählt.
  • switch-exhaustiveness-check: Wird einem Union-Typ (z. B. Bestellstatus) ein neuer Wert hinzugefügt, werden alle switch-Blöcke, die ihn nicht behandeln, beim Kompilieren markiert.
  • no-explicit-any: Daten aus externen Quellen werden als unknown angenommen und per Schemavalidierung eingeengt.

Die Zeile disableTypeChecked schaltet Regeln, die Typinformationen benötigen, für JavaScript-Dateien außerhalb des tsconfig-Bereichs wie eslint.config.mjs ab; sonst melden diese Dateien den Fehler „im Projektdienst nicht gefunden“. Lint mit Typinformationen wird in großen Projekten langsam. Auf dem Entwicklerrechner genügen Editorintegration und ein Pre-Commit-Hook für geänderte Dateien; den vollständigen Scan überlassen Sie der CI.

Ordnerstruktur und Modulgrenzen

Wächst die Codebasis, wird nicht der Typ zum eigentlichen Problem, sondern die Abhängigkeitsrichtung: Eine UI-Komponente importiert direkt den Datenbank-Client, ein Feature greift in die internen Dateien eines anderen Features. Sie ändern eine Stelle, und ein unbeteiligter Bildschirm bricht. Eine featureorientierte Struktur mit klaren Grenzen verhindert das:

src/
  app/                  // Routen und Seitenkomposition
  features/
    bestellung/
      index.ts          // nach aussen offene API des Features
      components/
      server/           // Datenzugriff, Geschaeftsregeln
      schema.ts
    lager/
      index.ts
      ...
  shared/
    ui/                 // Komponenten des Designsystems
    lib/                // Datum, Waehrung, Hilfsfunktionen
  generated/            // aus dem API-Schema erzeugte Typen (nicht manuell bearbeiten)

Regeln: shared darf kein features-Modul importieren; ein Feature greift auf ein anderes nur über index.ts zu; server-Ordner dürfen nicht aus Client-Komponenten importiert werden. Für den ersten Schritt genügt die eingebaute ESLint-Regel no-restricted-imports:

{
  files: ['src/**/*.{ts,tsx}'],
  rules: {
    'no-restricted-imports': ['error', {
      patterns: [{
        group: ['@/features/*/*', '!@/features/*/index'],
        message: 'Auf ein anderes Feature nur ueber index.ts zugreifen.',
      }],
    }],
  },
},

Dieses Muster erfasst auch die Dateien innerhalb eines Features; daher werden Importe innerhalb eines Features mit relativem Pfad (./components/...) geschrieben, der Alias wird nur für Zugriffe zwischen Features genutzt. Ist die Schichtenmatrix komplexer, lassen sich Abhängigkeitsregeln mit Werkzeugen wie eslint-plugin-boundaries oder dependency-cruiser definieren und in der CI prüfen. In Next.js-Webanwendungen wird das Paket server-only als zusätzliche Sperre dagegen genutzt, dass Servermodule ins Client-Bundle gelangen; diese Grenze beschreiben wir ausführlich im Beitrag Trennung von Server und Client Component im Next.js App Router.

API-Typen teilen und erzeugen

Typen zwischen Frontend und Backend manuell zu kopieren, ist der kürzeste Weg zu einem stillschweigend abdriftenden Vertrag. Im Backend ändert sich ein Feldname, das Frontend kompiliert, der Fehler explodiert in der Produktion. Regel: API-Typen werden aus einer einzigen Quelle erzeugt, nicht von Hand geschrieben. Die Quelle hängt vom gewählten API-Stil ab:

API-Stil Einzige Quelle Beispiel für ein Erzeugungswerkzeug
REST OpenAPI-Dokument openapi-typescript
GraphQL Schema + Client-Abfragen GraphQL Code Generator
Gleiches Repository, TypeScript-Backend Gemeinsam genutztes Schemapaket z.infer aus dem Zod-Schema
npx openapi-typescript ./openapi.yaml -o ./src/generated/api.d.ts

Erzeugte Dateien liegen unter src/generated, werden vom Lint ausgenommen und in der CI neu erzeugt; geprüft wird, dass die Differenz null ist. Ändert jemand das Schema und vergisst die Typaktualisierung, bricht der Build. Dort soll er auch brechen. Typen zur Kompilierzeit sind allerdings keine Laufzeitgarantie: Aus dem Netz kommende Daten müssen an der Grenze weiterhin mit einer Schemabibliothek validiert werden. Details für Formulare im Beitrag Formularvalidierung mit einem Schema auf Client und Server, die Wahl des API-Stils im Vergleich REST oder GraphQL.

Typ- und Lint-Prüfung in der CI

Den Standard tatsächlich durchsetzen tut die CI. Bei jedem Merge Request sollten diese Schritte separat laufen; schlägt einer fehl, wird der Merge blockiert:

# package.json-Skripte
"typecheck": "tsc --noEmit",
"lint": "eslint . --max-warnings=0",
"format:check": "prettier --check .",
"api:generate": "openapi-typescript ./openapi.yaml -o ./src/generated/api.d.ts"

# CI-Schritte
npm ci
npm run api:generate && git diff --exit-code src/generated
npm run typecheck
npm run lint
npm run format:check

--max-warnings=0 ist eine bewusste Wahl. Ein Lint-Schritt, der das Ansammeln von Warnungen erlaubt, wird innerhalb weniger Monate zu einer Ausgabe aus Hunderten Zeilen, die niemand liest. Eine ungelesene Warnung ist keine Warnung. Soll eine Regel auf Warnstufe bleiben, stufen Sie sie entweder zum Fehler hoch oder schalten Sie sie ab. In Monorepos mit Projektreferenzen (Project References) wird statt tsc --noEmit inkrementell mit tsc -b kompiliert. Wie Sie diese Schritte in eine Pipeline einbauen, beschreibt der Beitrag CI/CD-Pipeline für Webprojekte mit GitHub Actions.

Checkliste, die in das Standarddokument gehört:

  • Versionen von Node.js, TypeScript, ESLint und Prettier sind per Lockfile fixiert; die CI nutzt dieselben Versionen.
  • strict und noUncheckedIndexedAccess aktiviert; Ausnahmen mit kommentiertem @ts-expect-error.
  • Lint-Regeln mit Typinformationen und --max-warnings=0 aktiv.
  • Zugriff zwischen Features nur über index.ts; die Regel wird per Lint geprüft.
  • API-Typen werden erzeugt, nicht manuell bearbeitet; in der CI gibt es eine Differenzprüfung.
  • Editoreinstellungen (.editorconfig, empfohlene Erweiterungen) sind im Repository definiert.

Beim Neuaufbau der Codebasis einer Unternehmensanwendung oder bei der Überführung eines übernommenen Projekts in diesen Standard können wir Konfiguration und Umstellungsplan im Rahmen unserer Leistung Entwicklung individueller Webanwendungen gemeinsam vorbereiten. Maßgeblich für die vollständige Referenz der Compilerflags ist die TypeScript-tsconfig-Referenz, für Lint-Regeln die typescript-eslint-Dokumentation.

Häufig gestellte Fragen

Ist es sinnvoll, in einem bestehenden großen Projekt den Strict-Modus auf einmal zu aktivieren?

Meist nicht. Aktivieren Sie zuerst Flags wie noImplicitAny und strictNullChecks einzeln, schließen Sie die Fehler Modul für Modul und wechseln Sie dann zu strict: true. Während der Umstellung kann per Lint und Code-Review erzwungen werden, dass neue Dateien die strengen Regeln einhalten.

Gilt die Definition paths in tsconfig auch zur Laufzeit?

Nein. paths beschreibt nur dem TypeScript-Compiler die Modulauflösung und schreibt Importpfade nicht um. Werkzeuge wie Next.js und Vite lesen diese Definition; in reiner Node.js-Laufzeit braucht es dagegen das Feld imports in package.json (Subpath-Imports, die mit # beginnen) oder die Alias-Unterstützung des Build-Werkzeugs.

Wie vermeidet man Regelkonflikte, wenn Prettier und ESLint gemeinsam genutzt werden?

Die Formatierung wird vollständig Prettier überlassen, die Formatierungsregeln von ESLint werden mit eslint-config-prettier abgeschaltet. ESLint kümmert sich nur um Korrektheits- und Architekturregeln. In der CI laufen prettier –check und eslint als getrennte Schritte.

Sollte any in den Lint-Regeln komplett verboten werden?

Im Anwendungscode kann die Regel no-explicit-any auf Fehlerebene gehalten werden; für externe Daten ist der richtige Weg, statt any unknown zu verwenden und per Schemavalidierung einzuengen. In unvermeidbaren Fällen wie der Integration alter Bibliotheken wird eine Ausnahme mit begründetem eslint-disable-Kommentar und Freigabe im Code-Review definiert.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge