Tudo que voc queria saber sobre o package-lock.json mas estava com vergonha de perguntar

Esse texto uma traduo livre do artigoEverything You Wanted To Know About package-lock.json But Were Too Afraid To Ask.

Introduo

Ento voc atualizou o Node Package Manager (npm) para a verso 5.x.x e tudo parece que est funcionando bem, certo? Mas pera, o que isso? Um novo arquivo foi criado automaticamente:package-lock.json. Se voc abri-lo at vai parecer umpackage.json, mas com muito mais coisa, mais verboso. Voc decide ignor-lo enquanto desenvolve seu projeto. Eventualmente voc se depara com um problema de dependncia. No pode ser encontrada ou uma verso errada foi instalada. A maior parte das pessoas deleta opackage-lock.jsone reexecuta onpm install. Ento por que o temos? O que deveramos fazer? O que ele faz?

Resumo

• Se voc est usando uma verso do NPM superior a 5.x.x opackage-lock.jsonser gerado para voc;
• Voc deve usar opackage-lock.jsonpara garantir uma instalao consistente e dependncias compatveis;
• VocDEVEcommitar seupackage-lock.jsonem seu sistema de controle de verso;
• A partir da verso 5.1.0 do npm o contedo dopackage.json capaz de sobrescrever o que estiver nopackage-lock.jsonpara instalar ou modificar uma dependncia, o que*deve*gerar menos dor de cabea;
• No precisa mais deletar opackage-lock.jsone executar onpm installpara reger-lo;
• Use semver (versionamento semntico) se sua aplicao for uma API e siga as regras do semver.

Background

Versionamento Semntico (semver)

Antes de entender opackage-lock.jsone opackage.jsonvoc precisa entender oversionamento semntico (semver). a sacada por trs do NPM, e o que o tornou um sucesso. Voc pode ler mais sobre como o NPM faz seu uso poraqui.

De forma resumida, se voc est criando uma aplicao com a qual outras iro integrar, voc deve comunicar como as alteraes feitas afetaro a capacidade de integrao desses terceiros com sua aplicao. Isso feito atravs do versionamento semntico.

Uma verso dividida em 3 partes: X, Y e Z, onde a primeira considerada amajor(principal), a segunda, aminor(menor) e a terceira opatch*(correo).*Um exemplo como 1.2.3 representaria que 1 a major, a 2 a minor, e o 3 o patch.

• Uma modificao no patch no quebrar nada. Muito pelo contrrio, corrigir algo.
• Uma alterao na verso minor lhe trar uma nova funcionalidade, mas sem quebrar o que existe atualmente.
• E por fim, alterar algo na verso major significa que houve uma quebra de compatibilidade. Se o usurio no fizer a alterao necessria, ele no conseguir mais integrar com sua aplicao.

Gerenciando pacotes

O NPM existe para facilitar o gerenciamento de dependncias. Seu projeto pode ter centenas de dependncias, cada uma com suas prprias dependncias. Para nos mantermos longe desse inferno de dependncias, o NPM foi criado com um conjunto de comandos que permitem voc instalar e gerenciar tudo isso e, dificilmente, precisar se preocupar com elas.

Quando voc instala um pacote com o NPM (e o salva), uma nova entrada adicionada ao arquivopackage.jsoncontendo o nome do pacote e a verso (semver) que ser usada. Entretanto, existem algumas artimanhas para definir melhor as verses.

Por padro o NPM instalar a verso mais nova do pacote, inserindo um smbolo na frente da verso^2.12.0. Isso significa que o pacote ser instalada com uma verso que seja igual ou superior a 2.12.0. Leia mais sobre semver e wildcards e brinque com umaferramenta para calcular a verso do pacote.

Projetos Compartilhados

O real benefcio de ter dependncias definidas nopackage.json que qualquer um pode ter acesso a esse arquivo e criar um pasta de dependncias contendo todos os mdulos para rodar sua aplicao. Mas vamos dar uma olhada em uma caso especfico em que as coisas podem dar errado.

Vamos dizer que criamos um projeto utilizando oexpress. Depois de rodarnpm initinstalamos o express:npm install express --save. At o momento em que escrevo esse artigo, a ltima verso do express a 4.15.4. Ento ser adicionado como dependncia aopackage.jsona linhaexpress: ^4.15.4, e isso informar exatamente a verso que ser instalada em meu computador.

No agora, mas talvez amanh, o pessoal que desenvolve o express pode lanar um bug fix, ento a nova verso ser a 4.15.5. Ento se algum quiser contribuir com meu projeto, precisar clon-lo e rodar o comandonpm install. Com isso ele ter instalado em seu computador a verso 4.15.5. Ns dois teremos o express instalado, mas verses diferentes. Teoricamente ambas devem ser compatveis, mas talvez esse bug fix afete alguma funcionalidade que fazemos uso, e nossa aplicao poder produzir resultados diferentes, j que uma possui a verso 4.15.4, e outra a 4.15.5.

Package-lock

