npm install ou npm ci: qual usar, e onde

São dois comandos parecidos com um propósito diferente, e trocá-los é a causa daquele clássico: "na minha máquina funciona".

1. O que cada um faz ao lockfile

• npm install lê o package.json, resolve o que couber nos intervalos de versões, instala — e reescreve o package-lock.json se encontrar algo mais recente que caiba.

• npm ci ignora essa liberdade: instala exatamente o que está no lockfile. Se o lockfile não corresponder ao package.json, falha em vez de improvisar.

É essa última frase que faz toda a diferença. Um npm install num servidor de integração pode instalar hoje uma versão que ontem não existia — e é assim que uma alteração numa dependência de uma dependência chega a produção sem ninguém ter escrito uma linha.

2. A regra prática

# Ao desenvolver, quando quero mesmo mexer nas dependências
npm install alguma-biblioteca

# Em qualquer sítio automático: CI, imagem Docker, servidor
npm ci

O npm ci apaga o node_modules antes de instalar, o que também elimina a categoria de erros que começa com "mas eu tinha isso instalado".

3. O lockfile comita-se

Sempre. É ele que faz com que a sua máquina, a do colega e o servidor instalem a mesma árvore de dependências, até à última. Um projeto sem lockfile versionado não tem instalações reprodutíveis — tem instalações parecidas.

4. Coisas que valem a pena saber

• npm ci --omit=dev salta as dependências de desenvolvimento — é o que se quer na imagem de produção.

• npm ci exige o lockfile. Num projeto que não o tenha, começa por um npm install e comita o resultado.

• npm outdated mostra o que está para trás sem mexer em nada; npm update sobe dentro dos intervalos permitidos.

• npm audit não instala nada. Diz o que se sabe sobre o que já lá está.