"React refers to a UMD global": How TypeScript Goes Crazy

Introduction: When the Compiler Says "No"

You open your favorite editor, write a few lines of TypeScript code, run the build — and suddenly you see this: 'React' refers to a UMD global, but the current file is a module. If you've ever encountered this error, you know how disheartening it can be. Everything seems correct: the import is there, React is installed, but the compiler stubbornly refuses to understand what you want from it.

This error is not just a random bug. It reveals the deep inner workings of TypeScript, build systems, and module formats. In this article, we won't just show you how to fix it. We'll look "under the hood" and understand why the React refers to a UMD global error occurs, how TypeScript distinguishes between UMD and ESM, and how to properly configure your project to forget about it forever.

The article is aimed at developers who are already familiar with React and TypeScript but want to understand the internal mechanics. Ready? Let's go!

What is UMD and Why Does TypeScript Know About It?

Before we break down the error, let's recall what module formats are in JavaScript. When you write import React from 'react', TypeScript needs to understand where this code comes from and how to use it. There are several standards:

\n
• ESM (ECMAScript Modules) — the modern standard using import/export.
\n
• CommonJS — the Node.js format with require/module.exports.
\n
• UMD (Universal Module Definition) — a hybrid that works both in the browser (via global variables) and in Node.js (via modules).
\n

React is distributed in several formats, including UMD. When you install React via npm, you get the ESM version (e.g., index.js with export default). But older versions or some builds may use UMD, where React is available as a global variable window.React.

TypeScript analyzes type declaration files (.d.ts). For React, this is the @types/react package. Inside it, there is a declaration that states: "React is available as a UMD global." When TypeScript sees that your file is marked as a module (e.g., contains import or export), it gets confused: "You are importing React, but the declaration says it's a global. And the file is a module. What should I do?"

Why Does the Error Occur: "React refers to a UMD global, but the current file is a module"?

The error appears when TypeScript cannot unambiguously determine how to handle the React import. Here is a typical scenario:

// 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

You run the compilation, and TypeScript throws an error: 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.

Why? Because in @types/react there is a declaration like this (simplified):

// in the index.d.ts file from @types/react\nexport = React;\nexport as namespace React;\n\ndeclare namespace React {\n    // ...types\n}\n

The key line is export as namespace React. It tells TypeScript: "This module is also available as a global variable React (UMD)." When your file is a module (contains export), TypeScript may not understand whether you want to use the global React or the imported one. The result is a conflict.

How to Fix It: Three Proven Methods

Method 1: Explicit Import (Most Common)

The simplest way is to ensure you explicitly import React, even if