"ERESOLVE unable to resolve dependency tree" do npm e conflitos de peer dependencies

O que é

npm error code ERESOLVE (npm 10.6 e posteriores; npm ERR! code ERESOLVE no npm 7 a 10.5) vem do resolvedor de dependências do próprio npm. A documentação do npm sobre o formato do package.json descreve peerDependencies e o campo overrides, usado para ajustá-las. Desde o npm 7, as peer dependencies são instaladas automaticamente, em vez de gerarem apenas um aviso. Isso significa que o npm agora precisa encontrar uma única versão de cada pacote que satisfaça ao mesmo tempo todos os intervalos de peer da árvore. ERESOLVE indica que isso não foi possível: o seu projeto ou uma de suas dependências diretas declara um intervalo de peerDependencies para um pacote, e outra dependência da árvore precisa de uma versão fora desse intervalo. Conflitos em níveis profundos da árvore são, por padrão, resolvidos apenas com um aviso ERESOLVE overriding peer dependency; a opção --strict-peer-deps faz com que esses casos também resultem em falha.

Por que importa

O erro não é, por si só, o relato de um pacote quebrado. É o npm apontando um conflito real de restrições, que já existia antes do npm 7, só que de forma silenciosa. Contornar o problema sem entender quais dois requisitos realmente colidem corre o risco de instalar uma árvore que não atende ao que um dos pacotes espera em tempo de execução, mesmo que a instalação em si termine com sucesso.

Como aplicar

• Diagnóstico: leia o bloco de erro completo, não apenas a primeira linha. O npm imprime Found: x@version (o que está resolvido no momento), seguido de uma ou mais linhas Could not resolve dependency: peer x@"range" from y@version, que indicam exatamente qual pacote exige qual intervalo e a partir de onde. Depois disso, npm ls <package> --all mostra todos os pontos da árvore que dependem dele.
• Correções, da menos para a mais invasiva:
  1. Atualize o(s) pacote(s) em conflito para versões cujos intervalos de peer realmente se sobreponham. Muitas vezes é a solução de fato, pois o conflito costuma refletir uma dependência que está realmente defasada em relação às outras.
  2. Se o intervalo de peer de um pacote for simplesmente mais restritivo do que a realidade (ele declara um intervalo estreito, mas sabe-se que funciona com a versão major mais nova em uso), fixe apenas essa resolução aninhada com o campo overrides do package.json (npm 8.3+), documentado junto de peerDependencies, em vez de relaxar a verificação para a árvore inteira.
  3. Saída de emergência insegura: npm install --legacy-peer-deps, documentada como opção do npm install, restaura o comportamento do npm 6 de não instalar automaticamente nem verificar rigorosamente os peers. Funciona, mas impede que o npm verifique as expectativas de peer em qualquer ponto da árvore, e não apenas no conflito em questão.
  4. npm install --force vai além e instala mesmo havendo outros conflitos detectados pelo npm. Use-o como último recurso pontual, e não como padrão versionado no CI, pois a árvore resultante pode não satisfazer o que um pacote espera ao ser executado.
• Não resolve: apagar node_modules e package-lock.json e reinstalar. Quando os intervalos declarados conflitam, o npm falha do mesmo jeito, e as versões fixadas no lockfile se perdem.

Armadilhas

• Recorrer ao --force antes de ler quais dois pacotes realmente entram em conflito, o que obriga a fazer o diagnóstico de qualquer forma quando algo quebra em tempo de execução.
• Fazer commit de --legacy-peer-deps como flag permanente no CI, o que deixa novos conflitos de peer, sem relação com o original, se acumularem silenciosamente a partir daí.