ES
RU
EN
ZH
FR
DE
PT
AR
HI
Introducción: cuando el compilador dice «no»
\nAbre tu editor favorito, escribes unas líneas de código en TypeScript, ejecutas la compilación — y de repente ves esto: 'React' refers to a UMD global, but the current file is a module. Si alguna vez te has encontrado con este error, sabes lo desconcertante que puede ser. Todo parece correcto: la importación está, React está instalado, pero el compilador se niega obstinadamente a entender lo que quieres de él.
Este error no es solo un bug aleatorio. Revela los mecanismos profundos de funcionamiento de TypeScript, los sistemas de compilación y los formatos modulares. En este artículo no solo mostraremos cómo solucionarlo. Miraremos «bajo el capó» y entenderemos por qué ocurre el error React refers to a UMD global, cómo TypeScript distingue entre UMD y ESM, y cómo configurar correctamente tu proyecto para olvidarte de él para siempre.
\n\nEl artículo está dirigido a desarrolladores que ya conocen React y TypeScript, pero quieren entender los entresijos internos. ¿Listos? ¡Allá vamos!
\n\n¿Qué es UMD y por qué TypeScript lo conoce?
\n\nAntes de analizar el error, recordemos qué son los formatos modulares en JavaScript. Cuando escribes import React from 'react', TypeScript debe entender de dónde viene ese código y cómo usarlo. Existen varios estándares:
- \n
- ESM (ECMAScript Modules) — el estándar moderno que usa
import/export. \n - CommonJS — el formato de Node.js con
require/module.exports. \n - UMD (Universal Module Definition) — un híbrido que funciona tanto en el navegador (a través de variables globales) como en Node.js (a través de módulos). \n
React se distribuye en varios formatos, incluido UMD. Cuando instalas React a través de npm, obtienes la versión ESM (por ejemplo, index.js con export default). Pero las versiones antiguas o algunas compilaciones pueden usar UMD, donde React está disponible como una variable global window.React.
TypeScript analiza los archivos de declaración de tipos (.d.ts). Para React, este es el paquete @types/react. Dentro de él hay una declaración que indica: «React está disponible como UMD global». Cuando TypeScript ve que tu archivo está marcado como módulo (por ejemplo, contiene import o export), comienza a confundirse: «Estás importando React, pero en la declaración se dice que es global. Y el archivo es un módulo. ¿Qué hago?»
¿Por qué ocurre el error: «React refers to a UMD global, but the current file is a module»?
\n\nEl error aparece cuando TypeScript no puede determinar de manera inequívoca cómo procesar la importación de React. Este es un escenario típico:
\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;\nEjecutas la compilación y TypeScript muestra el error: 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.
¿Por qué? Porque en @types/react existe esta declaración (simplificada):
// en el archivo index.d.ts de @types/react\nexport = React;\nexport as namespace React;\n\ndeclare namespace React {\n // ...tipos\n}\nLa línea clave es export as namespace React. Le dice a TypeScript: «Este módulo también está disponible como variable global React (UMD)». Cuando tu archivo es un módulo (contiene export), TypeScript puede no entender si quieres usar el React global o el importado. El resultado es un conflicto.
Cómo solucionarlo: tres métodos comprobados
\n\nMétodo 1: Importación explícita (el más común)
\n\nLa forma más sencilla es asegurarte de que importas React explícitamente, incluso si
