TypeScript Best Practices: Acht Regeln für typsicheren Code

Von strict über unknown bis satisfies: Wie Teams das Typsystem so nutzen, dass es Fehler wirklich findet
Aktualisiert:
Abstract
- #TypeScript
- #JavaScript
- #Webentwicklung
- #Type-Safety
- #Best Practices
- #Typsystem
- #Codequalität
TypeScript schützt nur so weit, wie der Code es zulässt – auf diese Gewohnheiten kommt es an
Ein Code-Review in einem Projekt, das seit drei Jahren in TypeScript geschrieben ist: Die Antwort der Kunden-API wird mit as Kunde in den passenden Typ gezwungen, ein Formularwert mit ! für „sicher vorhanden“ erklärt, und eine Hilfsfunktion gibt any zurück. Der Compiler meldet keinen einzigen Fehler. Trotzdem stürzt die Anwendung ab, als die API ein Feld umbenennt.
Das Beispiel zeigt ein verbreitetes Missverständnis. TypeScript macht Code nicht automatisch sicher. Die Sprache prüft nur, was der Code ihr verrät, und lässt sich an jeder Stelle überstimmen. Wie viel Schutz ein Projekt tatsächlich bekommt, entscheiden die Gewohnheiten im Team. Die folgenden acht Regeln beschreiben die wichtigsten davon, jeweils mit einem Codebeispiel.
Wer TypeScript noch nicht kennt, findet im Beitrag TypeScript: Der Weg zu weniger Fehlern und wartbarem JavaScript-Code eine Einführung in Typsystem, strict-Modus und Migration. Der TypeScript-Entwickler-Ratgeber behandelt Architektur, Tests und Performance. Hier geht es um das Typsystem selbst: wie man es im Alltag so einsetzt, dass es seine Arbeit machen kann.
Regel 1: Mit einer strengen Konfiguration beginnen
Der Ausgangspunkt jedes Projekts ist die Datei tsconfig.json. Die Option strict bündelt die wichtigsten Prüfungen, darunter strictNullChecks (Werte, die null oder undefined sein können, müssen geprüft werden) und noImplicitAny (Parameter ohne Typangabe werden nicht stillschweigend zu any). Seit TypeScript 6.0 ist strict standardmäßig aktiv. Ältere Projekte haben es aber oft ausdrücklich abgeschaltet oder nie eingeschaltet.
Einige weitere Optionen gehören nicht zu strict, fangen aber typische Fehler ab:
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitOverride": true,
"noFallthroughCasesInSwitch": true,
"verbatimModuleSyntax": true,
"erasableSyntaxOnly": true
}
}
noUncheckedIndexedAccess behandelt Zugriffe wie liste[3] als „Element oder undefined“, weil das Element fehlen kann. exactOptionalPropertyTypes unterscheidet zwischen einer fehlenden Eigenschaft und einer, die ausdrücklich auf undefined gesetzt ist. noImplicitOverride verlangt das Schlüsselwort override, wenn eine Klasse eine Methode der Elternklasse überschreibt. verbatimModuleSyntax und erasableSyntaxOnly sorgen dafür, dass sich Typangaben rein durch Löschen entfernen lassen. Das ist wichtig, wenn Node.js, Deno, Bun oder ein schnelles Build-Werkzeug den Code ohne vollständige Übersetzung ausführen.
Für Bestandsprojekte ist es selten sinnvoll, alles auf einmal einzuschalten. Besser ist es, eine Option nach der anderen zu aktivieren und die Meldungen modulweise abzuarbeiten. Welche Optionen es sonst gibt, erklärt der Leitfaden zur TypeScript-5-Konfiguration.
Regel 2: An Systemgrenzen unknown statt any verwenden
any schaltet die Typprüfung für einen Wert vollständig ab, und zwar ansteckend: Alles, was aus einem any abgeleitet wird, ist ebenfalls ungeprüft. unknown bedeutet dagegen „Typ noch nicht bekannt“. Mit einem solchen Wert lässt sich nichts anfangen, bevor der Code ihn geprüft hat.
Der richtige Ort für unknown sind die Grenzen des eigenen Systems: API-Antworten, Formulardaten, localStorage, Nachrichten aus einer Warteschlange. Dort kommen Daten an, deren Form TypeScript nicht kennen kann. Eine Typangabe wie as Kunde ist an dieser Stelle nur eine Behauptung. Sicherer ist eine Prüfung zur Laufzeit, etwa mit einer Schema-Bibliothek wie Zod oder Valibot, die zugleich den Typ liefert:
import * as z from 'zod';
const KundeSchema = z.object({
id: z.string(),
name: z.string(),
email: z.email().optional(),
});
// Der Typ wird aus dem Schema abgeleitet und muss nicht doppelt gepflegt werden.
type Kunde = z.infer<typeof KundeSchema>;
export async function ladeKunde(id: string): Promise<Kunde> {
const antwort = await fetch(`/api/kunden/${id}`);
if (!antwort.ok) {
throw new Error(
`Kunde ${id} konnte nicht geladen werden (HTTP ${antwort.status})`,
);
}
const daten: unknown = await antwort.json();
return KundeSchema.parse(daten); // wirft einen Fehler, wenn die Form nicht passt
}
Benennt die API ein Feld um, schlägt das Programm genau an dieser Stelle mit einer klaren Meldung fehl, statt drei Komponenten weiter mit „Cannot read properties of undefined“. Dasselbe Prinzip gilt für Fehler in catch-Blöcken: Unter strict haben sie den Typ unknown, weil in JavaScript jeder beliebige Wert geworfen werden kann. Ein instanceof Error vor dem Zugriff auf message ist deshalb keine Pedanterie.
Regel 3: Zustände mit Union-Typen beschreiben
Ein häufiges Muster in gewachsenem Code sind Objekte voller optionaler Felder: istGeladen, fehler?, daten?, versendetAm?. Welche Kombinationen gültig sind, steht nirgends. Der Compiler erlaubt auch unsinnige Zustände, etwa „geladen“ mit Fehlermeldung, aber ohne Daten.
Besser ist eine Discriminated Union, also eine Vereinigung mehrerer Objekttypen, die sich an einem gemeinsamen Feld unterscheiden lassen:
type Bestellung =
| { status: 'offen'; erstelltAm: Date }
| { status: 'bezahlt'; bezahltAm: Date }
| { status: 'versendet'; sendungsnummer: string }
| { status: 'storniert'; grund: string };
function statusText(b: Bestellung): string {
switch (b.status) {
case 'offen':
return 'Wartet auf Zahlung';
case 'bezahlt':
return `Bezahlt am ${b.bezahltAm.toLocaleDateString('de-DE')}`;
case 'versendet':
return `Unterwegs, Sendungsnummer ${b.sendungsnummer}`;
case 'storniert':
return `Storniert: ${b.grund}`;
default: {
// Wird ein neuer Status ergänzt, meldet der Compiler hier einen Fehler.
const unbehandelt: never = b;
return unbehandelt;
}
}
}
Zwei Dinge leistet dieses Muster. Innerhalb jedes case weiß TypeScript genau, welche Felder vorhanden sind: Nur eine versendete Bestellung hat eine Sendungsnummer. Und der never-Zweig im default macht die Prüfung vollständig. Kommt später ein Status „zurückgesendet“ hinzu, zeigt der Compiler jede Stelle, die ihn noch nicht behandelt. Gerade in größeren Codebasen ist das eine der wirksamsten Techniken, die TypeScript bietet.
Regel 4: Narrowing statt Typzusicherungen
Narrowing heißt, dass TypeScript den Typ eines Werts nach einer Prüfung automatisch einengt. Nach if (typeof wert === 'string') gilt wert im Block als Zeichenkette. Dasselbe funktioniert mit instanceof, mit dem Operator in, mit Vergleichen auf null und mit dem Diskriminator-Feld aus Regel 3.
Das Gegenstück sind Typzusicherungen. Mit as behauptet der Code einen Typ, mit dem Non-Null-Operator ! behauptet er, dass ein Wert vorhanden ist. Beides prüft zur Laufzeit nichts. Stimmt die Behauptung nicht, kommt der Fehler später und an anderer Stelle.
Wo eine Prüfung mehrfach gebraucht wird, lohnt sich eine eigene Funktion. Eine Assertion-Funktion wirft einen Fehler, wenn die Bedingung nicht erfüllt ist, und teilt TypeScript danach den engeren Typ mit:
export function sicherstellen<T>(
wert: T,
bezeichnung: string,
): asserts wert is NonNullable<T> {
if (wert === null || wert === undefined) {
throw new Error(`${bezeichnung} fehlt`);
}
}
const formular = document.querySelector<HTMLFormElement>('#bestellformular');
sicherstellen(formular, 'Bestellformular');
formular.addEventListener('submit', absenden); // formular ist jetzt HTMLFormElement
Ganz verbieten lassen sich Zusicherungen nicht. In Tests, bei schlecht typisierten Bibliotheken oder bei Daten, die nachweislich schon geprüft wurden, sind sie manchmal der pragmatische Weg. Dann gehört ein Kommentar dazu, warum die Zusicherung hier sicher ist.
Regel 5: satisfies und as const für Konfigurationen nutzen
Bei Konfigurationsobjekten stehen Teams oft vor einem Zielkonflikt. Eine Typangabe wie const config: Record<Umgebung, string> prüft, dass alle Umgebungen vorhanden sind, verliert aber die genauen Werte. Ohne Typangabe bleiben die Werte erhalten, aber Tippfehler fallen nicht auf. Der Operator satisfies, eingeführt mit TypeScript 4.9, löst das: Er prüft den Wert gegen einen Typ, ohne den abgeleiteten Typ zu überschreiben.
type Umgebung = 'entwicklung' | 'test' | 'produktion';
const apiBasis = {
entwicklung: 'http://localhost:3000',
test: 'https://test.example.com',
produktion: 'https://api.example.com',
} as const satisfies Record<Umgebung, string>;
// Fehlt eine Umgebung oder ist ein Schlüssel falsch geschrieben, meldet der Compiler das.
// apiBasis.produktion hat den genauen Typ 'https://api.example.com'.
as const sorgt dafür, dass TypeScript die Werte als unveränderliche Literale behandelt. Das macht es auch zur schlanken Alternative zu enum. Enums erzeugen eigenen JavaScript-Code und werden deshalb von Laufzeitumgebungen, die Typen nur entfernen, nicht unterstützt. Ein Objekt mit as const leistet im Alltag dasselbe:
export const Rolle = {
Admin: 'admin',
Redaktion: 'redaktion',
Gast: 'gast',
} as const;
export type Rolle = (typeof Rolle)[keyof typeof Rolle]; // 'admin' | 'redaktion' | 'gast'
Regel 6: Typen ableiten statt doppelt pflegen
Jeder Typ, der von Hand neben einem anderen gepflegt wird, kann veralten. Wer für dasselbe Datenmodell einen Typ für die Anzeige, einen für das Formular und einen für die API schreibt, hat nach einigen Monaten drei leicht verschiedene Wahrheiten. TypeScript bietet Werkzeuge, um Typen voneinander abzuleiten:
interface Produkt {
id: string;
name: string;
preisNetto: number;
lagerbestand: number;
erstelltAm: Date;
}
// Für die Listenansicht genügen wenige Felder.
type ProduktVorschau = Pick<Produkt, 'id' | 'name' | 'preisNetto'>;
// Beim Anlegen vergibt der Server id und erstelltAm.
type NeuesProdukt = Omit<Produkt, 'id' | 'erstelltAm'>;
// Bei Änderungen sind alle Felder optional.
type ProduktAenderung = Partial<NeuesProdukt>;
Dazu kommen typeof (Typ eines Werts), keyof (Schlüssel eines Typs) und ReturnType (Rückgabetyp einer Funktion). Die Schema-Ableitung mit z.infer aus Regel 2 folgt demselben Gedanken. Auch Typinferenz gehört hierher: Lokale Variablen brauchen selten eine Typangabe, weil TypeScript den Typ aus dem Wert ermittelt. Ausdrückliche Typen lohnen sich vor allem an Schnittstellen, also bei Parametern und Rückgabewerten exportierter Funktionen. Dort dokumentieren sie den Vertrag und verhindern, dass eine Änderung im Inneren unbemerkt den Rückgabetyp verschiebt.
Eine Warnung gehört dazu: Ableitungen können unlesbar werden. Verschachtelte Conditional Types und Mapped Types über mehrere Ebenen sind für Bibliotheken gerechtfertigt, im Anwendungscode meist nicht. Wenn ein Typ eine Erklärung von zehn Zeilen braucht, ist ein einfacherer, ausgeschriebener Typ oft die bessere Wahl.
Regel 7: Typen im Projekt sinnvoll ordnen
Auch die Ablage von Typen beeinflusst, wie gut ein Projekt wartbar bleibt. Eine einzelne Datei types.ts mit allen Typen der Anwendung wirkt anfangs ordentlich, wird aber schnell zum Sammelbecken, von dem jedes Modul abhängt. Bewährt hat sich eine andere Ordnung:
- Typen neben den Code legen, der sie verantwortet. Der Typ
Bestellunggehört in das Modul, das Bestellungen verarbeitet, und wird von dort exportiert. - Gemeinsame Verträge bewusst trennen. Typen, die Frontend und Backend teilen, etwa API-Schemata, liegen in einem eigenen Paket oder Verzeichnis. In Monorepos helfen Project References (
referencesin dertsconfig.json), solche Pakete getrennt zu prüfen. - Typ-Importe kennzeichnen.
import type { Kunde } from './kunden.js'macht sichtbar, dass nur ein Typ gebraucht wird. MitverbatimModuleSyntaxist diese Kennzeichnung Pflicht, und der Import verschwindet beim Übersetzen zuverlässig. - Unveränderlichkeit ausdrücken. Parameter wie
posten: readonly Posten[]zeigen, dass eine Funktion eine Liste nur liest. Der Compiler verhindert dann versehentlichespushodersortauf fremden Daten.
Wie sich Module, Schichten und Verzeichnisse darüber hinaus organisieren lassen, beschreibt der bereits erwähnte Entwickler-Ratgeber.
Regel 8: Regeln im Team automatisch durchsetzen
Gute Vorsätze halten in Code-Reviews selten lange. Was wichtig ist, sollte ein Werkzeug prüfen. Für TypeScript ist das typescript-eslint, die TypeScript-Erweiterung für den Linter ESLint. Seine strengeren Regelsätze nutzen Typinformationen und erkennen damit auch Fehler wie nicht abgewartete Promises:
// eslint.config.mjs
import eslint from '@eslint/js';
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';
export default defineConfig(
eslint.configs.recommended,
tseslint.configs.strictTypeChecked,
{
languageOptions: {
parserOptions: { projectService: true },
},
rules: {
'@typescript-eslint/switch-exhaustiveness-check': 'error',
'@typescript-eslint/consistent-type-imports': 'error',
},
},
);
Der Regelsatz strictTypeChecked enthält unter anderem Regeln gegen any, gegen den Non-Null-Operator und gegen unbehandelte Promises. Zusätzlich gehört tsc --noEmit in die CI-Pipeline, damit kein Code ohne vollständige Typprüfung zusammengeführt wird. Muss ein Fehler ausnahmsweise unterdrückt werden, ist // @ts-expect-error mit Begründung besser als // @ts-ignore: Es meldet sich, sobald der Fehler nicht mehr auftritt, und bleibt damit nicht als Altlast liegen.
Mit TypeScript 7 hat Microsoft den Compiler in der Programmiersprache Go neu geschrieben, Prüfungen großer Projekte laufen laut Hersteller um ein Vielfaches schneller. Version 7.0 bringt allerdings noch keine Programmierschnittstelle für andere Werkzeuge mit, eine neue ist erst für 7.1 angekündigt. Werkzeuge wie typescript-eslint arbeiten deshalb vorerst weiter mit TypeScript 6.0, das sich laut Microsoft parallel zu TypeScript 7 installieren lässt. Vor einem Umstieg lohnt ein Blick, welche Version die eingesetzten Werkzeuge unterstützen.
Was das für Ihr Team bedeutet
Nicht jede Regel bringt gleich viel. Den größten Nutzen haben erfahrungsgemäß drei Dinge: eine strenge Konfiguration, geprüfte Daten an den Systemgrenzen und Union-Typen für fachliche Zustände. Sie fangen die Fehler ab, die in Produktion am meisten kosten. satisfies, abgeleitete Typen und eine saubere Ablage machen den Code vor allem leichter änderbar.
Überschätzt wird dagegen oft die Raffinesse des Typsystems. Teams, die viel Zeit in komplexe Typkonstruktionen stecken, gewinnen selten mehr Sicherheit, aber verlieren Lesbarkeit. Unsere Empfehlung: lieber wenige, konsequent eingehaltene Regeln, die ein Linter durchsetzt, als ein ausgefeiltes Regelwerk, das nur in der Dokumentation steht.
Für Bestandsprojekte heißt das: nicht alles auf einmal umbauen. Ein sinnvoller Anfang ist eine Auswertung, wo any, as und ! am häufigsten vorkommen, und eine schrittweise Bereinigung, beginnend bei den Schnittstellen nach außen. Wer dabei Unterstützung sucht oder sein Team schulen möchte, findet bei MARTINSFELD Beratung, Coaching und Seminare zu TypeScript-Codequalität.
Häufige Fragen zu TypeScript Best Practices
Sollte jede Funktion einen ausdrücklichen Rückgabetyp haben?
Nicht jede. Für exportierte Funktionen und öffentliche Methoden ist ein ausdrücklicher Rückgabetyp sinnvoll, weil er den Vertrag festhält. Bei kurzen, internen Hilfsfunktionen und Callbacks genügt die Inferenz meist.
Sind Enums noch empfehlenswert?
Für neuen Code ist ein Objekt mit as const oder eine Union aus String-Literalen in den meisten Fällen die bessere Wahl. Beides funktioniert auch in Laufzeitumgebungen, die Typen nur entfernen, und erzeugt keinen zusätzlichen Code. Bestehende Enums müssen nicht sofort ersetzt werden.
Wie geht man mit vielen any in Bestandscode um?
Zuerst sichtbar machen, etwa mit der Lint-Regel no-explicit-any als Warnung, und neue Fälle verbieten. Dann die Stellen an Systemgrenzen durch unknown mit Prüfung ersetzen, weil dort der Nutzen am größten ist. Interne any lassen sich anschließend Modul für Modul bereinigen.
Interface oder Type – was ist besser?
Für Objektstrukturen sind beide gleichwertig. Viele Teams nutzen interface für Objekte und type für Unions und abgeleitete Typen. Wichtiger als die Wahl ist, dass das Team sie einheitlich trifft und im Linter festhält.
Kategorien