Dependências e lockfile

Reprodução exige mais que um arquivo

Dependência é algo de que o programa precisa para funcionar ou ser desenvolvido. Ela pode ser uma biblioteca externa, um recurso de execução ou um contrato entre módulos. Neste capítulo, o foco é a instalação de pacotes. A Oficina Caracol não depende de bibliotecas de terceiros: usa JavaScript e APIs padrão. Ainda depende de um runtime Node compatível e de arquivos coerentes.

package.json descreve o pacote, seus comandos e suas dependências declaradas. package-lock.json registra a resolução correspondente gerada pelo npm, o gerenciador de pacotes. Em projetos com pacotes externos, o lockfile identifica versões e outras informações da árvore resolvida. Isso contribui para repetir a instalação, mas não comprova, sozinho, que o programa funcionará em qualquer ambiente.

O runtime, a versão do gerenciador, o modo de instalação, a integridade e disponibilidade das fontes e particularidades da plataforma também podem importar. Por isso a afirmação correta é que o lockfile participa da reprodutibilidade. A prova exige instalar do modo previsto e executar as verificações no ambiente identificado. S14, descrição de npm ci, explica a instalação orientada por um lockfile compatível.

Contrato de instalação preenchido

No projeto sem dependências externas, o lockfile pode ser pequeno. Seu conteúdo exato deve vir da geração efetiva, sem inventar versões, hashes de integridade ou resultados. Não se deve acrescentar uma dependência apenas para tornar esse arquivo mais interessante. O valor didático está em compreender a relação entre manifesto, resolução, ambiente e prova.

node --version
npm ci
npm test
npm run validate

Execute a sequência dentro de pratica. npm ci exige um lockfile compatível com package.json e pode remover a pasta de instalação existente antes de instalar. Ele não é o comando para atualizar deliberadamente dependências. Se os arquivos não correspondem, a falha é informação: investigue a mudança, em vez de apagar o lockfile e declarar que a repetição foi garantida.

Avaliar uma dependência proposta

Imagine uma proposta futura de biblioteca para desenhar cartões. Antes de incluí-la, pergunte qual requisito ela atende, que alternativa já existe na plataforma, qual licença e manutenção se aplicam e como sua remoção seria feita. Se aceita, registre sua inclusão, revise a alteração do manifesto e do lockfile e repita instalação e verificações. S10, especificação de versionamento semântico, descreve o significado de versões para interfaces que adotam esse contrato; um número de versão não dispensa teste de compatibilidade.

• Defina o motivo da dependência e o responsável por acompanhá-la.
• Verifique origem, licença, manutenção e riscos pertinentes ao uso.
• Gere os arquivos pelo gerenciador escolhido e revise o que realmente mudou.
• Faça uma instalação de conferência e execute as provas aplicáveis.
• Mantenha um caminho de retorno identificável, sem misturar atualização de dependência com mudanças funcionais sem relação.

Erros e reparos correspondentes

Exercício e solução comentada

Dados: uma pessoa altera package.json para incluir uma biblioteca, mantém o lockfile anterior e executa npm ci. O comando recusa a instalação. Ela propõe mudar para uma instalação que atualize tudo automaticamente e seguir adiante. Como tratar a falha?