How To Fix the npm "Conflicting Peer Dependency" Error
Tags: javascript, programming, softwaredevelopment, softwareengineering
Published: 2024-01-19 21:36:21

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](https://nodejs.org/es/blog/npm/peer-dependencies) 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`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#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](https://blog.npmjs.org/post/618653678433435649/npm-v7-series-arborist-deep-dive.html) 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:

```shell
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:

```shell
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](https://github.blog/2021-02-02-npm-7-is-now-generally-available/#peer-dependencies):

- 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`](https://docs.npmjs.com/cli/v9/configuring-npm/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](https://yarnpkg.com/) 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:

```shell
npm install -g yarn
```

4\. Install the project's dependencies via Yarn with:

```shell
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:

```shell
npm cache clean --force
```

4\. Install the project's dependencies via npm with:

```shell
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.
  
***
_The post "[How To Fix the npm "Conflicting Peer Dependency" Error](https://writech.run/blog/how-to-fix-the-npm-conflicting-peer-dependency-error-fe5527f629a4/)" appeared first on [Writech](https://writech.run)._