TypeScript-Pfade in tsconfig.json: Alias-Importe richtig nutzen

Wie TypeScript-Aliase Ihnen Stunden Ihrer Lebenszeit sparen

Haben Sie schon einmal so etwas geschrieben wie import UserService from '../../../../../services/UserService'? Falls ja, kennen Sie den Schmerz. Die Augen schweifen ab, Refactoring wird zum Albtraum, und jede Dateiverschiebung zerbricht die gesamte Importkette. Glücklicherweise bietet TypeScript (und seine Konfigurationsdatei tsconfig.json) eine elegante Lösung – paths.

Aber die Frage ist: Wie funktioniert das unter der Haube? Warum können Sie, nachdem Sie den Alias "@/*" definiert haben, import { UserService } from '@/services/UserService' schreiben? Und vor allem: Warum funktioniert das manchmal ohne zusätzliche Build-Tool-Einstellungen (webpack, Vite, Rollup) nicht?

In diesem Artikel zeigen wir nicht nur, wie Sie paths in tsconfig.json konfigurieren. Wir werfen einen Blick in den Mechanismus, verstehen das path mapping, lernen, wie TypeScript Module auflöst, und vermeiden typische Fehler.

Was sind paths in tsconfig.json?

Paths ist ein Abschnitt in tsconfig.json, der es Ihnen erlaubt, benutzerdefinierte Zuordnungen (Mappings) zwischen Import-Aliasen und tatsächlichen Dateipfaden zu definieren. Einfach ausgedrückt: Sie sagen TypeScript: „Wenn du einen Import siehst, der mit @utils/ beginnt, suche die Datei stattdessen im Ordner src/utils/“.

So sieht das im Code aus:

// tsconfig.json\n{\n  "compilerOptions": {\n    "baseUrl": ".",\n    "paths": {\n      "@/*": ["src/*"],\n      "@utils/*": ["src/utils/*"],\n      "@components/*": ["src/components/*"]\n    }\n  }\n}\n

Jetzt schreiben Sie anstelle der schrecklichen relativen Pfade:

// Vorher (Albtraum)\nimport { formatDate } from '../../../../utils/dateHelpers';\n\n// Nachher (wunderschön)\nimport { formatDate } from '@utils/dateHelpers';\n

Ein gewaltiger Unterschied, oder? Aber wie versteht TypeScript, wohin es gehen muss?

Wie die Modulauflösung unter der Haube funktioniert

Um das path mapping in TypeScript zu verstehen, müssen wir uns den grundlegenden Mechanismus der Modulauflösung (Resolution) ansehen. Wenn TypeScript Ihren Code kompiliert, verwendet es eine Strategie, die Node.js ähnelt, aber mit zusätzlichen Fähigkeiten.

Der Prozess sieht so aus:

\n
1. Prüfung auf absoluten Pfad (beginnt mit /) – wenn ja, wird vom Wurzelverzeichnis des Dateisystems gesucht.
\n
2. Prüfung auf relativen Pfad (beginnt mit ./ oder ../) – wird relativ zur aktuellen Datei aufgelöst.
\n
3. Prüfung auf Alias aus paths – wenn der Import mit einem in paths definierten Präfix beginnt, ersetzt TypeScript ihn durch den entsprechenden Pfad aus dem Mapping.
4. Suche in node_modules – wenn nichts zutrifft, wird das Modul als npm-Paket gesucht.

Der entscheidende Punkt: TypeScript selbst ändert die physischen Pfade im kompilierten JavaScript nicht. Es prüft nur die Typen und gibt Fehler aus, wenn eine Datei nicht gefunden wird. Die Ersetzung der Aliase durch echte Pfade zur Laufzeit ist Aufgabe des Build-Tools (webpack, Vite, tsc-alias).

Warum paths nicht „out of the box“ funktionieren?

Hier ist die häufigste Frage auf Stack Overflow: „Ich habe paths konfiguriert, aber beim Starten der Anwendung erscheint der Fehler 'Cannot find module'“. Der Grund ist einfach: TypeScript ist ein Transpiler, kein Bundler.

Wenn Sie tsc ausführen, generiert es JS-Dateien, lässt die Aliase aber unverändert. Zum Beispiel bleibt import { foo } from '@utils/bar' im JS-Code so erhalten. Node.js (oder der Browser) weiß nichts von @utils und gibt einen Fehler aus.

Um dies zu beheben, müssen Sie eine der folgenden Lösungen verwenden:

\n
• tsc-alias – ein Tool, das nach der Kompilierung die Aliase durch echte Pfade ersetzt.
• module-alias – ein npm-Paket zur Registrierung von Aliasen in Node.js.