Como corrigir o erro npm! ERESOLVE Não é possível resolver a árvore de dependências

Onpm ERRO! ERESOLVE não foi possível resolver a árvore de dependências erro significa que o npm encontrou requisitos de dependência de pares conflitantes entre pacotes em seu projeto. O npm 7+ tornou a resolução de dependências de pares mais rigorosa — pacotes que foram instalados silenciosamente lado a lado no npm 6 agora falham. Aqui estão todas as correções explicadas.

Compreendendo o erro

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.3.1
npm ERR! node_modules/react
npm ERR!   react@"^18.0.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-old-package@2.1.0
npm ERR! node_modules/some-old-package

Lendo este erro: Seu projeto usa React 18.some-old-package requer React 16 ou 17 como dependência de peer. O npm se recusa a instalar porque vê isso como um conflito.

Correção 1: –legacy-peer-deps (correção rápida mais segura)

npm install --legacy-peer-deps

Isso reverte o comportamento do npm para v6 – instala pacotes sem impor conflitos de dependência de pares. O pacote pode funcionar bem com a versão mais recente, mesmo que declare um intervalo mais antigo.

Quando usar: Depois de testar se a combinação funciona, o pacote não foi atualizado para declarar novas versões de pares React/Vue/Angular e você confia que a dependência não será realmente quebrada.

Persista em todas as instalações futuras:

# .npmrc file (commit this to repo)
legacy-peer-deps=true

Correção 2: –force (último recurso)

npm install --force

O que faz: Força a instalação mesmo com versões conflitantes, potencialmente instalando múltiplas versões do mesmo pacote. Mais agressivo que--legacy-peer-deps.

Quando usar: Somente quando--legacy-peer-deps não funciona e você verificou que a combinação é segura. --force pode criar bugs sutis de tempo de execução a partir de versões incompatíveis.

Correção 3: atualize o pacote conflitante

# Check if a newer version supports your React/Node version
npm info some-old-package peerDependencies

# Try installing a specific version
npm install some-old-package@latest

# Or check if there's an RC/beta with support
npm install some-old-package@next

Esta é a solução certa quando o pacote foi atualizado. Sempre verifique se há uma versão mais recente antes de acessar legado-peer-deps.

Correção 4: substitui o campo (npm 8.3+, abordagem mais correta)

// package.json
{
  "dependencies": {
    "some-old-package": "2.1.0",
    "react": "^18.0.0"
  },
  "overrides": {
    "some-old-package": {
      "react": "^18.0.0"
    }
  }
}

Ooverrides campo diz ao npm para forçar uma versão específica de uma dependência aninhada. Esta é a solução mais correta – você está dizendo explicitamente “use o React 18 para este pacote também” em vez de ignorar silenciosamente o conflito.

Para Yarn (campo de resoluções):

// package.json
{
  "resolutions": {
    "some-old-package/react": "^18.0.0"
  }
}

Correção 5: Encontre um pacote alternativo

Se um pacote não foi mantido e não suporta versões peer atuais, muitas vezes é um sinal para encontrar uma alternativa com melhor manutenção:

# Check last publish date
npm info some-old-package

# Check GitHub for issues/PRs about the newer React version
# Look for: forks, alternatives, or community maintained versions

Um pacote publicado pela última vez há mais de 2 anos com questões em aberto sobre a compatibilidade do React 18 provavelmente foi abandonado. Pesquise no npm alternativas modernas com manutenção ativa.

Árvore de Decisão

ERESOLVE error
    ↓
Is there a newer version of the conflicting package?
    YES → npm install package@latest
    NO ↓
Does the package actually work with your version (test it)?
    YES → Use --legacy-peer-deps or overrides in package.json
    NO ↓
Is there an actively maintained alternative?
    YES → Switch packages
    NO → Use --legacy-peer-deps and monitor for issues

Cenários comuns e correções

# Scenario: Create React App with React 18
npx create-react-app my-app  # old CRA doesn't support React 18
# Fix: Use Vite instead
npm create vite@latest my-app -- --template react-ts

# Scenario: Storybook + React 18
npx sb init  # older Storybook versions conflict
# Fix: Use current Storybook
npx storybook@latest init

# Scenario: Old Redux package conflicts
# Fix: upgrade to Redux Toolkit (official recommendation)
npm install @reduxjs/toolkit react-redux

# Scenario: Next.js conflicting peer deps
# Fix: usually just --legacy-peer-deps works; Next.js team is aware

Perguntas Frequentes

P: –legacy-peer-deps é seguro?
R: Geralmente sim, especialmente quando o conflito é sobre intervalos de versões de peer serem conservadores (por exemplo, peer diz React 16-17, mas funciona bem com 18). Sempre teste depois de usá-lo. O risco são incompatibilidades sutis de tempo de execução que só aparecem em casos extremos.

P: Por que o npm mudou o comportamento de dependência de pares?
R: O npm 7+ tornou a resolução de dependências de peer estrita para evitar conflitos de versão silenciosos que causavam erros de tempo de execução difíceis de depurar. É um comportamento mais correto – a compensação é a necessidade de uma resolução mais explícita.

P: Devo usar substituições npm ou –legacy-peer-deps?
A: overrides em package.json é mais explícito e documenta a decisão. --legacy-peer-deps é mais rápido, mas implícito. Para projetos de produção, prefiraoverrides portanto, a substituição fica visível na revisão do código.

P: Este erro apareceu após a atualização do Node.js – isso está relacionado?
R: As atualizações do Node.js geralmente trazem versões mais recentes do npm com resolução de dependência de pares mais rigorosa. Fazer downgrade do Node não é a solução — useoverrides or --legacy-peer-deps e atualize suas dependências para versões compatíveis com o Node/npm mais recente.

P: Como posso evitar isso em novos projetos?
R: Comece com ferramentas modernas (Vite, Next.js 14+, alternativas mais recentes de CRA) que possuem declarações de pares atualizadas. Evite pacotes com históricos de manutenção insatisfatórios. Usarnpm outdated trimestralmente para se manter atualizado.

Conclusão

Erros npm ERESOLVE geralmente são resolvidos por:(1) atualizar o pacote conflitante para uma versão que suporte a versão da sua estrutura, (2) usaroverrides em package.json para uma correção documentada ou (3)--legacy-peer-deps como uma solução temporária rápida. Evite--force a menos que nada mais funcione – pode criar conflitos de versão em tempo de execução. A melhor solução a longo prazo é manter as dependências atualizadas para que os conflitos de versão não se acumulem.