React UMD Global Error in Module Files

Problem

When migrating to Create React App 4.0 with TypeScript, developers encounter the error:

'React' refers to a UMD global, but the current file is a module.
Consider adding an import instead.ts(2686)

This occurs in .tsx files that use JSX syntax without explicitly importing React:

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

export default Users;

The error appears because TypeScript expects React to be available either as:

1. A module import, or
2. A global variable (UMD-style)

Since the file is treated as a module (not a script), TypeScript requires an explicit import for React.

Solutions

1. Enable New JSX Transformation (Recommended)

React 17+ introduced a new JSX transform that eliminates the need to import React in every file. To enable it:

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "target": "es2015"  // Required for JSX transformation
  }
}

Prerequisites

• TypeScript 4.1 or later
• React and React-DOM 17 or later
• Create React App 4.0+ (has this enabled by default)

2. Configure Babel for Custom Setups

If using a custom Webpack/Babel setup:

// babel.config.js
module.exports = {
  presets: [
    ["@babel/preset-react", {
      "runtime": "automatic" // Enables new JSX transformation
    }]
  ]
};

3. TypeScript Configuration Adjustments

Ensure your TypeScript configuration includes:

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "target": "es2015",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    ".storybook/*"  // Include additional directories if needed
  ]
}

4. VSCode-Specific Solutions

If using Visual Studio Code:

Restart TS Server

# Open command palette (Ctrl+Shift+P) and type:
TypeScript: Restart TS Server

Settings Adjustment

// .vscode/settings.json
{
  "js/ts.implicitProjectConfig.checkJs": false
}

5. Framework-Specific Configurations

For Vite users:

// tsconfig.node.json
{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

For Next.js users: The new JSX transform is enabled by default.

Troubleshooting Common Issues

File Location Problems

Ensure your files are in the correct location:

# Incorrect: File in root instead of src/
project-root/
  MyComponent.tsx  # ❌ May cause issues

# Correct: File in src directory
project-root/
  src/
    MyComponent.tsx  # ✅ Proper location

File Naming Issues

Avoid naming component files with .ts extension when they contain JSX:

# Incorrect
components/
  Dialog/
    Dialog.tsx
    Dialog.ts      # ❌ Should be index.ts

# Correct
components/
  Dialog/
    Dialog.tsx
    index.ts       # ✅ Proper naming

TypeScript Version Mismatch

Ensure VSCode uses the workspace TypeScript version:

1. Open command palette (Ctrl+Shift+P)
2. Type: TypeScript: Select TypeScript Version
3. Choose: Use Workspace Version

When to Import React Explicitly

Even with the new JSX transform, you may need to import React for:

import React from 'react'; // Required for React.FC type

const Title: React.FC = () => {
  return <>Hello World</>;
};

Alternative Solutions (Not Recommended)

Outdated Approaches

These solutions are workarounds rather than proper fixes:

// eslintrc.json (Not recommended)
{
  "globals": {
    "React": "readonly"
  }
}

// tsconfig.json (Not recommended)
{
  "compilerOptions": {
    "allowUmdGlobalAccess": true
  }
}

Summary

The 'UMD global' error occurs when TypeScript cannot resolve React in modules using JSX. The optimal solution is to enable React 17+'s new JSX transformation by setting "jsx": "react-jsx" in your TypeScript configuration and ensuring you meet the version requirements.

For most Create React App users, this should work out of the box in version 4.0+. For custom setups, ensure proper Babel and TypeScript configuration, and always verify that your development environment (especially VSCode) is using the correct TypeScript version.