O objetivo

A proposta dopackage-lock evitar que situaes como o caso acima, onde mdulos instalados a partir do mesmopackage.jsonresulte em duas diferentes instalaes. Opackage-lockfoi adicionado em verses superiores ao do NPM 5.x.x, ento se voc est usando essa verso ou alguma maior, voc o ver ser gerado, a no ser que voc desabilite essa funo.

O formato

Opackage-lock.json uma larga lista de dependncias listadas no seupackage.json, alm de especificar a verso exata que deve ser instalado, a localizao do mdulo (URI), o hash que verifica a integridade do mdulo e a lista de pacotes necessrios. Vamos dar uma olhada nos registros presentes apenas para o express:

"express": {      "version": "4.15.4",      "resolved": "https://registry.npmjs.org/express/-/express-4.15.4.tgz",      "integrity": "sha1-Ay4iU0ic+PzgJma+yj0R7XotrtE=",      "requires": {        "accepts": "1.3.3",        "array-flatten": "1.1.1",        "content-disposition": "0.5.2",        "content-type": "1.0.2",        "cookie": "0.3.1",        "cookie-signature": "1.0.6",        "debug": "2.6.8",        "depd": "1.1.1",        "encodeurl": "1.0.1",        "escape-html": "1.0.3",        "etag": "1.8.0",        "finalhandler": "1.0.4",        "fresh": "0.5.0",        "merge-descriptors": "1.0.1",        "methods": "1.1.2",        "on-finished": "2.3.0",        "parseurl": "1.3.1",        "path-to-regexp": "0.1.7",        "proxy-addr": "1.1.5",        "qs": "6.5.0",        "range-parser": "1.2.0",        "send": "0.15.4",        "serve-static": "1.12.4",        "setprototypeof": "1.0.3",        "statuses": "1.3.1",        "type-is": "1.6.15",        "utils-merge": "1.0.0",        "vary": "1.1.1"      }    },

Entradas equivalentes podem ser encontradas para cada pacote listado na seo requires.

Ento a ideia que ao invs do NPM ler opackage.jsonpara instalar os mdulos ele use opackage-lock.json. Isso acontece justamente por conta do que disse anteriormente. Pelopackage-lockespecificar a verso, localizao, hash para cada mdulo, e suas dependncias prprias, a instalao criada ser sempre a mesma, toda vez. No importa qual dispositivo voc use, ou quando voc far a instalao, ele dever ter o mesmo resultado, sempre, e isso til demais.

A controvrsia

Ento, se opackage-lock.jsonsupostamente resolve um problema comum, por que os principais resultados de pesquisa (alm da documentao do npm) so todos sobre desabilit-lo ou questionar a funo que ele desempenha?

Antes do NPM 5, opackage.jsonera a fonte absoluta para qualquer projeto. O que estava nele era a lei. Os usurios do NPM gostaram desse modelo e se acostumaram a mant-lo assim. Entretanto, quando opackage-lockfoi introduzido, ele agiu de forma contrria ao que as pessoas esperavam.

Dado um pacote preexistente e umpackage-lock, uma alterao nopackage.json(o que muitos usurios consideravam a fonte da verdade) no era refletida nopackage-lock.

Exemplo: Pacote A, verso 1.0.0 nopackagee nopackage-lock. Nopackage.jsona verso A foi alterada manualmente para 1.1.0. Se um usurio considerar opackage.jsoncomo a fonte da verdade e executar onpm install, ele ir esperar que a verso 1.1.0 seja instalada. Entretanto, a verso 1.0.0 instalada, apesar do fato de que a verso 1.1.0 est listada nopackage.json.

Exemplo:Um mdulo no existe nopackage-lock.json, mas existe nopackage.json. Como um usurio que olha para opackage.jsoncomo a fonte de toda a verdade, eu esperaria que meu mdulo fosse instalado. No entanto, como o mdulo no est presente nopackage-lock.json, ele no est instalado e meu cdigo falha porque no consegue encontrar o mdulo.

Na maior parte do tempo, porque a pessoa no conseguiu descobrir o motivo de suas dependncias no estarem sendo instaladas corretamente, ela ir preferir remover opackage-lock.jsone rodar o comandoinstallnovamente, ou ir desabilitar sua criao.

O conflito entre o esperado e a realidade gerouuma discusso muito interessante no repositrio do NPM. Algumas pessoas acham que opackage.jsondeveria ser a fonte da verdade, outras acham que desde que o NPM considerou opackage-lock.jsoncomo a fonte para realizar a instalao, essa deve ser a fonte real. A resoluo desse conflito est noPR #17508.Os contribuidores do projeto adicionaram uma mudana aopackage.jsonfazendo com que as regras presentes nele se sobrepujam ao que est nopackage-lock.

Agora, em ambos cenrios, os pacotes que os usurios esperam ser instalados, sero instalados corretamente. Essa mudana faz parte do release lanado na verso 5.1.0 do NPM, que foi ao ar em 5 julho de 2017.