All Articles

Explained: 'React' refers to a UMD global

Matt Pocock
Matt PocockMatt is a well-regarded TypeScript expert known for his ability to demystify complex TypeScript concepts.

If you're working with TypeScript and React, you've probably come across this error:

tsx
const Component = () => {
// React refers to a UMD global, but the
// current file is a module.
// Consider adding an import instead.
return <div>Hello world</div>;
};

This error is occurring because you've configured the jsx property in your tsconfig.json. Depending on what you're doing, you'll want to change this to preserve or react-jsx.

Quick Fix

If you're not using TypeScript to compile your application, you should change jsx to preserve in your tsconfig.json. Most modern frameworks won't use TypeScript to compile your application. So if you're not sure, choose this option.

json
{
"compilerOptions": {
"jsx": "preserve"
}
}

You should also restart your TS server.

If you are using TypeScript to compile your application, you should check if you're working with React 17 or later. If you are, you should change jsx to react-jsx in your tsconfig.json.

json
{
"compilerOptions": {
"jsx": "react-jsx"
}
}

If you're not, then keep jsx as react in your tsconfig.json and add import React from "react"; to the top of your file.

Explanation

The error happens when we have jsx set to react in the compilerOptions of our tsconfig.json.

The reason is that when TypeScript is set up like this, it assumes that it'll be transforming your JSX into React.createElement calls. So the code below:

tsx
const Component = () => {
return <div>Hello world</div>;
};

transforms to:

tsx
const Component = () => {
return React.createElement("div", null, "Hello world");
};

And here's the error. We don't have React in scope for this module, so this will cause a runtime error.

But since React 17, we haven't needed to import React to use JSX. So this error feels out of step with how React works today.

Stopping the Error

The thing this error shows is that you've probably misconfigured your tsconfig.json. Most React frameworks don't use TypeScript to handle this transformation. They'll use a tool like swc that runs faster, but doesn't do type checking.

TypeScript throws an error here because it assumes that you're using it to transform your JSX. And, you're probably not.

The safest bet is to change jsx to preserve in your tsconfig.json. This will tell TypeScript to leave your JSX alone and not throw an error when you forget to import React.

The Exception to the Rule

The only situation where this error would be helpful is if you're using React 16 or earlier. In that case, you'll need to import React to use JSX. So you should keep jsx as react in your tsconfig.json and add import React from "react"; to the top of your file.

The UMD Global is a red herring - it's not the real problem. The real problem is that you're using JSX without importing React.

Matt's signature

Share this article with your friends

`any` Considered Harmful, Except For These Cases

Discover when it's appropriate to use TypeScript's any type despite its risks. Learn about legitimate cases where any is necessary.

Matt Pocock
Matt Pocock

No, TypeScript Types Don't Exist At Runtime

Learn why TypeScript's types don't exist at runtime. Discover how TypeScript compiles down to JavaScript and how it differs from other strongly-typed languages.

Matt Pocock
Matt Pocock

Deriving vs Decoupling: When NOT To Be A TypeScript Wizard

In this book teaser, we discuss deriving vs decoupling your types: when building relationships between your types or segregating them makes sense.

Matt Pocock
Matt Pocock

NoInfer: TypeScript 5.4's New Utility Type

Learn how TypeScript's new utility type, NoInfer, can improve inference behavior by controlling where types are inferred in generic functions.

Matt Pocock
Matt Pocock