DEV Community: coin_guy

Do package.json ao runtime: como o npm resolve, instala e entrega dependências

coin_guy — Sun, 24 Aug 2025 23:12:29 +0000

Às vezes me pego pensando o quanto o package.json é subestimado no meio do desenvolvimento Node/Web.

O senso comum trata ele quase como uma lista de compras: “nomes de pacotes com uma numeração na frente”, e quando essa lista está pronta a gente cruza os dedos e roda um npm i (na maioria das vezes npm i -f, aquele jeitinho pra não ter que lidar com peerDependencies 😀) e ficamos esperando o download das nossas dependências.

E quando dá um problema inexplicável na sua aplicação? Sempre aparece alguém com o mantra clássico:

“Apaga a node_modules, deleta o package-lock.json e roda um install de novo.”

É praticamente o “desliga o modem, espera 5 segundos e liga de novo” das nossas aplicações.

Mas será que o package.json é só isso? Ou será que ele é, de fato, o core da sua aplicação e deveria receber mais atenção? 🔍.

Package.json como contrato

A documentação do NPM tem uma longa e extensa definição sobre o que o package.json representa e logo nos primeiros momentos de leitura já percebemos de que não se trata apenas de um arquivo ou um "simples objeto JavaScript". Podemos listar algumas das responsabilidades que esse arquivo tem segundo a documentação que acabamos de ver:

É o Manifesto do seu projeto: define a identidade da sua aplicação: nome, versão e outros metadados. É essencial para qualquer aplicação conseguir consumir demais pacotes npm (e no caso de libs a importância se estende para conseguirmos publicar e disponibilizar essa lib para demais desenvolvedores)
Campos obrigatórios e complementares: name e version são obrigatórios apenas se você pretende publicar o pacote no npm (version deve seguir o padrão do semanticVersion: major.minor.patch). Para projetos internos (apps que não vão pro registry), tecnicamente você consegue rodar sem version, mas a boa prática é sempre manter. Como campos complementares podemos ter: description, author, license, repository, keywords, homepage e entre outros (úteis para documentação, publicação e identificação).
Dependencies: é onde definimos os pacotes essenciais para que a nossa aplicação funcione (exemplo: no caso de uma aplicação Angular, aqui vamos encontrar os pacotes vitais @angular). Dependências vão para o bundle final(prod) da aplicação ao contrario de dependências de desenvolvimento.
DevDependencies: pacotes que são usados apenas no ambiente de desenvolvimento: jest, eslint, cypress, bundlers, TypeScript e entre outros.

Um ponto importante sobre Dependencies e DevDependencies: elas seguem um padrão de versionamento baseado no semVer: (^, ~, 1.0.0), que é importante para controle de compatibilidade e atualizações previsíveis dos nossos pacotes
Scripts automatizados: esse campo do arquivo é responsável por adicionar scripts personalizados para executarmos alguma rotina que precisamos através do comando npm run <nome_do_comando>. Aqui também temos acesso a hooks que podem ser disparados de maneira pre<nome_comando> ou post<nome_do_comando>

{
  "scripts": {
    "build": "echo '🔨 Construindo app...'",
    "prebuild": "echo '📦 Limpando dist antes do build...'",
    "postbuild": "echo '✅ Build finalizado com sucesso!'"
  }
}

Na ordem de execução ficaria => prebuild, build, postbuild.

Existem alguns outros campos bem legais do package.json como:

Engine: que define versões mínimas e máximas requeridas para que você possa executar aplicação
OS: em que sistema operacional sua aplicação pode ser executada (e se for necessário em qual OS não pode ser executado)
CPU: o tipo de arquitetura de CPU que sua aplicação pode ser executada (semelhante ao OS)

Com isso, o package.json deixa de ser apenas “uma lista de compras” e passa a ser visto como o contrato central que garante que seu projeto vai rodar, compilar e ser instalado do jeito planejado.

Rodando o install e entendendo como ele funciona

Então o seu package.json já está configurado e com as dependências que você precisa listadas com as versões alinhadas, agora seu próximo passo é rodar o npm install e ver toda aquela mágica de toneladas e toneladas de pacotes sendo baixadas. Mas como funciona isso por debaixo dos panos? é um processo simples? quando executamos o install o npm simplesmente tira os pacotes nas versões que precisamos de algum canto misterioso e auto-mágico, assim como um mágico tira um coelho da cartola?

e a resposta é .... NÃO!

Na verdade o processo de download e instalação de pacotes npm é muito mais burocrático do que parece.

