O comando npm install --legacy-peer-deps é usado para contornar a funcionalidade de instalação automática de peerDependency ao instalar pacotes. Ele diz ao NPM para ignorar as dependências de pares e instalar apenas o pacote.
No NPM v7+, por padrão, npm install falhará quando encontrar peerDependencies conflitantes. Isso não era assim antes. Se você já tem um peerDependency instalado, mas não com uma versão nomeada pelo módulo, então o NPM v7+ lançará um erro. Adicionar --legacy-peer-deps ignora esse novo requisito, com o risco de introduzir mudanças que quebram a funcionalidade.
Portanto, se o seu projeto estava quebrando com npm install, é provável que houvesse algum conflito de dependência que estava sendo ignorado com o uso de --legacy-peer-deps. Isso pode acontecer quando diferentes pacotes no seu projeto dependem de diferentes versões da mesma biblioteca. Com --legacy-peer-deps, o NPM ignora esses conflitos e prossegue com a instalação.
E uma vez usado o --legacy-peer-deeps, como tratar as peerdependecies manualmanente no package.json e nao precisar usar ele projeto?
Falo isso por quê na empresa subimos docker com legacy-peer-deps e vez ou outra temos que mudar versao na mao,corre o risco de quebrar algua feature no sistema..