Photo by Mark Galer on Unsplash

In this post I wanted to walk through a recent experience I had trying to resolve an NPM dependency conflict. Really, I want to show you how to read the output that NPM gives you when it finds a dependency conflict, because it wasn’t that intuitive to me at first. Hopefully this will help you if you ever have to resolve dependency conflicts — and you probably will.

Updating typescript

Trying to update typescript to the latest version, I received this output from NPM:

Looking at this, it may not be obvious what the actual conflict is. But once you understand what’s going on here, it’s not hard to understand. Let’s break it down:

• Line 1 just indicates the name of your application (from package.json)
• Line 2 shows the version of typescript NPM found to install (5.1.3), based on the entry in package.json
• Line 4 lists the entry in dev dependencies that caused NPM to find 5.1.3 (typescript@^5.1.0). Note the “dev” in front, which indicates this is a dev dependency.

This next block reveals what the problem is:

• Line 2 tells us that typescript@≥=4.9.3 < 5.1 is a peer dependency of @angular/[email protected], which is the wanted version of @angular/compiler-cli, based on package.json. A peer dependency is a dependency that one of your dependencies relies on. Since the peer dependency specifies a typescript version less than 5.1, the found typescript version 5.1.3 won’t work.

The rest of the output describes the dependency tree that got us here — this is required by that and that is required by this, etc. It isn’t really important in this case, now that we know what the problem is. But let’s go over it anyway:

• Line 1 shows us that the dev dependency entry @angular/compiler-cli@^16.0.3 is what is causing @angular/[email protected] to be wanted (recall that @angular/compiler-cli has the peer dependency that is causing the problem)
• Line 2 informs us that @angular/compiler-cli@^16.0.0 is also a peer dependency of the wanted @angular-devkit/[email protected] (so even if we could remove @angular/compiler-cli as a dev dependency, it’s still required as a peer dependency by @angular-devkit/build-angular)
• Line 4 is saying the dev dependency entry @angular-devkit/build-angular@^16.0.3 is what is causing @angular-devkit/[email protected] to be wanted

Again, that last block didn’t help us this time. We know we want @angular/[email protected] and we now know that it’s not compatible with [email protected] (according to its spec).

You can always force the issue, or use legacy-peer-deps, but you generally don’t want to do that unless you’re confident that NPM is just wrong — which happens. But in this case NPM seems to be correct — whether or not [email protected] would actually break anything is a separate issue. I didn’t have my heart set on typescript 5.1+, so I complied and changed my typescript package.json entry to ~5.0.0 to resolve the conflict.

So this was just a quick look at how to read the output of an NPM dependency conflict error.