[HOW TO FIX] NPM conflicting peer dependency error

Introduction

A common frustration when working with front-end or node projects is dealing with NPM dependency hell! NPM is a great tool to manage packages for your projects, but you can waste hours when dependency issues arises.

In this post, I will go over a recent error that I was having with peer dependencies and a few ways I approached to resolve it.

Some common error messages that you can see from this includes

...
Installing NPM modules using NPM version 7.11.1
npm ERR! code ERESOLVE
npm ERR! ERESOLVE is unable to resolve the dependency tree
npm ERR!
npm ERR! Found: compression-webpack-plugin@3.1.0
npm ERR! node_modules/compression-webpack-plugin
npm ERR!   compression-webpack-plugin@"9.0.1" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! compression-webpack-plugin@"9.0.1" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: webpack@5.64.4
npm ERR! node_modules/webpack
npm ERR!   peer webpack@"^5.1.0" from compression-webpack-plugin@9.0.1
npm ERR!   node_modules/compression-webpack-plugin
npm ERR!     compression-webpack-plugin@"9.0.1" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
...
...

Alternatively, you can see the following similar warning:

npm WARN react-datepicker@0.25.0 requires a peer of react@^0.14.0 but none was installed.

There are a few simple steps you can take to troubleshoot and resolve this issue.

1. Check for incompatible versions and upgrade the versions with NPM
2. Use npm install --save --legacy-peer-deps
3. Use the Yarn package manager: Yarn is an alternative package manager which can help resolve peer dependencies conflicts more quickly than NPM.
4. Downgrade your version of NPM
5. Try to run npm cache clean --force and npm i --force
6. Remove the node_modules folder and then package-lock.json. Then install all packages again.

1. Check for incompatible versions and upgrade the versions with NPM

Lets consider a scenario of using webpack and compression-webpack-plugin in our project.

We currently have the following versions dependencies with webpack:

• webpack version 5.1.0
• compression-webpack-plugin version 3.1.0

Now when we try to update webpack to version 5.64.4, we get the following error:

...
Installing NPM modules using NPM version 7.11.1
npm ERR! code ERESOLVE
npm ERR! ERESOLVE is unable to resolve the dependency tree
npm ERR!
npm ERR! Found: compression-webpack-plugin@3.1.0 ❌
npm ERR! node_modules/compression-webpack-plugin
npm ERR!   compression-webpack-plugin@"9.0.1" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! compression-webpack-plugin@"9.0.1" from the root project ❌
npm ERR!
npm ERR! Conflicting peer dependency: webpack@5.64.4 ❌
npm ERR! node_modules/webpack
npm ERR!   peer webpack@"^5.1.0" from compression-webpack-plugin@9.0.1
npm ERR!   node_modules/compression-webpack-plugin
npm ERR!     compression-webpack-plugin@"9.0.1" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
...
...

First lets understand the error that is comming up. The trace just says that we are trying to update our webpack version to version 5.64.4.

However, when we have a peer dependency of compression-webpack-plugin version 9.0.1 that could not be found in the project directory.

(Note: We currently have compression-webpack-plugin version 3.1.0)

To fix this, update our compression-webpack-plugin to version 9.0.1 thats required!

2. Use npm install --save --legacy-peer-deps

Another quick and easy solution is to run npm install with the flag --legacy-peer-deps:

npm install --save --legacy-peer-deps

With NPM versions 7.x, it is more strict with peer dependencies than in NPM version 6.x. NPM 7.x version have the following requirements for peer dependencies:

• install peer dependencies by default. This is not required in previous versions.
• modules MUST have peer dependencies specified or it will throw an error

The flag --legacy-peer-deps just tells NPM to install packages, but use the version 6 algorithm to resolve peer dependencies.

3. Use the Yarn package manager: Can help resolve peer dependencies conflicts more quickly than NPM.

Consider the following Angular error with peer dependencies:

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: project-admin@11.0.0
npm ERR! Found: @angular/common@11.0.3
npm ERR! node_modules/@angular/common
npm ERR!   @angular/common@"11.0.3" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/common@"^9.1.0 || ^10.0.0" from @agm/core@3.0.0-beta.0
npm ERR! node_modules/@agm/core
npm ERR!   @agm/core@"3.0.0-beta.0" from the root project

