FR
RU
EN
ES
ZH
DE
PT
AR
HI
Introduction : quand le compilateur dit « non »
\nVous ouvrez votre éditeur préféré, écrivez quelques lignes de code en TypeScript, lancez la compilation — et soudain, vous voyez ceci : 'React' refers to a UMD global, but the current file is a module. Si vous avez déjà rencontré cette erreur, vous savez à quel point elle peut être déconcertante. Tout semble correct : l'import est là, React est installé, mais le compilateur refuse obstinément de comprendre ce que vous voulez.
Cette erreur n'est pas un simple bug aléatoire. Elle révèle les mécanismes profonds du fonctionnement de TypeScript, des systèmes de compilation et des formats modulaires. Dans cet article, nous ne nous contenterons pas de montrer comment la corriger. Nous allons regarder « sous le capot » et comprendre pourquoi l'erreur React refers to a UMD global se produit, comment TypeScript distingue UMD et ESM, et comment configurer correctement votre projet pour l'oublier à jamais.
\n\nCet article s'adresse aux développeurs qui connaissent déjà React et TypeScript, mais qui souhaitent comprendre les rouages internes. Prêts ? C'est parti !
\n\nQu'est-ce que UMD et pourquoi TypeScript le connaît-il ?
\n\nAvant d'analyser l'erreur, rappelons ce que sont les formats modulaires en JavaScript. Lorsque vous écrivez import React from 'react', TypeScript doit comprendre d'où vient ce code et comment l'utiliser. Il existe plusieurs standards :
- \n
- ESM (ECMAScript Modules) — le standard moderne utilisant
import/export. \n - CommonJS — le format Node.js avec
require/module.exports. \n - UMD (Universal Module Definition) — un hybride qui fonctionne à la fois dans le navigateur (via des variables globales) et dans Node.js (via des modules). \n
React est distribué dans plusieurs formats, dont UMD. Lorsque vous installez React via npm, vous obtenez une version ESM (par exemple, index.js avec export default). Mais les anciennes versions ou certaines compilations peuvent utiliser UMD, où React est disponible en tant que variable globale window.React.
TypeScript analyse les fichiers de déclaration de types (.d.ts). Pour React, il s'agit du paquet @types/react. À l'intérieur, il y a une déclaration qui indique : « React est disponible en tant que UMD global ». Lorsque TypeScript voit que votre fichier est marqué comme un module (par exemple, contient import ou export), il commence à s'embrouiller : « Vous importez React, mais la déclaration dit que c'est un global. Et le fichier est un module. Comment faire ? »
Pourquoi l'erreur se produit-elle : « React refers to a UMD global, but the current file is a module » ?
\n\nL'erreur apparaît lorsque TypeScript ne peut pas déterminer de manière univoque comment traiter l'import de React. Voici un scénario typique :
\n\n// 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;\nVous lancez la compilation, et TypeScript génère l'erreur : 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.
Pourquoi ? Parce que dans @types/react, il y a cette déclaration (simplifiée) :
// dans le fichier index.d.ts de @types/react\nexport = React;\nexport as namespace React;\n\ndeclare namespace React {\n // ...types\n}\nLa ligne clé est export as namespace React. Elle indique à TypeScript : « Ce module est également disponible en tant que variable globale React (UMD) ». Lorsque votre fichier est un module (contient export), TypeScript peut ne pas comprendre si vous voulez utiliser le React global ou celui importé. Résultat : un conflit.
Comment corriger : trois méthodes éprouvées
\n\nMéthode 1 : Import explicite (la plus courante)
\n\nLa méthode la plus simple consiste à s'assurer que vous importez explicitement React, même si
