Skip to main content

Package.json and Package-lock.json

  • Package.json and Package-lock.json

📦 package.json e package-lock.json​

Você provavelmente já se deparou com o arquivo package-lock.json se trabalha com projetos que utilizam Node.js. Neste artigo, veremos o que é o package-lock.json, por que ele é necessário e como ele difere do package.json.

🧾 O que é o arquivo package.json?​

O package.json é um arquivo JSON localizado no diretório raiz de um projeto Node.js. Ele contém metadados sobre o projeto (nome, versão, autor, scripts, etc.) e lista todas as dependências instaladas com o NPM.

Sempre que instalamos um pacote usando npm install, o package.json é atualizado com o nome do pacote e sua versão, seguindo a convenção semver.

🔢 O que é SemVer?​

O SemVer (Semantic Versioning) é o padrão usado pelo NPM para definir versões de pacotes. Cada versão segue o formato:

x.y.z

Onde:

  • x — versão major (grande): mudanças incompatíveis.
  • y — versão minor (menor): novas funcionalidades compatíveis.
  • z — versão patch: correções de bugs.

Exemplo:​

  • Incrementar major: mudanças grandes ou que quebram compatibilidade.
  • Incrementar minor: novas funcionalidades compatíveis.
  • Incrementar patch: apenas correções.

🔣 Símbolos de versão no NPM​

O NPM utiliza símbolos especiais antes das versões no package.json para definir regras de atualização quando executamos npm update ou npm install.

Os dois mais comuns são:

  • ^ (caret)
  • ~ (til)

🟩 ^ (caret)​

Regra: permite atualizações de minor e patch, mas não de major.

Exemplo:

"abc": "^13.1.0"

Com isso, o NPM pode atualizar para:

13.2.0, 13.3.0, 13.3.1, ...

Mas não para:

14.0.0

🟦 ~ (til)​

Regra: permite apenas atualizações de patch.

Exemplo:

"abc": "~13.1.0"

Com isso, o NPM pode atualizar para:

13.1.1, 13.1.2, ...

Mas não para:

13.2.0 ou 14.0.0

💡 Por padrão, o NPM usa o símbolo ^ ao instalar pacotes.

⚠️ O problema sem o package-lock.json​

Considere o seguinte cenário:

  • O Desenvolvedor A instala o pacote "abc" na versão 2.1.1 → No package.json fica:

    "abc": "^2.1.1"

  • Três meses depois, o Desenvolvedor B clona o projeto e executa npm install. Nesse meio tempo, novas versões de "abc" foram lançadas:

    2.1.3, 2.1.5, 2.2.1, 2.2.6, 3.0.0, 3.0.1

Como a regra ^2.1.1 permite atualizações de minor e patch, o NPM instala a versão 2.2.6 (a mais recente compatível).

🔸 Resultado:

  • Desenvolvedor A usa a 2.1.1
  • Desenvolvedor B usa a 2.2.6

Mesmo com o mesmo package.json, ambos têm versões diferentes, o que pode causar erros e inconsistências no projeto.

🔒 O que é o arquivo package-lock.json?​

O package-lock.json é a versão bloqueada do package.json. Ele é gerado automaticamente sempre que instalamos, removemos ou atualizamos pacotes com o NPM.

Sua função principal é registrar as versões exatas dos pacotes instalados — incluindo subdependências (dependências das dependências).

⚙️ Como o package-lock.json funciona?​

Ao executar npm install, o NPM:

  1. Lê o package.json para saber quais pacotes instalar.
  2. Verifica o package-lock.json para saber quais versões exatas usar.

Se a versão no package-lock.json for compatível com o package.json (seguindo o SemVer), o NPM instala exatamente essa versão.

🧩 Exemplo prático​

  1. Desenvolvedor A

    • Instala "abc" na versão 2.1.1.

    • O package.json fica com:

      "abc": "^2.1.1"

    • O package-lock.json registra:

      "abc": "2.1.1"

  2. Três meses depois, Desenvolvedor B

    • Clona o projeto e executa npm install.
    • O NPM encontra "abc" no package-lock.json com a versão 2.1.1, verifica que é compatível com ^2.1.1, e instala a mesma versão.
    • Agora ambos usam a versão 2.1.1 → sem conflitos ✅

Se o package-lock.json não existisse, o NPM instalaria a versão mais recente compatível (2.2.6), recriando o problema inicial.

🧭 Conclusão​

✔️ O arquivo package-lock.json garante que todas as instalações (npm install) resultem nas mesmas versões de pacotes, em qualquer máquina.

📌 Boas práticas:​

  • Sempre versione o arquivo package-lock.json junto com o código no repositório. Assim, todos os desenvolvedores e pipelines CI/CD usarão as mesmas versões.
  • Não edite o package-lock.json manualmente — ele é gerenciado automaticamente pelo NPM.
  • Faça atualizações de dependências apenas alterando o package.json.

🧠 Em resumo​

ArquivoFunçãoGeraçãoO que contém
package.jsonDefine dependências e metadados do projetoManualVersões em SemVer (ex: ^1.2.3)
package-lock.jsonBloqueia versões exatas das dependênciasAutomáticaVersões específicas instaladas (ex: 1.2.3)