Como evitar problemas com a versão do Node e do NPM no seu projeto

Nesse artigo veremos como garantir que as dependências sejam instaladas apenas se o ambiente tiver com a versões do node e do NPM especificadas. Abaixo, conto uma breve história para explicar de onde surgiu esse artigo.

Como trabalho em um ambiente com algumas equipes, um dia desses, ocorreu que iniciei um projeto usando node, na minha máquina estava usando a versão v16.20 do node com NPM na versão 8.19, até ai nada demais, outros membros da equipe puxaram o projeto para sua máquina, na hora de rodar um `npm i` já começou o B.O, alguma das dependências precisam fazer build e requiriam algumas instalações adicionais na máquina de alguns, beleza, as mensagens de erro não eram tão claras quanto a algumas dependência porém deu para se resolver rápido, aí finalmente na hora de rodar, nada de aplicação subir em algumas máquinas sendo que em outras, tava tudo rodando normalmente, aí se olha log daqui, olha log dali, vai pra stack e nada de conseguir resolver, até que em algum momento fomos verificar a versão instalada em umas das máquinas, bem, era a versão 14, certo, como fiz o projeto na 16, será que é isso? Certo, vamos tentar, instalamos o NVM e puxamos a versão 16 do node e voilá, como que por mágica a aplicação rodou normalmente, fizemos o mesmo nas demais máquina e em todas funcionou normalmente, com isso conseguimos resolver o problema porém infelizmente não chegamos a causa em si, possivelmente tinha alguma dependência específica de algo que tinha na versão 16 porém os logs não nos ajudaram muito, com isso, fui atrás de uma forma de garantir que o projeto só podesse ser configurado apenas a partir daquela versão do node em diante.

Para conseguir resolver isso, será necessário informar ao NPM que ele só deve instalar os pacotes casos os requisitos de engine sejam atendidos, conforme pode ser conferido a seguir

"engines": {
    "npm": "version_number>= or <=version_number",
    "node": "version_number>= or <=version_number"
  }

"engines": {
    "npm": ">=10.1",
    "node": ">=20.9"
  }

No exemplo acima, estou informando ao NPM que ele deve emitir um aviso caso a versão do próprio NPM seja inferior ao 10.1 e caso o NODE seja inferior ao 20.9, você não é obrigado a colocar ambos como requisito, pode ser apenas um ou outro. Neste exemplo, um aviso será emitido apenas se o seu projeto for instalado como uma dependência em outro projeto, caso queira emitir um aviso quando for instalar dependências no projeto, será necessário definir o modo estrito como true como abaixo.

engineStrict: true,
"engines": {
  "npm": ">=10.1",
  "node": ">=20.9"
}

Com isso, o NPM irá emitir um aviso como da imagem abaixo.

Porém observe que até aqui emitiu apenas um aviso, bem detalhado por sinal porém não bloqueou a instalação das dependências, isso pode ser ruim, porque com as milhões de dependências que um projeto node pode ter “rsrs” e com isso as diversas saídas no log, pode ser que quem rodar um `npm i` da vida, não observe o aviso na saída do log, logo, pode ser mais interessante bloquear a instalação das dependências e forçar o usuário a deixar o ambiente com o mínimo necessário antes de prosseguir, para isso, será necessário criar um arquivo .npmrc no diretório raiz do projeto e incluir nele a configuração conforme abaixo.

engine-strict=true

Com isso, ao fazer novamente um `npm i`, observe agora que a instalação foi bloqueada.

Isso me ajudou a evitar algumas dores de cabeça e perca de tempo em projetos que fiz depois desse, espero que o mesmo se aplique pra você e até a próxima.