Squad Front

Appearance

Package-lock.json ​

O arquivo package-lock.json é um dos arquivos mais importantes para a estabilidade do projeto e deve ser obrigatoriamente enviado ao Git.

1. O que é o package-lock.json? ​

Enquanto o package.json define quais dependências (e versões aproximadas) seu projeto precisa, o package-lock.json descreve a árvore exata de dependências que foi instalada.

Ele trava (lock) as versões de todas as sub-dependências, garantindo que cada desenvolvedor e o servidor de CI/CD instalem exatamente os mesmos bytes.

2. Por que ele é importante? ​

  • Determinismo: Garante que o projeto funcione da mesma forma na sua máquina, na máquina do colega e no ambiente de produção.
  • Segurança: Registra o hash (integridade) de cada pacote, evitando que um código malicioso seja injetado se um servidor de pacotes for invadido.
  • Performance: Otimiza o processo de instalação (npm install), pois o npm não precisa "resolver" as versões novamente.

3. Por que DEVEMOS comitar? ​

Se você não comitar o package-lock.json:

  1. Cada npm install pode instalar versões ligeiramente diferentes de sub-dependências.
  2. Isso gera o famoso erro: "Na minha máquina funciona, mas em produção quebrou".
  3. O time de QA pode testar uma versão da aplicação que é diferente da que será publicada.

4. Como gerenciar ​

✅ Como fazer ​

  • Sempre comite: Inclua o package-lock.json em todos os seus Pull Requests que envolvam mudança de dependências.
  • Use npm ci: Em ambientes de integração contínua (CI), usamos npm ci em vez de npm install. Esse comando é mais rápido e garante que o ambiente seja fiel ao lockfile.
  • Resolva conflitos com cuidado: Se houver conflito no lockfile durante um merge, geralmente a melhor forma de resolver é aceitar uma das versões e rodar npm install novamente para regenerar o arquivo corretamente.

❌ Como não fazer ​

  • Deletar o lockfile: Nunca delete o package-lock.json para "resolver" um erro de instalação. Isso mascara o problema e gera instabilidade para o resto do time.
  • Ignorar no .gitignore: Nunca adicione o package-lock.json ao seu .gitignore.
  • Alterar manualmente: Nunca edite o conteúdo deste arquivo à mão. Ele é gerado automaticamente pelo npm.

5. Resumo ​

O package.json é a sua intenção (o que você quer), o package-lock.json é a realidade (o que foi instalado). * Mantenha a realidade sob controle comitando o lockfile.*