How to fix React version mismatch between packages in React

First, identify which React versions are currently installed in your project:

npm ls react
npm ls react-dom

This shows your dependency tree and highlights any duplicate installations. Look for multiple versions listed at different dependency depths. You can also check top-level dependencies:

npm ls --depth=0 | grep react

If you see multiple versions, note which packages are causing the duplication.

Open your package.json and ensure react and react-dom specify the same version without the caret (^) or tilde (~) prefix:

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

Remove the ^ character to prevent automatic minor version updates that could cause mismatches. If you're using React Native, include it as well:

{
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.72.0"
  }
}

Delete your node_modules and lock file, then reinstall from scratch:

# Remove existing installations
rm -rf node_modules
rm package-lock.json  # or yarn.lock / pnpm-lock.yaml

# Clear npm cache
npm cache clean --force

# Reinstall
npm install

For yarn users:

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

This ensures a fresh dependency resolution without conflicts from cached data.

If multiple React versions persist after reinstalling, use npm's deduplication tool:

npm dedupe

This attempts to reduce duplication by moving dependencies to the top level where possible. After running, verify the result:

npm ls react

You should see a single React version throughout the tree. If duplicates remain, you may have packages with incompatible peer dependency requirements.

Check which packages have outdated React requirements:

npm outdated

Update packages that have newer versions supporting your React version:

npm update <package-name>

For packages without updates, check their GitHub issues or documentation for React 19 compatibility. You may need to find alternative libraries or wait for updates. Use npx npm-check-updates to see major version updates:

npx npm-check-updates
npx npm-check-updates -u  # Update package.json
npm install

If some dependencies require older React versions but work fine with your current version, force resolution using package manager overrides.

For npm (v8.3+), add to package.json:

{
  "overrides": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

For yarn, use resolutions:

{
  "resolutions": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

For pnpm:

{
  "pnpm": {
    "overrides": {
      "react": "18.2.0",
      "react-dom": "18.2.0"
    }
  }
}

Then reinstall dependencies. Use this carefully as it may cause runtime issues with packages expecting different React APIs.

If you encounter ERESOLVE errors during installation, you have temporary workarounds:

npm install --legacy-peer-deps

This ignores peer dependency conflicts but may lead to runtime errors. A better approach:

npm install --force

This forces installation despite conflicts. However, the proper fix is updating or replacing incompatible packages rather than suppressing warnings. Only use these flags as a last resort for testing whether the mismatch is actually causing problems.