«Could not find a declaration file»: Wie man TypeScript mit jedem JS-Modul befreundet

Der «unsichtbare» Fehler, den jeder TypeScript-Entwickler kennt

Sie schreiben Code in TypeScript, alles läuft reibungslos, aber plötzlich – eine rote Wellenlinie unter dem Import. Der Compiler meldet etwas Erschreckendes: Could not find a declaration file for module 'module-name'. '/path/to/module-name.js' implicitly has an 'any' type. Wenn Sie schon einmal mit TypeScript gearbeitet haben, sind Sie dieser Meldung sicherlich begegnet. Sie erscheint, wenn Sie versuchen, ein JavaScript-Modul zu importieren, für das keine Deklarationsdatei (normalerweise mit der Erweiterung .d.ts) existiert.

Auf Stack Overflow hat diese Frage tausende Aufrufe. Und das ist kein Zufall: Das Problem scheint komplex, obwohl es tatsächlich mehrere einfache und elegante Lösungen gibt. In diesem Artikel werden wir analysieren, warum der Fehler auftritt, und vier grundlegende Ansätze zu seiner Behebung vergleichen. Sie erfahren, welche Methode Sie je nach Situation wählen sollten, und können die «unsichtbaren» Typen für immer vergessen.

Warum verlangt TypeScript eine Deklaration?

TypeScript ist eine Erweiterung von JavaScript, die statische Typisierung hinzufügt. Wenn Sie import * as _ from 'lodash' schreiben, muss TypeScript wissen, welche Typen die Variable _ hat. Wenn für das Modul keine .d.ts-Datei vorhanden ist, kann der Compiler die Typen nicht überprüfen und weist dem Modul standardmäßig den Typ any zu. Dies verletzt die Strenge der Typisierung, weshalb TypeScript Sie warnt. Tatsächlich handelt es sich nicht um einen Laufzeitfehler, sondern um eine Compiler-Warnung, aber in strengen Projekten (strict: true) kann sie den Build blockieren.

Kommen wir nun zu den Lösungen. Wir betrachten vier Ansätze, vom einfachsten bis zum flexibelsten.

Lösung 1: Schnell und schmutzig – declare module

Der einfachste Weg ist, eine Deklarationsdatei manuell zu erstellen. Fügen Sie dazu Ihrem Projekt eine Datei global.d.ts (oder types.d.ts) hinzu und schreiben Sie:

// global.d.ts\ndeclare module 'module-name';

Diese Zeile sagt TypeScript: «Das Modul existiert, aber sein Typ ist any». Das Problem ist gelöst, aber Sie verlieren alle Vorteile der Typisierung. Dieser Ansatz eignet sich für schnelle Prototypen oder wenn das Modul nur an ein oder zwei Stellen verwendet wird. Für Produktionsprojekte ist dies jedoch nicht die beste Wahl.

\n
• Vorteile: Minimaler Code, keine Installation von Paketen erforderlich.
\n
• Nachteile: Der Typ any macht den Sinn von TypeScript zunichte; wenn das Modul aktualisiert wird, erfahren Sie nichts von API-Änderungen.
\n

Lösung 2: Verwendung von @types-Paketen

Für die meisten gängigen npm-Module gibt es separate Pakete mit Deklarationen. Für lodash ist dies beispielsweise @types/lodash. Installieren Sie sie über npm oder yarn:

npm install --save-dev @types/lodash

Danach findet TypeScript die Deklarationen automatisch und der Fehler verschwindet. Wenn Sie TypeScript 2.0+ verwenden, sucht es selbstständig nach dem @types-Ordner. Dies ist die Standard- und empfohlene Methode.

\n
• Vorteile: Vollständige Typisierung, Community-Support, automatische Updates.
\n
• Nachteile: Nicht für alle Module gibt es @types (z. B. für weniger bekannte Bibliotheken).
\n

Wie prüfen Sie, ob Typen vorhanden sind? Besuchen Sie die npm-Seite oder führen Sie npm info @types/modulname aus. Wenn das Paket nicht gefunden wird, fahren Sie mit der nächsten Lösung fort.

Lösung 3: Aktivieren von allowJs und checkJs

Wenn Sie ein Projekt schreiben, das TypeScript und JavaScript mischt, können Sie dem Compiler erlauben, JS-Dateien zu überprüfen. Fügen Sie dazu in tsconfig.json Folgendes hinzu:

{\n  "compilerOptions": {\n    "allowJs": true,\n    "checkJs": false\n  }\n}

Die Option allowJs erlaubt das Importieren von JS-Modulen in TS-Dateien. Dabei wird TypeScript versuchen