1. Por que acontece
A partir do npm 7, peer dependencies são tratadas com mais rigor. Um plugin pode exigir React 18 enquanto o app está em 19.
npm install
# ERRESOLVE unable to resolve dependency tree
npm ls react
npm explain react
2. Estratégias (da melhor à paliativa)
- Atualizar o pacote que declara o peer antigo
- Alinhar a versão do peer no app (quando seguro)
- Usar
overridesnopackage.jsoncom consciência npm i --legacy-peer-depssó como paliativo local/CI temporário
// package.json
"overrides": {
"algum-plugin": { "react": "$react" }
}
BOA PRÁTICA Trate peer conflict como sinal de stack desalinhada — não como “bug chato do npm”.
3. Ler a mensagem de erro
O ERESOLVE mostra qual pacote exige qual versão. Procure as linhas "Found" (o que está instalado) e "Could not resolve dependency" (o que o outro pacote pede). Depois use npm explain nome-do-pacote para ver quem depende dele e por qual caminho.
4. Diferença entre as opções de contorno
--legacy-peer-depsignora a checagem de peer dependencies na instalação, como no comportamento anterior ao npm 7. O conflito continua existindo e pode aparecer só em execução.--forceaceita a árvore conflitante e instala mesmo assim, o que pode deixar versões incompatíveis no projeto.overridesfixa uma versão específica de forma declarada nopackage.jsone fica versionada, o que torna a escolha explícita para o time.
5. Depois de resolver
Rode npm ls para conferir a árvore, execute os testes e o build, e faça o commit do package-lock.json junto com o package.json. Se o projeto usa outro gerenciador, o problema aparece de forma parecida; veja npm, pnpm e Yarn, e o roadmap de Node.js.