Assim que executamos um npm install nas nossas aplicações a primeira pergunta que o npm se faz é: "cadê o package-lock.json dessa aplicação ???"

package-lock.json: A caixa-preta do projeto

Quando algum avião tem qualquer tipo de problema, o primeiro lugar que todos vão checar é a famigerada "caixa preta", a caixa preta não abre margem para chutes e achismos, o que está nela são os registros absolutos do avião...assim como o package-lock.json é a caixa preta dos seus pacotes. O lock não é apenas um arquivo gigantesco que serve para complicar a sua vida com changes no momento de um git rebase ou um git pull, ele é justamente o registro fiel de como cada dependência sua foi instalada, um raio-x perfeito da arvore de dependências da aplicação

Vamos olhar com um pouco mais de proximidade para o caso do @angular/core e tomar como exemplo para os demais:

no package.json a dependência está listada como:

"@angular/core": "^16.2.0",

Quando usamos o semVer range syntax (~, ^) não sabemos exatamente a versão especifica do pacote que será baixada para o nosso projeto, temos como ter um controle e uma certa visibilidade, mas se usamos o range syntax (o mais comum) ficamos com algumas incertezas sobre a versão. Essas incertezas se tornam certezas quando olhamos no detalhe o registro da dependência no package-lock.json

Aqui nós temos o registro exato da dependência:

A dependência foi instalada na versão 16.2.9.
Ela foi encontrada no registry do npm (não foi configurado o uso de nenhum "articatory" ou qualquer outro tipo de Registry privado (como Nexus, Verdaccio, etc.). Curiosidade: o arquivo do pacote vem no formato .tgz. Experimente rodar npm pack no build de uma lib Node e veja o pacote gerado: nome_da_sua_lib.tgz.
O pacote está integro e tem a garantia disso através de uma chave SHA512, mas o que isso quer dizer ? quer dizer que o pacote que você baixou está em conformidade com o que o autor publicou no npm, evitando que você baixe pacotes com conteúdos malicioso/prejudiciais.
Todos os pacotes adicionais que a dependência precisa serão baixados para funcionar corretamente graças ao campo requires.

E por aqui já podemos ver o quanto é importante termos apenas as dependências que precisamos nos nossos projetos, afinal as dependências também tem dependências o que gera mais download de pacotes....logo node_modules tende ao infinito 😁.

Para finalizarmos o assunto package-lock.json: se sua aplicação já estiver com um install ou seu projeto clonado já vier com um package-lock.json (é uma boa práticas sempre que necessário comitarmos o package-lock.json, inclusive é uma questão de segurança), o npm vai usar esse arquivo como referencia e ir fazendo o download de dependência por dependência seguindo com fidelidade a questão do registry(presente no campo resolved) e das versões, garantindo a reprodutibilidade do seu projeto.

Continuando o fluxo do npm install

Dada a necessária explicação sobre o package-lock.json, vamos voltar a falar agora sobre como o npm te entrega esses pacotes, do registry até a sua máquina...e para isso nada melhor que um fluxograma certo? (fluxogramas salvam vidas, pode confiar)

Neste fluxo ainda não estamos considerando peerDependencies no processo de instalação, uma breve explicação sobre peerDependecies:

São dependências que os pacotes precisam que o consumidor também instale, porque ela não vai instalar sozinha.
A partir do npm v7, o npm tenta instalar automaticamente as peerDependencies quando possível. Se houver conflito de versões que ele não consegue resolver, ele falha e pede instalação manual.

E após todo esse processo de: checagem, download, extração e disponibilização, os seus pacotes vão estar prontos para consumo em runTime e sua aplicação (esperamos todos nós) vai estar funcional.

Estamos certos em cruzar os dedos toda vez que rodamos um npm i, afinal de contas olha quantos processos são executados por "de baixo do capô", e quase um jogo de azar no qual sempre torcemos pelo nosso gerenciador de pacotes nos salvar de mais algum bug que vai nos custar horas.

E você? já tomou algum erro de peerDependecies ou de ETARGET?

Da Glória ao Caos: como CJS e ESM dividem o JavaScript até hoje

coin_guy — Sun, 25 May 2025 17:29:03 +0000

JS é uma linguagem de programação fantástica, que te dá a possibilidade de fazer inúmeras coisas — desde um gráfico bem ilustrado, até modelos 3Ds incríveis.

Mas o JavaScript não se limita a gráficos bonitos ou interfaces coloridas.

Precisa de uma API? Ótimo, o Node.js pode te atender.
Quer uma aplicação performática? Builders modernos com SSR e SSG podem resolver seus problemas (e talvez até criar outros no caminho) com velocidade.

Aplicações mobile? WebViews criadas com frameworks JS vão te salvar.
Quer criar seu próprio jogo? Dá uma olhada no Phaser.

A lista é extensa: bots, pacotes NPM, Machine Learning... JS é praticamente o gênio do Aladdin esperando para sair da lâmpada: "Você nunca teve um amigo como eu."

Mas, ainda assim, temos os críticos, não precisa pesquisar muito para encontrar alguém reclamando do JS no Reddit, no Stack Overflow ou em algum fórum de programação.

Os motivos variam desde opiniões pessoais até coisas que, de fato, são difíceis de defender no JavaScript...principalmente quando falamos de coerções de tipo e comparações inesperadas.

Além disso, há frustrações práticas: ter que alinhar versões dos pacotes NPM no package.json para que tudo volte a funcionar depois de um erro inesperado é algo comum. Problemas com dependências quebradas por atualizações são reais, e podem virar uma dor de cabeça.

E você ainda pode ter mais azar: cair num problema de incompatibilidade entre CJS e ESM — o motivo que originou este post:

É... e então, de repente, aquele seu amigo gênio começa a virar um pesadelo.

Cada versão de cada pacote pode se tornar seu inimigo.

E o pior: qual pacote é o culpado?
Você só vai descobrir trocando as versões, deletando o node_modules, dando npm install, rodando npm start e torcendo.
Cada tentativa é um teste de fé, corrigir o pacote X pode quebrar o Y e
a tarefa que parecia durar 2 horinhas vira um loop eterno de frustração. Parece raro… mas acontece muito.

Queria te dizer que existe uma bala de prata pra resolver isso — mas não tem.
Ninguém vai vir te salvar. 🤯

O que dá pra fazer é entender os mecanismos, a história, e os "porquês" por trás dessas decisões no JavaScript.
Conhecer a linguagem a fundo vai te dar mais controle, vai fazer você parar de suar frio quando vir o infame diretório node_modules nos logs de erro.

A ORIGEM DO PROBLEMA ENTRE CJS E ESM

Se você voltar um pouco no tempo e na história do JS, vai notar que o motor V8 (o interpretador do JS do Chrome) era executado apenas no lado do cliente.

O Node ainda não existia, e não tínhamos JavaScript no backend.

O JS no lado do cliente não era nem de longe "parrudo" e complexo como é hoje.

Módulos? Isso não existia. Empacotadores como Webpack? Só daqui a alguns anos. Frameworks? Muito futurista.

Naquela época, JavaScript sequer tinha noção de modularidade. Não existia import, nem export. Tudo que você escrevia, você torcia pra não colidir com mais nada.

O que tínhamos era um arquivo index.html que carregava alguns JS hospedado em algum servidor, e quando esse arquivo era consumido, o navegador apenas interpretava os JS com o V8 — e com isso, renderizava a aplicação na tela.

Quem reinava nessa época era o nosso saudoso jQuery, que ainda está presente em aproximadamente 73% de todos os sites da web!!

Mas aí vem a pergunta: como as coisas eram feitas no passado? se não tínhamos módulos? Todo o código da aplicação era inserido em um único JS?

Quase isso.

Nesse período, tínhamos o famoso "script soup": o arquivo index.html era encarregado de carregar todos os JS da aplicação — seja via CDN, seja arquivos próprios:

Parecia simples e até fácil de controlar.

Mas aí começa o caos: todos os arquivos JS carregados dessa forma são executados no mesmo escopo global.

O que isso significa? Que funções e variáveis declaradas em um arquivo podem ser sobrescritas por outro sem nem te avisar.

E mais: os scripts são executados na ordem em que aparecem no HTML.

Ou seja, se você tentar usar uma função antes de ela ser carregada, pode dar erro — mesmo que ela exista em outro arquivo.

Vamos a um exemplo simples:

`script1.js`

const dogsName = 'Zelda';
function sayHiToDog() {
  console.log("Hi " + dogsName);
}

`script2.js`

const dogsName = "McIntosh";

Se esses dois scripts forem incluídos no mesmo HTML, você vai se deparar com esse erro no console:

Uncaught SyntaxError: Identifier 'dogsName' has already been declared (at script2.js:1:1)

Por quê?
Porque o conteúdo dos arquivos JS é carregado como se tudo estivesse em um mesmo arquivo gigante.
Todos os valores, funções e variáveis vazam para o escopo global. Isso abre espaço pra conflitos, sobrescrições e bugs que só aparecem no runtime.

Longe do caos da web

Um pouco distante do cenário mencionado acima, em 2009 tivemos o lançamento do Node.js (para felicidade de alguns e tristeza de outros): tínhamos agora JS no backend!

Pra lidar com a bagunça que era a gestão de arquivos no frontend — cheio de scripts globais brigando por espaço — o Node adotou um modelo de modularização inspirado em uma proposta da comunidade chamada commonJS.

Nasce uma solução no backend para iluminar o frontend

O commonJS era uma maneira mais elegante de lidar com importação de trechos de código para os arquivos, por que? porque ele tratava os arquivos/dependências como módulos!. Com o commonJS, o JavaScript finalmente ganhava uma forma real de modularização prática e isolada, sem depender de escopo global.

Se você já mexeu em alguma aplicação nodeJS com certeza já viu essas palavrinhas soltas por ai: require e module.exports, e são justamente elas que faziam a mágica acontecer. O require importava o que outros arquivos exportavam como módulo e o module.exports exportava o conteúdo que você queria dos seus scripts.

const dogsName = "McIntosh";
module.exports = {dogsName}

E para consumir isso bastava você chamar o require

const {dogsName} = require('./script1')
console.log(dogsName) //McIntosh

O commonJS no front

Com o nodeJS ganhando cada vez mais espaço, os desenvolvedores começaram a se dedicar na criação de pacote modularizados(npm) para suas aplicações, pacotes esses com funções reutilizáveis que poderiam ser adicionados em qualquer aplicação, e as libs mais antigas ao commonJS (lodash e o axios por exemplo) começaram a seguir esse caminho também e se modularizaram utilizando essa mecânica, que revolucionou como o JS lidava com a gestão do código. Mas ai temos um problema, o navegador não entendia essa sintaxe de require e module.exports do nodeJS ☠, se você fizer um teste rápido no seu navegador colocando isso:

const dogsName = require('dogsLib');

O navegador não vai reclamar que dogsLib não existe (e não existe mesmo) ele vai é reclamar que require não existe! por conta da execução quebrar antes da tentativa da importação.

VM361:1 Uncaught ReferenceError: require is not defined

E como resolvemos isso ? como vamos trazer um pedacinho do nodeJS para o navegador ? é aí que surgem os bundlers — ferramentas que ajudam a trazer essa modularização para o ambiente do navegador.

Sobre os Bundlers

Quando estamos no nosso processo de desenvolvimento de aplicações no front, raramente nos atentamos aos bundlers (webpack, browserify, esbuild...) a menos quando temos algum erro que cite que o bundler quebrou no processo de compilação. Mas para que serve os bundlers e como eles solucionaram esse problema de trazer a modularização para o front?

Bom, entre as inúmeras funções que um bundler tem uma delas é a de deixar o código "entendível" ao navegador, quando adicionamos um bundler na aplicação o fluxo deixa de ser:

Seu JS -> Navegador

para:

Seu JS -> bundler -> Navegador

O navegador não sabe o que é a sintaxe de modularização do nodeJS e o bundler sabe disso, então nesse caso o bundler vai agir também como um tradutor para o navegador, ele vai compilar o seu código JS em algo que o navegador não tenha nenhuma dificuldade de entender tentando manter ao máximo a fidelidade do que o seu código está fazendo e como ele está lidando com a gestão dos módulos. E com a adição dos bundlers no front voa lá, temos modularização em aplicações web também.

Nem tudo são flores

Todo começo de relacionamento é um mar de flores, mas nem todos eles continuam assim com o passar do tempo, e foi justamente isso que aconteceu na relação navegador e CJS. O CJS revolucionou e não foi pouco não a maneira como os desenvolvedores web olhavam para a estrutura do seu código, mas mesmo assim o commonJS não tinha nascido para o front, ele foi "empurrado" para lá e com isso os problemas que não notávamos no backend começaram a se apresentar no frontend. Problemas como:

performance: A execução síncrona do CJS pode ser um gargalo no cliente, onde o carregamento não pode bloquear a renderização da página. Somado a isso temos problemas que impossibilitam muito uma tentativa de tree-shaking do que realmente está sendo usado do módulo e do que não está.
inconsistência: apesar existir uma certa coerência, especialmente em épocas anteriores, diferentes bundlers implementavam o suporte ao CJS de maneiras ligeiramente distintas, gerando uma certa inconsistência no momento de build (o mesmo arquivo tinha builds diferentes no webpack e em outro bundler).
sem suporte: a comunidade entendeu a dor de não dar suporte para os módulos e começou a trabalhar em uma maneira diferente de gerir isso, criando o ESM, ao invés de dar suporte ao CJS.

Conhecemos o ESM

O escmaScript 2015 (ES6) foi considerado por alguns uma das versões que mais revolucionaram o JS, e não estou nem falando da criação de features modernas que tiraram aquela aparência de "linguagem remendada" do JS como: variáveis que respeitam o escopo que são declaradas (let e const), arrow functions ou classes, estamos falando dos ESModules. Se o CJS era a solução elegante ao carregamento global de scripts, o ESM era a solução elegante ao CJS. O CJS era popular e difundido na comunidade web (o que vai ser um problemão) e o desafio do ESM era provar o seu valor cobrindo as brechas deixadas pelo CJS no web.

ESM vs CJS na Web — Comparativo de Benefícios

Característica	ESM (ES Modules)	CJS (CommonJS)
Suporte nativo em navegadores	✅ Sim	❌ Não (precisa de bundler)
Carregamento assíncrono	✅ Sim	❌ Não, é síncrono
Tree-shaking (remoção de código)	✅ Suportado pelos bundlers modernos	❌ Ineficiente, exige soluções manuais
Importação dinâmica (`import()`)	✅ Suporte nativo	✅ Suporte via `require()`
Análise estática de dependências	✅ Sim, desde o parse inicial	❌ Não, requer execução
Paralelização de carregamento	✅ Sim	❌ Não
Execução condicional de módulos	❌ Não (estrutura rígida)	✅ Sim (pode usar lógica com `require`)
Compatibilidade com o Node.js	✅ Sim (desde Node 12+ com `type: module`)	✅ Sim, nativamente
Padrão moderno	✅ Sim, especificação oficial	❌ Legado, criado como solução temporária
Ideal para aplicações web	✅ Totalmente	❌ Foi adaptado via bundler

Para o contexto de web (que é o foco desse artigo) o ESM já nasce com uma vantagem imensa em relação ao CJS, ele foi planejado e projetado para ser nativo nos navegadores.

O ESM logo ganhou tração e os pacotes e projetos web passaram por refatorações para dizer adeus ao CJS e olá ao ESM, e aqui para variar temos outro problema.

Os fantasmas do passado sempre te perseguem

Não é um mal limitado aos humanos essa questão dos erros do passado continuarem existindo no futuro, isso aconteceu com a web também! e nesse caso vamos falar de como o CJS continua assombrando a web mesmo com uma década de ESM(considerando a data de criação desse post).

Muitos pacotes que foram escritos com CJS não foram refatorados para ESM, e isso acaba gerando uma verdadeira salada de frutas com o projeto usando pacotes ESM e pacotes CJS (tipos diferentes de sintaxe de execução, CJS usa require enquanto ESM usa import, maneiras diferentes de como lidam com o carregamento de módulo e entre outros pontos.)
Uma complicação em fazer pacotes CJS funcionar no web, vide o Jest (talvez esse seja um pouco pessoal) que precisa de um arquivo de configuração com um mapper explicando para a lib como ela deve tratar pacotes ESM na hora da execução dos testes.
Frameworks conhecidos com versões mais recentes não dão mais nenhum tipo de suporte ao CJS (não é mesmo Angular v17+), pegando como exemplo o Angular v17+ que vem por padrão com o ESBuild como bundler, você pode se deparar com essa surpresa ao buildar uma aplicação com o ESBuild que ainda tem pacotes no CJS:
Todo esse problema entre CJS e ESM reforça mais um dos problemas que listamos no inicio desse post, a necessidade de ficar "alinhando" as versões das dependências do seu projeto e torcer MUITO para que o npm start funcione como estava funcionando antes e não que alguns desses dizeres se apresente no console:

ReferenceError: exports is not defined in ES module scope
SyntaxError: Cannot use import statement outside a module
TypeError: Module "x" does not provide an export named "default"

As vezes me pego pensando de que a web ainda está em um momento de "velho oeste" aonde as coisas ainda estão se estabelecendo mas não existe muito uma lei a ser seguida... e você? acha que as coisas já estão estabelecidas ou que ainda existirão mudanças drásticas assim como mudamos de CJS para ESM?

Bom esse foi um breve resumo de como os módulos surgiram na web e de como eles podem facilitar e complicar muito a sua vida. Espero que tenha gostado, nos vemos por aí 🤠.