«React refers to a UMD global»: Wie TypeScript verrückt spielt

Einleitung: Wenn der Compiler «Nein» sagt

Sie öffnen Ihren Lieblingseditor, schreiben ein paar Zeilen TypeScript-Code, starten den Build – und plötzlich sehen Sie dies: 'React' refers to a UMD global, but the current file is a module. Wenn Sie jemals auf diesen Fehler gestoßen sind, wissen Sie, wie verwirrend er sein kann. Scheinbar ist alles richtig: Der Import ist vorhanden, React ist installiert, aber der Compiler weigert sich hartnäckig zu verstehen, was Sie von ihm wollen.

Dieser Fehler ist nicht einfach ein zufälliger Bug. Er offenbart tiefe Mechanismen von TypeScript, Build-Systemen und Modulformaten. In diesem Artikel zeigen wir nicht nur, wie man ihn behebt. Wir schauen «unter die Haube» und verstehen, warum der Fehler React refers to a UMD global auftritt, wie TypeScript zwischen UMD und ESM unterscheidet und wie Sie Ihr Projekt richtig konfigurieren, um ihn für immer zu vergessen.

Der Artikel richtet sich an Entwickler, die bereits mit React und TypeScript vertraut sind, aber die internen Abläufe verstehen möchten. Bereit? Los geht's!

Was ist UMD und warum kennt TypeScript es?

Bevor wir den Fehler analysieren, erinnern wir uns an die Modulformate in JavaScript. Wenn Sie import React from 'react' schreiben, muss TypeScript verstehen, woher dieser Code kommt und wie er verwendet wird. Es gibt mehrere Standards:

\n
• ESM (ECMAScript Modules) – der moderne Standard mit import/export.
\n
• CommonJS – das Node.js-Format mit require/module.exports.
\n
• UMD (Universal Module Definition) – ein Hybrid, der sowohl im Browser (über globale Variablen) als auch in Node.js (über Module) funktioniert.
\n

React wird in mehreren Formaten verbreitet, einschließlich UMD. Wenn Sie React über npm installieren, erhalten Sie die ESM-Version (z. B. index.js mit export default). Ältere Versionen oder bestimmte Builds können jedoch UMD verwenden, bei dem React als globale Variable window.React verfügbar ist.

TypeScript analysiert Typdeklarationsdateien (.d.ts). Für React ist dies das Paket @types/react. Darin gibt es eine Deklaration, die besagt: «React ist als UMD global verfügbar». Wenn TypeScript sieht, dass Ihre Datei als Modul markiert ist (z. B. import oder export enthält), gerät es in Verwirrung: «Sie importieren React, aber die Deklaration sagt, es sei ein Global. Die Datei ist jedoch ein Modul. Wie soll ich das handhaben?»

Warum tritt der Fehler auf: «React refers to a UMD global, but the current file is a module»?

Der Fehler erscheint, wenn TypeScript nicht eindeutig bestimmen kann, wie der React-Import verarbeitet werden soll. Hier ist ein typisches Szenario:

// App.tsx\nimport React from 'react';\nimport { useState } from 'react';\n\nconst App: React.FC = () => {\n    const [count, setCount] = useState(0);\n    return <div>{count}</div>;\n};\n\nexport default App;\n

Sie starten die Kompilierung und TypeScript gibt den Fehler aus: 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.

Warum? Weil es in @types/react folgende Deklaration gibt (vereinfacht):

// in der Datei index.d.ts von @types/react\nexport = React;\nexport as namespace React;\n\ndeclare namespace React {\n    // ...Typen\n}\n

Die entscheidende Zeile ist export as namespace React. Sie sagt TypeScript: «Dieses Modul ist auch als globale Variable React (UMD) verfügbar». Wenn Ihre Datei ein Modul ist (enthält export), kann TypeScript nicht eindeutig erkennen, ob Sie das globale React oder das importierte verwenden möchten. Die Folge ist ein Konflikt.

Wie man es behebt: Drei bewährte Methoden

Methode 1: Expliziter Import (die häufigste)

Der einfachste Weg ist, sicherzustellen, dass Sie React explizit importieren, auch wenn