Resolving NPM Peer Dependency Conflicts

5 min readMay 24, 2024

In one of my previous posts I have talked about the difference between npm installand npm ci[1]. This time I would like to address peer dependency conflicts and the installation of dependencies with the additional option --legacy-peer-deps or --force.

Sometimes, addressing peer-dependency conflicts may involve installing dependencies with additional options like --legacy-peer-deps or --force.

What’s the problem with these options?

Using options like --legacy-peer-deps or --force can bypass peer dependency checks and potentially lead to compatibility issues or unexpected behavior. While they may offer a temporary solution, it’s important to use them with caution. It’s generally recommended to resolve peer dependency conflicts by updating package versions or adjusting dependency declarations whenever possible.

In recent months, I’ve observed developers grappling with npm dependency installations, particularly when encountering conflicting peer dependencies. Here are some of the questions I’ve come across:

I ran npm install --legacy-peer-deps, but I received an error at build time indicating that some dependencies are missing.
All conflicting dependencies will be skipped from installation. In this case, npm i --force has to be used.
I ran npm install --force, but I received an error at build time indicating that some dependencies are missing.
The settings in the .npmrc overrule the manually added options. In this case, legacy-peer-deps=true was set and the installation was done via --npm i --legacy-peer-deps
I ran npm install --legacy-peer-deps and encountered an error at build time due to missing dependencies. To address this, I deleted the package-lock.json file and attempted the installation again. However, running npm install --force did not resolve the issue. Why didn't it work? I thought --force would always resolve such problems.
As there was no package-lock.json present, this file was re-generated during the installation, resulting in a different dependency tree due to the --legacy-peer-deps option. Consequently, the conflicting dependencies were skipped during the installation and are not present in the new package-lock.json. Therefore, even running npm install --force will not resolve the issue. The changes in the package-lock.json must be reverted, and then npm install --force should be run.

The root cause of these issues is conflicting dependencies, which means that running npm install will not resolve them without additional options. This situation not only leads to frustration but also requires additional time and effort to rectify.

Let’s explore how to resolve this situation effectively.

Resolving conflicting peer-dependencies

Here are some examples of peer dependency conflicts and how to resolve them.

1. Peer-Dependency-Conflict

Version mismatch between @angular/compiler, @angular/compiler-cli, and @angular-devkit/build-angular.

npm ERR! While resolving: test-ui@1.0.22
npm ERR! Found: @angular-devkit/build-angular@16.2.1
npm ERR! node_modules/@angular-devkit/build-angular
npm ERR!   dev @angular-devkit/build-angular@"^16.2.12" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! dev @angular-devkit/build-angular@"^16.2.12" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: @angular/compiler@16.2.12
npm ERR! node_modules/@angular/compiler
npm ERR!   peer @angular/compiler@"16.2.12" from @angular/compiler-cli@16.2.12
npm ERR!   node_modules/@angular/compiler-cli
npm ERR!     dev @angular/compiler-cli@"^16.2.4" from the root project
npm ERR!     peer @angular/compiler-cli@"^16.0.0" from @angular-devkit/build-angular@16.2.14
npm ERR!     node_modules/@angular-devkit/build-angular
npm ERR!       dev @angular-devkit/build-angular@"^16.2.12" from the root project
npm ERR!     2 more (@angular/localize, ng-packagr)

2. Solution

Ensure that all Angular packages are using compatible versions. Align the versions of @angular/compiler, @angular/compiler-cli, and @angular-devkit/build-angular

"devDependencies": {
  "@angular-devkit/build-angular": "16.2.12",
  "@angular/compiler-cli": "16.2.12",
  "@angular/compiler": "16.2.12",
}

2. Peer-Dependency-Conflict

@angular/elements requires version 16.2.12, but @angular/core was found in version 16.2.4.

npm ERR! While resolving: @angular/elements@16.2.12
npm ERR! Found: @angular/core@16.2.4
npm ERR! node_modules/@angular/core
npm ERR!   @angular/core@"^16.2.4" from the root project
npm ERR!   peer @angular/core@"16.2.4" from @angular/animations@16.2.4
npm ERR!   node_modules/@angular/animations
npm ERR!     @angular/animations@"^16.2.4" from the root project
npm ERR!     peerOptional @angular/animations@"16.2.4" from @angular/platform-browser@16.2.4
npm ERR!     node_modules/@angular/platform-browser
npm ERR!       @angular/platform-browser@"^16.2.4" from the root project
npm ERR!       5 more (@angular/forms, @angular/platform-browser-dynamic, ...)
npm ERR!     1 more (@test-platform/core)
npm ERR!   22 more (@angular/common, @angular/compiler, @angular/forms, ...)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/core@"16.2.12" from @angular/elements@16.2.12
npm ERR! node_modules/@angular/elements
npm ERR!   peer @angular/elements@">=14.0.0 <17.0.0" from test-library@4.1.2
npm ERR!   node_modules/test-library
npm ERR!     test-library@"^4.1.2" from the root project
npm ERR!     1 more (@test/test-api)

