Understanding and Resolving 'React' UMD Global Reference Errors in TypeScript

Error Phenomenon and Background

When migrating React projects to TypeScript, developers frequently encounter the following TypeScript compilation error: 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.ts(2686). This error typically occurs in React components with .tsx file extensions when using Create React App 4.0 or later versions.

A typical error scenario is shown below:

const Users = () => {
    return <>Teachers aka Users</>;
};

export default Users;

Root Cause Analysis

The fundamental cause of this error lies in the mismatch between TypeScript compiler configuration and React version. When the jsx option in tsconfig.json is set to react, TypeScript transforms JSX syntax into React.createElement calls, which requires React to be available in the current module's scope.

From a semantic perspective, TypeScript's compilation process can be understood as:

// Original JSX code
const Component = () => {
    return <div>Hello world</div>;
};

// TypeScript compiled code (when jsx is set to react)
const Component = () => {
    return React.createElement("div", null, "Hello world");
};

In the compiled code, the call to React.createElement depends on the global React object, but in modular files, if not explicitly imported, React will be unavailable, triggering the UMD global reference error.

React 17 New JSX Transform Mechanism

React 17 introduced a new JSX transform mechanism that no longer requires importing React in every file. The new transformation approach directly imports necessary JSX runtime functions from the React package, rather than relying on the global React object.

TypeScript 4.1 began supporting this new feature through the react-jsx and react-jsxdev values for the jsx compiler option. This support enables developers to use JSX without importing React while maintaining type safety.

Solutions and Configuration Optimization

To resolve the UMD global reference error, choose the appropriate configuration solution based on the specific project context:

Solution 1: Upgrade TypeScript and Configure react-jsx

For projects using React 17 or later, it's recommended to upgrade to TypeScript 4.1 or higher and configure in tsconfig.json:

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

The advantages of this configuration include:

• Full support for React 17's new JSX transform
• No need to import React in every file
• Better type checking and development experience
• Consistency with Create React App 4.0's default configuration

Solution 2: Use Preserve Mode

If the project uses other build tools (such as SWC, Babel, etc.) to handle JSX transformation, set jsx to preserve:

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

This configuration tells TypeScript to leave JSX syntax unchanged, allowing other build tools to handle the transformation, suitable for most modern React frameworks.

Solution 3: Traditional React Import Approach

For projects using React 16 or earlier, or situations where configuration upgrades are temporarily not feasible, add at the top of each file using JSX:

import React from 'react';

While this method is effective, it doesn't align with React 17 best practices and adds unnecessary code redundancy.

Version Requirements and Compatibility

To use the new JSX transform features, meet the following minimum version requirements:

• TypeScript: 4.1 or higher
• React: 17.0 or higher
• React-DOM: 17.0 or higher
• Create React App: 4.0 or higher (built-in support)

Practical Recommendations and Best Practices

Based on project实际情况, the following configuration strategies are recommended:

1. New Projects: Directly use Create React App 4.0+ and TypeScript 4.1+, configuring jsx: "react-jsx"
2. Existing Project Migration: Gradually upgrade dependency versions and unify configuration to react-jsx mode
3. Mixed Environments: If some components still need to support older versions, temporarily retain React imports and migrate gradually
4. Build Tool Integration: Ensure the build toolchain supports the new JSX transform to avoid configuration conflicts

Error Troubleshooting and Debugging Techniques

When encountering UMD global reference errors, follow these troubleshooting steps:

1. Check if TypeScript version is ≥4.1
2. Verify jsx configuration in tsconfig.json
3. Confirm React and React-DOM versions are ≥17.0
4. Restart TypeScript language server to apply configuration changes
5. Check for conflicting build tool configurations

Through proper configuration and version management, UMD global reference errors can be completely eliminated, allowing developers to enjoy the development conveniences brought by React 17's new features.