Use npm install ao adicionar uma dependência ou atualizar o conjunto resolvido do projeto. Depois, revise package.json e package-lock.json juntos. Em um checkout limpo que precisa instalar o conjunto já aprovado, npm ci usa o lockfile existente e falha se ele estiver incompatível com package.json.

Reproduza a instalação do CI

Execute npm ci no mesmo diretório que contém o lockfile usado pelo pipeline. Se o arquivo foi gerado com uma configuração que altera a resolução, como legacy-peer-deps, o CI precisa usar configuração compatível. Uma configuração de projeto sem credenciais pode ser versionada em .npmrc.

npm ci remove node_modules se o diretório já existe. Isso ajuda a detectar código que só funcionava por causa de dependências sobrando no ambiente local. Ainda vale alinhar a versão do Node e do npm entre desenvolvimento e CI. O lockfile fixa a árvore resolvida, mas a plataforma e os scripts de instalação podem afetar o resultado.

Se npm ci falha logo após editar package.json, regenere e revise o lockfile localmente. A correção precisa aparecer no diff do commit.

Documentação de referência · Como encontrar um commit que quebrou o código com git bisect

Confira o que mudou depois da instalação

Depois de npm install, verifique se a nova dependência aparece em package.json no grupo correto e se package-lock.json registra a árvore resolvida. Em um monorepo com workspaces, confirme o diretório a partir do qual o comando deve rodar. Executar o npm na pasta errada pode atualizar outro lockfile ou gerar uma instalação diferente do pipeline.

npm ci recria node_modules e usa as versões registradas no lockfile, mas a instalação também pode executar scripts de pacotes nativos. Sistema operacional, arquitetura e versão do Node influenciam esses scripts. Se o CI e a máquina local diferem, compare os ambientes antes de atribuir toda divergência ao lockfile. A versão do npm também pode alterar detalhes de resolução e formato.

Trate dependências de forma revisável

Evite editar o lockfile manualmente. Resolva os conflitos usando a ferramenta e valide que o resultado ainda contém as dependências esperadas. Se uma flag como legacy-peer-deps foi necessária para gerar o arquivo, torne a configuração reproduzível no projeto e registre o motivo. Não use uma opção para ignorar erros de peer dependencies sem entender qual pacote impõe o conflito.

Na revisão, observe o tamanho do diff, novos pacotes transitivos e URLs de registry. Rode uma instalação limpa e o comando de build que o projeto usa. Um lockfile consistente prova que a árvore pode ser reproduzida dentro das condições declaradas; não prova que a atualização é segura ou que o pacote novo tem comportamento desejado.

Em CI, cache de npm costuma guardar o download de pacotes, não substituir a instalação limpa. A etapa de instalação deve continuar usando npm ci para detectar um lockfile incompatível. Ao trocar versões do Node ou npm, revise o lockfile gerado e rode os scripts de verificação. Se dois desenvolvedores usam npm diferente, alinhe as versões ou declare a versão esperada no projeto para reduzir alterações de formatação e resolução inesperadas.