In the above error @agm/core@3.0.0-beta.0 requires @angular/common version ^9.1.0 or ^10.0.0.

And the actual @angular/common version 11.0.3.

One tip is to use the Yarn package manager instead of NPM. Yarn is pretty a wrapper around NPM, but it contains features thats more of an improvement.

Steps to use Yarn and fix this peer dependency error are as follows:

1. Delete the node_modules folder in your project.
2. Delete the package-lock.json files. You may need to back up your project first. Note: Do not delete 1package.json1. We will need this to install our packages!
3. Run the command to install yarn: npm i yarn. (We can install globally with the -g flag)
4. Go to the root directory of your project and run the command yarn install.

If you are already using yarn, we can use the following command:

yarn add @angular/common@10.0.0

Hopefully this should fix up the peer dependency issue!

4. Downgrade your version of NPM (from version 7.x+ to 6.x)

If you are using NPM 7.x or higher, this will most likely break your code than with NPM version 6.x or below. One key difference with NPM version 7.x is that it installs peer dependencies by default!

This can cause version/dependency conflicts and introduce breaking the installation process.

We see this issue most commonly with React v17+ projects (or version 18 now). Alot of React modules did not include the peer dependency of React v17 and when you run npm install, it will give the unable to resolve dependency tree error.

Since NPM version 7.x requires peer dependencies to be explicitly specified, this error will fire whenever a module (or any of its own dependencies) lists a previous major version of React as a peerDependency without specifically including React v17 as well.

5. Try to run npm cache clean --force and npm i --force

One fix is to try:

npm cache clean --force
npm i --force

Sometimes, your depencies are correct, but you still get the conflicting peer dependency error. This could be due to NPM still looking through the cached modules.

NPM usually stores modules in your local project folder and also a “cached” folder. This will be ~/.npm on linux/ OSX systems, or %AppData%/npm-cache for windows systems.

So the next time you install a similar module it will go off to the cache instead of downloading it! The above command just clears the cache folder.

6. Remove the node_modules folder and then package-lock.json. Then install all packages again.

If the above steps do not work, we can try to do a clean installation of the packages. To do this follow the steps below:

• Delete node_modules folder. This is where all the packages are saved.
• Delete the package-lock.json.
• Run npm install
• Run npm install --legacy-peer-deps if the above still giving conflict errors

💡 What is a peer dependency anyway?

A peer dependency is similar to regular dependencies, but they do not have a “strong” link between packages. They can exist without the package being installed.

As an example, lets say that we are building a calendar component for React - “awesome-calendar”. This allows people with React projects to use. We then have the following peer dependencies:

"peerDependencies": {
  "react": "^17.0.1",
  "react-dom": "^17.0.1"
}

This just means that our calendar component will require React version 17 and React-Dom version 17. It is up to the developer that is using our component to have those React and React-Dom versions in their projects!

If not, then the unable to resolve dependency tree error will appear!

We can also set the range of peer dependencies as well:

"peerDependencies": {
  "react": "16.8 - 17"
}

The intention of peer dependencies is to pass on any conflicts to the developer to resolve since this cannot be done with a package manager.

A great write up of peer dependencies is located on the official Node website: https://nodejs.org/en/blog/npm/peer-dependencies/

💡 Tip: Check the peer dependency of a module before installing it

When install a module, NPM doesnt really list the peer dependencies for that. However we can get around that by using the command before or after you install it to your project.

npm info name-of-module peerDependencies

The above will give you a list of peer dependencies and the compatible versions that it uses

As an example, when we run for react-datepicker: npm info react-datepicker peerDependencies, it gives us the following list:

{
  react: '^16.9.0 || ^17 || ^18',
  'react-dom': '^16.9.0 || ^17 || ^18'
}

Summary

In this post we went over several reasons why we are getting conflicts with peer dependencies in NPM. This give us the dreaded unable to resolve dependency tree error.

This is usually caused by how the algorithm to manage peer dependencies is used with NPM version 7.x+.

To get around this we can do the following:

• use the --legacy-peer-deps flag to use legacy peer dependency algorithm
• Downgrade our NPM version from 7.x+ to version 6.x
• Use Yarn instead of NPM
• Clear NPM cache, delete node_module and package-lock.json files!