«npm WARN requires a peer»: como corrigir e entender a essência do erro

Introdução: por que o npm está gritando com você?

Você já executou npm install e viu algo assim?

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? Se sim — você não está sozinho. Esta pergunta no Stack Overflow acumulou milhares de visualizações e dezenas de comentários de desenvolvedores que, como você, queriam apenas instalar um pacote e acabaram com uma dor de cabeça. Hoje vamos entender o que são peer dependencies, por que o npm insiste tanto para instalá-las e como trabalhar corretamente com elas em projetos TypeScript. E sim, isso não será uma documentação chata, mas uma análise prática com exemplos de código.

Vamos lá!

O que são peer dependencies e para que servem?

Imagine que você está montando um quebra-cabeça. Você tem a imagem principal (seu projeto) e várias peças (pacotes). Algumas peças se encaixam perfeitamente, mas apenas se você usar a moldura correta. No mundo do npm, essa "moldura" é a peer dependency.

Peer dependency (ou "dependência de pares") é uma exigência de um pacote de que uma determinada biblioteca esteja instalada no projeto, mas o próprio pacote não a instalará. Por quê? Porque essa biblioteca já deve estar presente, e o pacote apenas "se dá bem" com ela, sem criar duplicatas.

Por exemplo, o pacote ts-patch (uma ferramenta popular para TypeScript) exige que o typescript esteja instalado no projeto. Mas o ts-patch não instala o TypeScript por conta própria — ele presume que você já o adicionou. Se o TypeScript não estiver presente, o npm emite o aviso mencionado.

Por que isso é importante para projetos TypeScript?

TypeScript não é apenas uma linguagem, é um ecossistema. Muitos pacotes (por exemplo, @types/react, ts-loader, eslint-plugin-typescript) funcionam sobre o TypeScript. Se você tem a versão 5.0 do TypeScript instalada e o pacote requer 4.0+, está tudo bem. Mas se o TypeScript não estiver instalado, começam os problemas.

Aqui está um exemplo real da prática. Suponha que você está escrevendo um pequeno script em TypeScript e usando ts-patch para transformação de código. Você executa:

npm install ts-patch --save-dev

E obtém:

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

O que fazer? Entrar em pânico? Não. Basta instalar o TypeScript:

npm install typescript --save-dev

Problema resolvido. Mas e se você já tiver o TypeScript, mas de outra versão? Aí começa a parte interessante.

Comparação de abordagens: como instalar peer dependencies

Existem várias maneiras de lidar com esse erro. Vamos compará-las usando um projeto TypeScript como exemplo.

Abordagem 1: Instalação manual (clássica)

A maneira mais simples e confiável é ler o aviso e instalar manualmente o pacote necessário. Você vê que é necessário typescript@>=4.0 e o adiciona:

npm install typescript@^4.0 --save-dev

Vantagens:

\n
• Controle total sobre a versão.
\n
• Sem surpresas ocultas.
\n

Desvantagens:

\n
• É necessário ler atentamente as mensagens do npm.
\n
• Se houver muitos pacotes, o processo se torna repetitivo.
\n

Esta abordagem é ideal para projetos pequenos, onde você sabe exatamente quais dependências precisa.

Abordagem 2: Instalação automática com npx ou plugins

Algumas ferramentas, como npm-check ou install-peerdeps, podem instalar automaticamente todas as peer dependencies para um pacote específico. Instale o utilitário globalmente:

npm install -g install-peerdeps