React Testing Library: Cannot find module 'react-dom/client'

Problem Statement

When running tests with npm test, you encounter the following error:

Cannot find module 'react-dom/client' from 'node_modules/@testing-library/react/dist/pure.js'
Required stack:
node_modules/@testing-library/react/dist/pure.js
node_modules/@testing-library/react/dist/index.js

This error typically occurs when there's a version compatibility issue between your React version and the Testing Library version. From the provided package.json, we can see that React version 17.0.2 is being used with @testing-library/react version 13.0.0.

Root Cause

The core issue is a version compatibility conflict. According to the @testing-library/react release notes, version 13.0.0 and above dropped support for React 17 and below. These newer versions are designed to work specifically with React 18+.

WARNING

React 18 introduced a new react-dom/client API that replaces the previous react-dom rendering approach. Testing Library v13+ expects this new API, which doesn't exist in React 17.

Solutions

There are two primary solutions to resolve this compatibility issue:

Solution 1: Downgrade Testing Library (Recommended for React 17)

If you need to maintain React 17 compatibility, downgrade @testing-library/react to a version that supports it:

npm install @testing-library/react@12.1.5 --save-dev

Version 12.1.5 is the latest version that fully supports React 17 and doesn't require the react-dom/client module.

Solution 2: Upgrade React to Version 18+

If you can upgrade your React version, this is the forward-compatible approach:

npm install react@18 react-dom@18

After upgrading React, you may need to update other dependencies that might have compatibility requirements:

npm update --legacy-peer-deps

TIP

After upgrading to React 18, you'll need to update your application's entry point to use the new createRoot API instead of the deprecated ReactDOM.render() method.

Additional Troubleshooting Steps

If the issue persists after trying the solutions above, consider these additional steps:

1. Clear node_modules and reinstall:

   rm -rf node_modules
   npm install

2. Update type definitions (for TypeScript projects):

   npm install --save-dev @types/react@latest @types/react-dom@latest

3. Verify all dependencies are compatible:

   npm outdated

Code Example: React 18 Compatibility

If you choose to upgrade to React 18, here's how to update your application's entry point:

// Before (React 17)
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

// After (React 18)
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.getElementById('root');
const root = createRoot(container);
root.render(<App />);

Prevention

To avoid similar dependency conflicts in the future:

1. Always check the peer dependencies of packages before updating
2. Review library changelogs for breaking changes
3. Use semantic versioning awareness when updating packages
4. Consider using dependency management tools like Dependabot or Renovate

Conclusion

The "Cannot find module 'react-dom/client'" error is a clear indicator of version incompatibility between React Testing Library and React itself. The most straightforward solutions are either downgrading Testing Library to v12.x for React 17 projects or upgrading React to v18+ to use the latest Testing Library features.