Fix: Module not found: Can't resolve 'react/jsx-runtime' - Complete Solution Guide

The ‘Module not found: Can’t resolve react/jsx-runtime’ error is a common issue that React developers encounter when working with modern React applications. This error typically occurs when there’s a mismatch between React versions or when JSX runtime dependencies are missing or incorrectly configured.

This comprehensive guide explains what causes this error, why it happens, and provides multiple solutions to fix it in your React projects with clean code examples and directory structure.

---

What is react/jsx-runtime?

The react/jsx-runtime is a module introduced in React 17 that provides the runtime functions for the new JSX transform. It allows you to use JSX without explicitly importing React in your files, making your code cleaner and more efficient.

JSX Transform Evolution:

• React 16 and earlier: Required import React from 'react' in every file using JSX
• React 17+: Introduces automatic JSX transform, eliminating the need for explicit React imports

---

Common Error Messages:

• Module not found: Can't resolve 'react/jsx-runtime' in './src'
• Module not found: Error: Can't resolve 'react/jsx-runtime'
• Module not found: Can't resolve 'react/jsx-dev-runtime'

---

Understanding the Problem

The react/jsx-runtime error occurs when:

1. React version mismatch: Using React 17+ features with older React versions
2. Missing dependencies: The jsx-runtime package isn’t installed
3. Babel configuration issues: Incorrect JSX transform setup
4. Webpack configuration problems: Build tool not properly configured
5. Package manager conflicts: Inconsistent package installations

Typical React Project Structure:

my-react-app/
├── package.json
├── package-lock.json
├── node_modules/
├── src/
│   ├── App.jsx
│   ├── index.js
│   └── components/
│       └── MyComponent.jsx
└── public/
    └── index.html

---

Solution 1: Update React Dependencies

The most common cause is having outdated React dependencies. Update to the latest versions.

Step 1: Check Current Versions

npm list react react-dom

Step 2: Update React Packages

npm install react@latest react-dom@latest

Step 3: Verify Installation

npm list react react-dom

Updated package.json:

{
  "name": "my-react-app",
  "version": "0.1.0",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0"
  }
}

---

Solution 2: Install Missing JSX Runtime

If the jsx-runtime package is missing, install it explicitly:

npm install react-jsx-runtime

Or ensure it’s included as part of React:

npm install react react-dom --save

---

Solution 3: Configure Babel for JSX Transform

If you’re using custom Babel configuration, ensure it’s properly set up for the new JSX transform.

Step 1: Install Babel Dependencies

npm install --save-dev @babel/core @babel/preset-react

Step 2: Update babel.config.js

module.exports = {
  presets: [
    [
      '@babel/preset-react',
      {
        runtime: 'automatic', // This enables the new JSX transform
      },
    ],
  ],
};

Alternative: .babelrc Configuration

{
  "presets": [
    [
      "@babel/preset-react",
      {
        "runtime": "automatic"
      }
    ]
  ]
}

---

Solution 4: Configure Webpack for JSX

If you’re using a custom Webpack setup, ensure proper configuration:

webpack.config.js:

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-env',
              ['@babel/preset-react', { runtime: 'automatic' }]
            ]
          }
        }
      }
    ]
  }
};

---

Solution 5: Create-React-App Specific Fix

For Create-React-App projects, the issue often stems from outdated dependencies:

Step 1: Update React Scripts

npm install react-scripts@latest

Step 2: Clear Cache and Reinstall

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Step 3: Verify React Scripts Version

{
  "devDependencies": {
    "react-scripts": "^5.0.1"
  }
}

---

Solution 6: Vite Project Configuration

For Vite-based React projects, ensure proper configuration:

vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
})

Install Vite React Plugin:

npm install @vitejs/plugin-react --save-dev

---

Solution 7: Next.js Project Fix

For Next.js projects, ensure compatibility:

next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
}

module.exports = nextConfig

Update Next.js:

npm install next@latest

---

Solution 8: TypeScript Configuration

If using TypeScript, ensure proper configuration:

tsconfig.json:

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "es6"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx" // This is crucial for the new JSX transform
  },
  "include": [
    "src"
  ]
}

---

Solution 9: Environment-Specific Fixes

