Comandos npm Essenciais que Todo Desenvolvedor Deveria Conhecer

Mar 10, 2026 · 4 min read

Comandos npm Essenciais que Todo Desenvolvedor Deveria Conhecer

Você provavelmente usa npm install e npm run dev todos os dias sem pensar duas vezes. Mas a CLI do npm tem um conjunto de ferramentas muito mais profundo que pode economizar tempo real — seja depurando uma árvore de dependências quebrada, auditando vulnerabilidades ou executando um script pontual. Este guia cobre os comandos npm essenciais e padrões de fluxo de trabalho modernos que pertencem à prática diária de todo desenvolvedor.

Principais Conclusões

npm install, npm uninstall e npm outdated formam o núcleo do gerenciamento diário de dependências.
Use npm ls, npm explain e npm query para inspecionar e depurar sua árvore de dependências.
npm audit, npm sbom e npm diff fornecem ferramentas práticas para segurança e transparência da cadeia de suprimentos.
O campo overrides no package.json permite fixar dependências transitivas sem esperar por correções upstream.
Passar flags através de scripts com -- e executar binários pontuais com npm exec otimizam fluxos de trabalho comuns.

Instalando e Gerenciando Dependências

O cavalo de batalha do gerenciamento de dependências do npm é o npm install. Execute-o sem argumentos para sincronizar seu node_modules local com o package-lock.json. Adicione um nome de pacote para instalar algo novo:

npm install react            # runtime dependency
npm install vite --save-dev  # dev-only dependency

Para remover um pacote com segurança e limpar o package.json ao mesmo tempo:

npm uninstall lodash

Para verificar o que está desatualizado em seu projeto:

npm outdated

Isso fornece uma tabela clara das versões atual, desejada e mais recente — útil antes de decidir o que atualizar e quando.

Executando Scripts e Passando Flags

npm run sem argumentos lista todos os scripts definidos no seu package.json. Útil quando você está entrando em um projeto desconhecido.

Quando você precisa passar flags para o script subjacente, use -- para separá-las:

npm run build -- --watch --mode=development

Tudo após -- é encaminhado diretamente para o script, permitindo ajustar o comportamento sem tocar no package.json.

Inspecionando a Árvore de Dependências

Dois comandos que os desenvolvedores devem conhecer para depurar problemas de dependências são npm ls e npm explain (também com alias npm why).

npm ls renderiza sua árvore de dependências completa. Passe um nome de pacote para filtrar:

npm ls ms

npm explain informa por que um pacote específico está instalado — qual dependência direta o trouxe:

npm explain ms@0.7.1

Para filtragem mais avançada, npm query permite pesquisar dependências usando uma DSL no estilo de seletor CSS. Por exemplo, encontrar todos os pacotes que definem um script postinstall (uma verificação de segurança útil):

npm query ":attr(scripts, [postinstall])"

Executando Pacotes Sem Instalá-los

npm exec executa um binário de pacote usando as dependências locais do seu projeto, ou baixa temporariamente o pacote se ele ainda não estiver instalado. Nas versões modernas do npm, o comando npx delega para npm exec internamente.

npm exec -- create-react-app my-app

Ele respeita primeiro o node_modules local do seu projeto, tornando o comportamento mais previsível do que recorrer a uma instalação global.

Comandos npm Focados em Segurança

npm audit escaneia sua árvore de dependências contra bancos de dados de vulnerabilidades conhecidas e imprime um relatório classificado por severidade:

npm audit
npm audit fix          # auto-corrige atualizações seguras
npm audit fix --force  # aplica correções com breaking changes (teste minuciosamente depois)

Para transparência da cadeia de suprimentos, npm sbom gera uma Lista de Materiais de Software (Software Bill of Materials) — um inventário completo das dependências do seu projeto em formato legível por máquina:

npm sbom > sbom.json

Esta saída pode ser alimentada diretamente em ferramentas de segurança como Snyk para escaneamento mais profundo de vulnerabilidades.

Para comparar o que realmente mudou entre duas versões de pacote antes de atualizar:

npm diff --diff=ms@2.1.2 --diff=ms@2.1.3

A saída espelha o git diff, facilitando identificar mudanças inesperadas antes que elas cheguem ao seu projeto.

Fixando Dependências Transitivas

Quando uma vulnerabilidade existe em uma dependência transitiva que você não controla diretamente, use o campo overrides no package.json para forçar uma versão específica:

"overrides": {
  "node-ipc": "9.2.1"
}

Note que overrides é suportado no npm v8.3 e posteriores. Se você está usando Yarn, o recurso equivalente é resolutions. Esta abordagem é uma das maneiras mais práticas de manter uma árvore de dependências segura sem esperar pelos mantenedores upstream.

Conclusão

A maioria dos desenvolvedores apenas arranha a superfície do que o npm pode fazer. Os comandos cobertos aqui — de npm explain e npm query a npm sbom e overrides — preenchem a lacuna entre o uso básico e um fluxo de trabalho genuinamente eficiente. Comece com aqueles que correspondem aos seus pontos de dor atuais e construa a partir daí.

Perguntas Frequentes

npm exec é o comando integrado introduzido no npm v7 que executa binários de pacotes, e é para onde o npx delega internamente nas versões modernas do npm. A principal diferença é que npm exec verifica primeiro seu node_modules local, proporcionando comportamento mais previsível. Para a maioria das tarefas cotidianas, os dois são intercambiáveis, mas npm exec é a abordagem recomendada daqui para frente.

Execute npm audit fix para aplicar automaticamente atualizações seguras e compatíveis com semver. Se uma correção requer um bump de versão major, use npm audit fix --force, mas teste sua aplicação minuciosamente depois, pois breaking changes podem ser introduzidas. Para problemas de dependências transitivas fora do seu controle direto, use o campo overrides no package.json para fixar uma versão corrigida.

Use overrides quando uma vulnerabilidade ou bug existe em uma dependência transitiva e a dependência direta que a traz ainda não lançou uma correção. Ele força o npm a resolver uma versão específica daquele pacote aninhado. Este recurso requer npm v8.3 ou posterior. Sempre teste após aplicar um override, pois forçar uma versão pode causar problemas de compatibilidade.

Execute npm explain seguido do nome e versão do pacote, por exemplo npm explain ms@0.7.1. Isso imprime a cadeia completa de dependências que causou a instalação do pacote. Você também pode usar a forma abreviada npm why. Para uma visão mais ampla de toda a sua árvore de dependências, use npm ls com um filtro opcional de nome de pacote.

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.