JSX-Fehler in TypeScript: das Flag --jsx und wie man ihn behebt

«Cannot use JSX unless the '--jsx' flag is provided» — was ist das für ein Ding?

Stellen Sie sich vor: Sie schreiben voller Begeisterung Ihre erste React-Anwendung in TypeScript. Der Code sieht perfekt aus, die Komponenten sind durchdacht, die Stimmung ist kämpferisch. Sie starten die Kompilierung — und plötzlich sehen Sie diese kalte, erschreckende Meldung:

Cannot use JSX unless the '--jsx' flag is provided.

Kommt Ihnen bekannt vor? Keine Sorge, Sie sind nicht allein. Dieser Fehler ist eine der häufigsten Fragen auf Stack Overflow mit tausenden von Aufrufen. Aber wie jedes Rätsel hat auch dieses eine einfache und elegante Lösung. In diesem Artikel werden wir den Fehler nicht nur beheben, sondern auch verstehen, warum er auftritt und wie Sie TypeScript ein für alle Mal für die Arbeit mit JSX konfigurieren.

Übrigens, wenn Sie gerade erst Ihre Reise in die Welt von TypeScript und React beginnen, empfehle ich Ihnen auch, unsere Materialien zu den Grundlagen von TypeScript durchzusehen — das hilft Ihnen, viele Fallstricke am Anfang zu vermeiden.

Warum beschwert sich TypeScript über JSX?

Lassen Sie uns die Natur dieses Fehlers verstehen. TypeScript ist eine strenge Sprache, die standardmäßig keine HTML-ähnliche JSX-Syntax versteht. Wenn Sie schreiben:

const element = <h1>Hallo, Welt!</h1>;

sieht TypeScript keinen bekannten Code, sondern etwas Fremdes. Um dem Compiler zu erklären, dass diese spitzen Klammern kein Fehler, sondern Teil Ihrer React-Komponente sind, müssen Sie explizit das Flag --jsx angeben. Es ist, als ob Sie TypeScript einen Dolmetscher geben: «Hör mal, diese Konstrukte sind gültiges JSX, fass sie nicht an, sondern verarbeite sie richtig».

Der Fehler tritt in drei typischen Fällen auf:

\n
• Neues Projekt — Sie haben vergessen, die tsconfig.json für die Arbeit mit React zu konfigurieren;
\n
• Migration von JavaScript — Sie übersetzen ein Projekt nach TypeScript, haben aber die Konfiguration nicht aktualisiert;
\n
• Verwendung von .tsx-Dateien — Sie haben eine Datei mit der Erweiterung .tsx erstellt, aber der Compiler weiß nicht, was er damit machen soll.
\n

Die gute Nachricht: Die Behebung dauert weniger als eine Minute. Die schlechte Nachricht: Wenn man nicht weiß, wo man suchen muss, kann man Stunden verlieren. Lassen Sie uns das ein für alle Mal beheben.

Schritt-für-Schritt-Lösung: Einrichtung der tsconfig.json

Der korrekteste und empfohlene Weg ist, die JSX-Einstellung in Ihrer tsconfig.json hinzuzufügen. Diese Datei ist das Gehirn Ihres TypeScript-Projekts. Hier sagen wir dem Compiler, wie er JSX verarbeiten soll.

Schritt 1: Öffnen Sie die tsconfig.json

Suchen Sie die Datei tsconfig.json im Stammverzeichnis Ihres Projekts. Wenn sie nicht existiert, erstellen Sie sie. Dies können Sie mit dem Befehl tun:

npx tsc --init

Dieser Befehl generiert eine grundlegende Konfigurationsdatei mit vielen auskommentierten Optionen. Keine Sorge — wir werden nur eine einzige Zeile ändern.

Schritt 2: Fügen Sie die jsx-Option hinzu

Fügen Sie innerhalb des Objekts compilerOptions die folgende Zeile hinzu (oder kommentieren Sie sie aus):

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // restliche Einstellungen...\n  }\n}

Beachten Sie: Der Wert "react-jsx" ist der moderne Standard für React 17+ und React 18. Wenn Sie eine ältere Version von React (vor 17) verwenden, können Sie "react" angeben. Ich empfehle jedoch nachdrücklich "react-jsx" — es erzeugt optimierteren Code und erfordert kein Importieren von React in jeder Datei.

Schritt 3: Speichern und Kompilierung neu starten

Nach dem Speichern der Änderungen sollte der Fehler verschwinden. Starten Sie den Build erneut:

npm run build\n# oder\nnpx tsc

Wenn Sie alles richtig gemacht haben, hört der Compiler auf, sich zu beschweren, und Ihre Anwendung wird gestartet.

Alternative Methoden: für fortgeschrittene Benutzer

Manchmal muss man schnell eine Hypothese testen oder ein einziges Skript ausführen. In solchen Fällen können Sie das Befehlszeilen-Flag verwenden:

npx tsc --jsx react-jsx app.tsx

Dies ist eine temporäre Lösung — sie ändert nicht die globalen Projekteinstellungen.