"npm WARN requires a peer": how to fix and understand the essence of the error

Introduction: why is npm yelling at you?

Have you ever run npm install and seen something like this?

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed. You must install peer dependencies yourself.

Familiar? If yes — you are not alone. This question on Stack Overflow has gathered thousands of views and dozens of comments from developers who, like you, just wanted to install a package and got a headache instead. Today we will figure out what peer dependencies are, why npm insists so strongly on installing them, and how to work with them correctly in TypeScript projects. And yes, this will not be boring documentation, but a lively breakdown with code examples.

Let's go!

What are peer dependencies and why are they needed?

Imagine you are putting together a puzzle. You have the main picture (your project) and several pieces (packages). Some pieces fit together perfectly, but only if you use the right frame. In the npm world, this "frame" is a peer dependency.

A peer dependency is a package's requirement that a specific library must be installed in the project, but the package itself will not install it. Why? Because that library should already be present in your project, and the package simply "works with" it without creating duplicates.

For example, the ts-patch package (a popular tool for TypeScript) requires that typescript is installed in the project. But ts-patch does not install TypeScript itself — it assumes you have already added it. If TypeScript is missing, npm outputs that very warning.

Why is this important for TypeScript projects?

TypeScript is not just a language, it's an ecosystem. Many packages (e.g., @types/react, ts-loader, eslint-plugin-typescript) work on top of TypeScript. If you have TypeScript version 5.0 installed, and the package requires 4.0+, everything is fine. But if TypeScript is not installed at all — problems begin.

Here is a real-life example. Let's say you are writing a small script in TypeScript and using ts-patch for code transformation. You run:

npm install ts-patch --save-dev

And you get:

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed.\nYou must install peer dependencies yourself.

What to do? Panic? No. Just install TypeScript:

npm install typescript --save-dev

Problem solved. But what if you already have TypeScript, but a different version? That's where the fun begins.

Comparison of approaches: how to install peer dependencies

There are several ways to deal with this error. Let's compare them using a TypeScript project as an example.

Approach 1: Manual installation (classic)

The simplest and most reliable way is to read the warning and manually install the required package. You see that typescript@>=4.0 is required, and you add it:

npm install typescript@^4.0 --save-dev

Pros:

\n
• Full control over the version.
\n
• No hidden surprises.
\n

Cons:

\n
• You need to carefully read npm messages.
\n
• If there are many packages, the process becomes tedious.
\n

This approach is ideal for small projects where you know exactly which dependencies you need.

Approach 2: Automatic installation using npx or plugins

Some tools, such as npm-check or install-peerdeps, can automatically install all peer dependencies for a specific package. Install the utility globally:

npm install -g install-peerdeps