How to Fix the ‘Can’t Resolve react/jsx-runtime’ Error in Next.js Application

If you are working with Next.js and React, you might have encountered an error message that halts your development process. This error is often puzzling and can leave you scratching your head:

“Module not found: Can’t resolve ‘react/jsx-runtime'”

This issue appears when you’re building or running a Next.js application, and while it can be fixed, understanding the root cause is crucial. One strange aspect of this error is that it might not appear when using the turbo flag during execution. But when you try to run or build your project without this flag, the error resurfaces.

What Does the Error “Can’t Resolve ‘react/jsx-runtime'”?

Before diving into the solution, let’s take a closer look at what this error means. The message Module not found: Can't resolve 'react/jsx-runtime' is related to how React 17 and later versions handle JSX transformations. This particular error indicates that the required React JSX runtime is missing or misconfigured in your application.

What Is JSX Runtime:

With React 17 and newer, React introduced a new JSX transform that no longer requires React to be in scope when JSX is used. The JSX runtime is responsible for transforming JSX code into valid JavaScript function calls. This means that if the react/jsx-runtime module is not found, it’s likely that React is not set up properly in your project to handle JSX transformations.

Why Does This Error Occur:

The issue typically occurs because:

1. The correct version of React isn’t installed: React 17 introduced the new JSX transform, and if your version of React is too old, the required JSX runtime might not exist or be recognized.
2. Webpack or Next.js misconfigurations: Webpack might not resolve React correctly due to incorrect aliases or missing configurations.
3. Dependency mismatches: If the dependencies in your project are not aligned or if there are version mismatches between React and React DOM, it can lead to this error.
4. The --turbo flag workaround: The error doesn’t appear when you use the --turbo flag, which likely changes how dependencies are bundled or cached, but this doesn’t address the underlying cause.

Possible Causes for the Error

To better understand why this error happens, let’s look at the potential causes that could be contributing to it.

Incorrect React Version:

React 17 introduced the react/jsx-runtime module to enable the new JSX Transform. If you’re running an older version of React, such as React 16, this module might not be available. Moreover, the error could happen if your package.json file has a mismatch in the version numbers or if dependencies are not correctly installed.

Example from your package.json:

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

Here, you might be using an unsupported React version that doesn’t align with Next.js requirements.

Webpack Misconfiguration:

Next.js uses Webpack under the hood, and if your next.config.js (or next.config.ts for TypeScript users) is misconfigured, it may cause Webpack to fail when trying to resolve React modules.

In your next.config.ts file, you have custom Webpack configuration, and while this is fine, incorrect paths or missing alias configurations can prevent Next.js from correctly resolving React and React DOM.

For example:

config.resolve.alias = {
  ...config.resolve.alias,
  'react': require.resolve('react'),
  'react-dom': require.resolve('react-dom'),
};

If react/jsx-runtime is not included or misconfigured here, Webpack will not be able to find it.

Dependency Overriding Issues:

In your package.json, you are using a custom overrides field, which is designed to replace certain dependencies with others. However, if there’s a problem with this override, it may cause mismatches between versions of React or other dependencies that are needed to resolve react/jsx-runtime.

"overrides": {
  "react": "$react"
}

If $react points to a version of React that doesn’t support the new JSX runtime, the application will fail to resolve react/jsx-runtime.

Development Cache Issues:

When using the turbo flag, it’s possible that the build process or the caching mechanism within Next.js handles the resolution of dependencies differently. The --turbo flag could be skipping certain build steps that reveal errors when running or building without it.

How to Fix the Error

Now that we’ve outlined the causes, let’s take a step-by-step approach to fixing the error.

Ensure You Are Using React 17 or Later:

The first and most crucial step is to verify that you’re using React 17 or later. You can check this in your package.json under the dependencies section. Update it to match the correct version:

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

After updating the package.json, run the following command to install the correct dependencies:

npm install

Alternatively, if you’re using Yarn:

yarn install

Update Webpack Configuration:

Next.js uses Webpack to bundle your application, so it’s important that Webpack can resolve react/jsx-runtime. Check your next.config.ts to ensure that Webpack is correctly configured to resolve React and React DOM:

config.resolve.alias = {
  ...config.resolve.alias,
  'react': require.resolve('react'),
  'react-dom': require.resolve('react-dom'),
};

If everything is set correctly and you’re still encountering issues, you might also want to explicitly resolve react/jsx-runtime in the Webpack configuration. This would ensure that Webpack knows exactly where to find the JSX runtime.

Clear Next.js Cache:

If you’re encountering caching issues with the --turbo flag, clearing the cache might help. Run the following command to clear Next.js’ cache:

npm run dev -- --clear-cache

For production builds, you can also try deleting the .next directory manually:

rm -rf .next

Then rebuild your application:

npm run build

Fix Dependency Overrides:

Your package.json includes an overrides field that might be causing conflicts. Make sure that the $react variable correctly points to the intended React version, and that it doesn’t cause conflicts with react/jsx-runtime.

"overrides": {
  "react": "^17.0.2"
}

If $react is a custom variable, ensure that it points to a valid React version.

Ensure Correct JSX Runtime Configuration:

In your tsconfig.json, check the JSX settings. React 17+ requires the new JSX transform. Make sure the jsx option is set to react-jsx:

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

This tells TypeScript to use the new JSX runtime introduced in React 17.

Conclusion

The error Can't resolve 'react/jsx-runtime' is a common issue when using React 17 and later in Next.js applications, especially when there are version mismatches or incorrect configurations. By ensuring that you’re using the right version of React, updating your Webpack configuration, and clearing any cache-related issues, you can resolve this error and get your Next.js application up and running smoothly.