When working on an npm project, you may encounter a common error message that reads “conflicting peer dependency” while trying to install a package via npm. This error can be quite frustrating and slow down your development process.
In this article, you will understand what a peer dependency is, why this error occurs, and how to fix it.
Introduction to Peer Dependencies in npm 7+
Before digging into how to address the npm error, let’s focus on some key concepts you need to know.
What is a peer dependency?
In npm, a peer dependency is a package that needs another package to work but does not include it in its own installation. In other words, a peer dependency specifies that a package is compatible with a specific host tool or library, while not requiring it directly.
Peer dependencies are specified in the package.json file in the peerDependencies section. This mechanism is particularly useful when it comes to building npm plugins. When using a peer dependency, the npm module is saying, “I only work when plugged in to version x.y.z of a particular host package. So, if you install me, make sure it is alongside a compatible host.”
From version 4 to 6, npm stopped supporting automatic installation of peerDependencies due to technical issues with the deduplication algorithm. However, since version 7, npm relies on the Arborist algorithm to automatically install peerDependencies.
Why does the “conflicting peer dependency” error occur?
This error occurs when there is a conflict between the versions of the peer dependencies required by different packages your projects rely on. For example, if package A requires version 1.0 of a peer dependency, and package B requires version 2.0 of the same dependency, npm will not be able to resolve this conflict. As a result, it will throw that error.
Fix the “Conflicting Peer Dependency” Error in npm
There are several approaches to fixing the error. Let’s see them all.
1. Manually install the required peer dependencies
If npm fails because it cannot resolve the version <version> of the peer dependency <package>, simply install it with:
npm install <package>@<version>
Replace <package> with the name of the peer dependency and <version> with the required version number. Note that this is a viable solution only when the peer dependency is currently not present in your project.
2. Upgrade the conflicting packages
Updating packages that have peer dependencies to the latest version may solve the problem. This is because their peer dependencies might change accordingly and no longer conflict.
To do so, inspect the error returned by npm, identify the packages that are causing the error, and manually update them with an npm install command.
Keep in mind that upgrading to the new version of a package may require a lot of work, especially when it comes to a major version change. Rushing the transition to a new major version of a package can lead to new bugs and instability in the application.
3. Use the – legacy-peer-deps flag
A viable solution to the error is to run npm install with the --legacy-peer-deps flag as below:
npm install --legacy-peer-deps
The flag --legacy-peer-deps was added in npm 7 as a way to ignore peer dependencies and proceed with the installation anyway. That option was introduced because starting with npm 7:
- Peer dependencies are installed by default
- npm modules must specify a particular version of each peer dependency
This means that npm version 7 or higher is much stricter with peer dependencies than npm version 6. This is also the reason behind the popularity of the “conflicting peer dependency” npm error.
Thus, --legacy-peer-deps simply tells npm to install packages using the npm 6 algorithm to resolve peer dependencies.
If you want to avoid adding the --legacy-peer-deps flag every time you launch an npm i command, create a .npmrc file in the root folder of your project and initialize it as below:
legacy-peer-deps=true
Any npm command will now automatically contain the --legacy-peer-deps flag. This will solve the issue but may involve security risks and result in compatibility problems. The reason is that npm might end up installing packages that are not compatible with each other or packages with well-known security vulnerabilities.
4. Use Yarn instead of npm
Yarn is an alternative package manager to npm. Specifically, it has a more effective conflict resolution system compared to npm. So, Yarn uses a better algorithm than NPM when it comes to resolving peer dependencies. For this reason, switching to Yarn may solve the issue.
Follow the steps below to switch your npm project to Yarn:
1. Delete the node_modules folder in your project.
2. Back up your package-lock.json file and then delete it.
3. Globally install Yarn with the following command:
npm install -g yarn
4. Install the project’s dependencies via Yarn with:
yarn install
Your project now relies on Yarn as a project manager, and the error might disappear.
5. Clean up npm
Sometimes, you get a peer dependency error due to problems in npm’s cached modules. If none of the previous approaches worked, try doing a clean package installation.
Follow the steps below to clean up npm:
1. Delete the node_modules folder.
2. Delete the package-lock.json.
3. Clean the npm cache with:
npm cache clean --force
4. Install the project’s dependencies via npm with:
npm install
Et voilà! The “conflicting peer dependency” error should now be gone!
Conclusion
In this article, you saw what peer dependencies are and why the conflicting error occurs in npm 7+. Then, by adopting one of the five different solutions mentioned in this article, you learned how to fix the “conflicting peer dependency” npm error.
Thanks for reading! I hope you found this article helpful.