For Development:

# Clear cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
npm start

For Production Builds:

# Ensure production dependencies are correct
npm ci
npm run build

---

Solution 10: Package Manager Specific Fixes

Using Yarn:

yarn cache clean
rm -rf node_modules yarn.lock
yarn install

Using pnpm:

pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

---

Complete Project Structure After Fix

Standard React App:

my-react-app/
├── package.json
├── package-lock.json
├── node_modules/
├── public/
│   └── index.html
├── src/
│   ├── App.jsx
│   ├── index.js
│   └── components/
│       └── MyComponent.jsx
├── babel.config.js (if using custom Babel)
└── tsconfig.json (if using TypeScript)

Vite React App:

my-vite-app/
├── package.json
├── package-lock.json
├── node_modules/
├── public/
├── src/
│   ├── App.jsx
│   ├── main.jsx
│   └── components/
│       └── MyComponent.jsx
├── vite.config.js
└── tsconfig.json (if using TypeScript)

---

Working Code Examples

Before (Causing Error):

// This might cause issues if React version is incompatible
function App() {
  return <h1>Hello World</h1>;
}

export default App;

After (Fixed):

// With proper React version and configuration
import React from 'react'; // Optional in React 17+

function App() {
  return <h1>Hello World</h1>;
}

export default App;

Modern JSX (React 17+):

// No need to import React explicitly
function App() {
  return <h1>Hello World</h1>;
}

export default App;

---

Best Practices to Prevent This Error

1. Keep Dependencies Updated

# Regularly update React dependencies
npm update react react-dom

2. Use Consistent Versions

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

3. Verify JSX Runtime Configuration

{
  "compilerOptions": {
    "jsx": "react-jsx" // For React 17+
  }
}

4. Use Modern Build Tools

• Create-React-App (includes proper configuration)
• Vite with @vitejs/plugin-react
• Next.js (handles configuration automatically)

---

Debugging Steps

Step 1: Check React Version

npm list react

Step 2: Verify Node Modules

ls node_modules/react/

Step 3: Check for jsx-runtime

ls node_modules/react/jsx-runtime.js

Step 4: Clear and Reinstall

rm -rf node_modules package-lock.json
npm install

---

Common Mistakes to Avoid

1. Mixing React Versions

# ❌ Don't do this
npm install react@16 react-dom@18

2. Incorrect JSX Configuration

// ❌ Wrong
{
  "compilerOptions": {
    "jsx": "react"
  }
}

// ✅ Correct for React 17+
{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

3. Missing Dependencies

Always ensure both react and react-dom are installed with matching versions.

---

Performance Considerations

1. Bundle Size

The new JSX transform can reduce bundle size by eliminating React imports in each file.

2. Build Time

Proper configuration can improve build times and development experience.

3. Tree Shaking

Modern JSX runtime supports better tree shaking for smaller production bundles.

---

Security Considerations

1. Dependency Updates

Regularly update React dependencies to get security patches.

2. Verify Sources

Always install packages from official sources (npm, yarn registry).

3. Audit Dependencies

npm audit
npm audit fix

---

Testing the Fix

1. Development Server

npm start
# Should run without JSX runtime errors

2. Production Build

npm run build
# Should complete successfully

3. Unit Tests

npm test
# Should pass without import errors

---

Alternative Solutions

1. Revert to Classic JSX Transform

If issues persist, temporarily use the classic transform:

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

2. Explicit React Imports

Add explicit React imports to all JSX files:

import React from 'react';

function App() {
  return <h1>Hello World</h1>;
}

export default App;

---

Conclusion

The ‘Module not found: Can’t resolve react/jsx-runtime’ error is typically caused by React version mismatches or incorrect configuration. By following the solutions provided in this guide—updating dependencies, configuring build tools properly, and ensuring consistent versions—you can resolve this error and maintain a healthy React development environment.

The key is to keep your React dependencies up-to-date, use modern build tools that handle JSX configuration automatically, and follow React’s official documentation for the latest best practices. With these solutions implemented, your React applications will run smoothly without JSX runtime errors.

Remember to test thoroughly after implementing fixes and maintain consistent dependency versions across your development and production environments.