«npm WARN requires a peer»: как исправить и понять суть ошибки

Введение: почему npm кричит на вас?

Вы когда-нибудь запускали npm install и видели что-то вроде этого?

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

Знакомо? Если да — вы не одиноки. Этот вопрос на Stack Overflow собрал тысячи просмотров и десятки комментариев от разработчиков, которые, как и вы, хотели просто установить пакет, а получили головную боль. Сегодня мы разберёмся, что такое peer dependencies, почему npm так настойчиво требует их установить и как правильно с ними работать в проектах на TypeScript. И да, это будет не скучная документация, а живой разбор с примерами кода.

Поехали!

Что такое peer dependencies и зачем они нужны?

Представьте, что вы собираете пазл. У вас есть основная картинка (ваш проект) и несколько кусочков (пакеты). Некоторые кусочки идеально подходят друг к другу, но только если вы используете правильную рамку. В мире npm эта «рамка» — peer dependency.

Peer dependency (или «равноправная зависимость») — это требование пакета к тому, что определённая библиотека должна быть установлена в проекте, но сам пакет не будет её устанавливать. Почему? Потому что эта библиотека уже должна быть у вас, и пакет просто «дружит» с ней, не создавая дубликатов.

Например, пакет ts-patch (популярный инструмент для TypeScript) требует, чтобы в проекте был установлен typescript. Но ts-patch не устанавливает TypeScript сам — он предполагает, что вы уже его добавили. Если TypeScript нет, npm выдаёт то самое предупреждение.

Почему это важно для TypeScript-проектов?

TypeScript — это не просто язык, это экосистема. Многие пакеты (например, @types/react, ts-loader, eslint-plugin-typescript) работают поверх TypeScript. Если у вас установлена версия TypeScript 5.0, а пакет требует 4.0+, всё хорошо. Но если TypeScript вообще нет — начинаются проблемы.

Вот реальный пример из жизни. Допустим, вы пишете небольшой скрипт на TypeScript и используете ts-patch для трансформации кода. Вы запускаете:

npm install ts-patch --save-dev

И получаете:

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

Что делать? Паниковать? Нет. Просто установите TypeScript:

npm install typescript --save-dev

Проблема решена. Но что если у вас уже есть TypeScript, но другой версии? Тут начинается самое интересное.

Сравнение подходов: как устанавливать peer dependencies

Существует несколько способов справиться с этой ошибкой. Давайте сравним их на примере TypeScript-проекта.

Подход 1: Ручная установка (классика)

Самый простой и надёжный способ — прочитать предупреждение и вручную установить нужный пакет. Вы видите, что требуется typescript@>=4.0, и добавляете его:

npm install typescript@^4.0 --save-dev

Плюсы:

• Полный контроль над версией.
• Нет скрытых сюрпризов.

Минусы:

• Нужно внимательно читать сообщения npm.
• Если пакетов много, процесс становится рутинным.

Этот подход идеален для небольших проектов, где вы точно знаете, какие зависимости вам нужны.

Подход 2: Автоматическая установка с помощью npx или плагинов

Некоторые инструменты, например npm-check или install-peerdeps, могут автоматически установить все peer dependencies для конкретного пакета. Установите утилиту глобально:

npm install -g install-peerdeps

А затем запустите для нужного пакета:

install-peerdeps ts-patch

Утилита сама найдёт все peer dependencies и установит их в правильных версиях.

Плюсы:

• Экономит время.
• Подходит для сложных проектов с кучей зависимостей.

Минусы:

• Дополнительный инструмент, который нужно устанавливать.
• Может установить версию, которая не совпадает с вашими требованиями (например, если вы используете TypeScript 5.0, а он предложит 4.0).

Подход 3: Использование npm@7+ (автоматическая установка)

Начиная с npm версии 7, peer dependencies устанавливаются автоматически. Если вы обновите npm до актуальной версии, вы можете вообще забыть об этой ошибке. Проверьте свою версию:

npm --version

Если версия 7 или выше, просто удалите node_modules и package-lock.json, а затем выполните чистую установку:

rm -rf node_modules package-lock.json
npm install

npm сам подтянет все необходимые peer dependencies.

Плюсы:

• Не нужно ничего делать вручную.
• Работает «из коробки».

Минусы:

• Может привести к конфликтам версий, если у вас уже установлены несовместимые пакеты.
• Не все проекты готовы к обновлению npm (например, если используется старый CI/CD).

Пример из реального проекта на TypeScript

Допустим, вы разрабатываете библиотеку для работы с API на TypeScript. Вы решили использовать ts-patch для генерации типов из схем. Вот как выглядит ваш package.json до установки:

{
  "name": "my-api-lib",
  "version": "1.0.0",
  "devDependencies": {
    "ts-patch": "^3.2.0"
  }
}

Запускаем npm install и видим:

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

Теперь применяем подход 1 — ручную установку. Добавляем TypeScript:

npm install typescript@^4.0 --save-dev

После этого package.json выглядит так:

{
  "name": "my-api-lib",
  "version": "1.0.0",
  "devDependencies": {
    "ts-patch": "^3.2.0",
    "