2. Solution

The peer dependency@angular/elements requires a newer angular version. Therefore, we need to specify this peer dependency as a direct dependency in the package.json.

"dependencies": {
    "@angular/animations": "16.2.4",
    "@angular/common": "16.2.4",
    "@angular/compiler": "16.2.4",
    "@angular/core": "16.2.4",
    "@angular/elements": "16.2.4",
    ...
}

3. Peer-Dependency-Conflict

@ng-select/ng-option-highlight@0.0.7 requires @angular/common between 13.0.0 and 14.0.0, but your project uses @angular/common@16.2.12.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: @ng-select/ng-option-highlight@0.0.7
npm ERR! Found: @angular/common@16.2.12
npm ERR! node_modules/@angular/common
npm ERR!   @angular/common@"^16.1.2" from the root project
npm ERR!   peer @angular/common@"16.2.12" from @angular/forms@16.2.12
npm ERR!   node_modules/@angular/forms
npm ERR!     @angular/forms@"^16.1.2" from the root project
npm ERR!     peer @angular/forms@">=14.0.0 <17.0.0" from @test-platform/font@8.1.10
npm ERR!     node_modules/@test-platform/font
npm ERR!       @ju30-platform/font@"^8.1.1" from the root project
npm ERR!       3 more (@test-platform/common, @test-platform/component, @test-platform/core)
npm ERR!     3 more (@test-platform/services, @ng-select/ng-select, @ngneat/reactive-forms)
npm ERR!   15 more (@angular/platform-browser, ...)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/common@">=13.0.0 <14.0.0" from @ng-select/ng-option-highlight@0.0.7
npm ERR! node_modules/@ng-select/ng-option-highlight
npm ERR!   @ng-select/ng-option-highlight@"^0.0.7" from the root project
npm ERR!   peer @ng-select/ng-option-highlight@"^0.0.7" from @test-platform/component@8.1.10

3. Solution

The best way to resolve this issue is to update @ng-select/ng-option-highlight in the repository the peer dependency is defined as direct dependency. However, if this is not an option, we can override the dependency with a newer version of @ng-select/ng-option-highlight that supports Angular 16.

"overrides": {
    "@ng-select/ng-option-highlight": "11.1.2",
}

4. Resolving Conflicting Peer Dependencies with ChatGPT

When faced with a peer dependency conflict that isn’t immediately apparent, ChatGPT can swiftly assist in identifying the issue. I’ve utilized it in such instances when the error message wasn’t immediately clear to me.

Moreover, ChatGPT will instantly provide a solution to the problem, allowing for swift resolution of the issue.

Summing Up

I’ve presented some issues regarding conflicting peer dependencies. These conflicts not only lead to frustration during npm installations but also consume a significant amount of time. Consequently, it’s crucial to clear these conflicts from the package.json.

Furthermore, I’ve demonstrated how such conflicts can be resolved, either by defining them as direct dependencies or by overriding them in the overrides section of the package.json. If the root cause of the peer dependency conflict isn't immediately apparent, one might seek assistance from ChatGPT to resolve the issue promptly.

I encourage you to address your peer dependency conflicts. Doing so will save considerable time, and your developers will greatly appreciate it.

Links

[1] https://medium.com/bitsrc/stop-using-npm-install-in-your-ci-cd-pipeline-ba0378bbebfb

Stackademic 🎓

Thank you for reading until the end. Before you go:

Please consider clapping and following the writer! 👏
Follow us X | LinkedIn | YouTube | Discord
Visit our other platforms: In Plain English | CoFeed | Venture | Cubed
Tired of blogging platforms that force you to deal with algorithmic content? Try Differ
More content at Stackademic.com

Resolving NPM Peer Dependency Conflicts

Resolving conflicting peer-dependencies

Summing Up

Links

Stackademic 🎓

Written by Robert Maier-Silldorff