Guia rápido de comandos npm

Guia rápido de comandos npm: install, ci, update, run, semver | We.Inc

Pesquise todos os comandos npm do dia a dia com suas flags, veja como o npm ci difere do npm install e teste qualquer range semver, como ^1.2.3 ou ~0.4, contra uma versão no seu navegador.

Guia rápido de comandos npm

Os comandos npm que você mais vai digitar são npm install para adicionar pacotes, npm ci para instalações limpas no CI, npm update para avançar dentro dos seus ranges de versão, npm uninstall para remover um pacote e npm run seguido do nome de um script. Pesquise a tabela completa abaixo e depois teste o que um range com caret ou tilde permite.

Os cinco que você precisa primeiro

Tarefa
Comando
Altera o package.json?

Adicionar um pacote
npm install react
Sim, adiciona em dependencies

Adicionar uma ferramenta de desenvolvimento
npm install -D vite
Sim, adiciona em devDependencies

Instalar exatamente o que o lockfile diz
npm ci
Nunca

Obter versões mais novas dentro dos seus ranges
npm update
Não, a menos que você passe --save

Remover um pacote
npm uninstall lodash
Sim, remove o pacote

As listas de comandos na internet costumam parar no nome de cada comando. Esta acrescenta as flags que as pessoas realmente usam, os aliases, o que cada comando grava no package.json e no lockfile, e um testador de ranges para você ver quais versões um caret, um tilde ou um x-range realmente aceitam.

Digite uma palavra como save, global ou lock na caixa de busca, ou escolha uma categoria, para filtrar a tabela de comandos.
Use o botão de copiar em qualquer linha para colocar o comando na área de transferência.
No testador de semver, informe um range e uma versão para ver se a versão o satisfaz e no que o range se expande.
Leia a seção de scripts para entender como se comportam o npm run, os scripts pre e post e o separador --.

Faça commit do package-lock.json. O npm ci se recusa a rodar sem ele, e é ele que faz duas máquinas instalarem a mesma árvore.
O npm update só avança dentro dos ranges do package.json. Para pular uma versão major, instale o pacote de novo com @latest ou com uma versão específica.
Use npm run sem nome de script para listar todos os scripts que um projeto define.
O npx executa o binário de um pacote sem instalação global, o que mantém pequena a pasta global da sua máquina.

Perguntas frequentes

Qual é a diferença entre npm install e npm ci?

O npm install resolve as versões a partir do package.json, pode atualizar o lockfile e mantém o node_modules existente. O npm ci exige um lockfile, apaga o node_modules primeiro, instala exatamente o que o lockfile lista, falha se ele divergir do package.json e nunca grava nenhum dos dois arquivos.

O npm update altera o package.json?

Não por padrão. A documentação do npm define save como false para o npm update, então só o node_modules e o lockfile mudam. Passe --save se quiser que as novas versões sejam gravadas de volta no package.json.

O que significa o caret em ^1.2.3?

Ele permite qualquer mudança que mantenha igual o primeiro número diferente de zero da esquerda. ^1.2.3 aceita 1.x a partir de 1.2.3, mas não 2.0.0. Abaixo de 1.0.0 ele é mais restrito: ^0.2.3 só aceita patches 0.2.x.

Como passo uma flag para o script por trás do npm run dev?

Coloque -- antes dela, por exemplo npm run dev -- --port 4000. Tudo o que vem depois dos dois traços vai para o script em vez de ser lido pelo npm.

O que significam Wanted e Latest no npm outdated?

Wanted é a versão mais alta que o range do seu package.json permite. Latest é a versão que o autor do pacote marcou como latest no registry. Quando Latest é maior que Wanted, obtê-la exige editar o range.

Install, ci e update fazem trabalhos diferentes

Use npm install enquanto desenvolve. Ele adiciona pacotes, salva no package.json por padrão e mantém o lockfile em sincronia com o que você pediu.
Use npm ci em servidores de build e em imagens Docker. Ele parte de um node_modules vazio e trata o lockfile como fonte da verdade, então todo build recebe a mesma árvore.
Use npm update quando quiser correções de bugs sem mexer nos ranges declarados. Rode npm outdated antes para saber o que vai mudar.

Scripts são atalhos com algumas regras

Tudo o que está no objeto scripts do package.json roda com npm run nome. O npm adiciona node_modules/.bin ao PATH do script, e é por isso que vite ou next funcionam ali sem instalação global.
Um script chamado prebuild roda antes de build, e postbuild roda depois. test, start, stop e restart são especiais o bastante para que você possa omitir a palavra run neles.

Ranges semver explicados

No que cada range se expande (regras do node-semver, usadas pelo npm)

Range
Significa
Permite

Atualizações minor e patch

Somente atualizações patch

Nada mais novo

Atualizações patch

O mesmo que 1.x

Qualquer patch de 1.2

Qualquer versão

Intervalo inclusivo

Scripts do package.json

Um bloco de scripts típico

prebuild roda automaticamente antes de build. Binários locais como vite são resolvidos a partir de node_modules/.bin.

Etapa de instalação para CI

Instalação limpa e repetível, um build e depois uma verificação de segurança que só falha em achados graves.

Configuração

Cria um package.json com as respostas padrão.

Instalar

Instala tudo o que está listado no package.json. Os aliases incluem npm i e npm add.

Instalar

Adiciona um pacote em dependencies e no lockfile; salvar vem ativado por padrão.

Instalar

Salva em devDependencies (forma longa --save-dev).

Instalar

Salva uma versão exata em vez de um range com caret (--save-exact).

Instalar

Salva em optionalDependencies (--save-optional).

Instalar

Instala sem registrar no package.json.

Instalar

Instala globalmente, na pasta prefix do npm em vez do projeto.

Instalar

Pula as devDependencies, por exemplo em um servidor de produção.

Instalar

Ignora conflitos de peer dependencies como as versões antigas do npm faziam.

Instalar

Instalação limpa a partir do lockfile: apaga o node_modules e nunca grava o package.json nem o lockfile. Alias npm clean-install.

Atualizar

Leva os pacotes às versões mais novas que seus ranges permitem. Aliases up e upgrade.

Atualizar

O mesmo, e grava as novas versões de volta no package.json.

Atualizar

Atualiza os pacotes globais para a tag latest.

Atualizar

Pula para a tag latest mesmo atravessando uma versão major.

Atualizar

Mostra Current, Wanted e Latest para cada dependência.

Remover

Remove um pacote e sua entrada no package.json e no lockfile. Aliases remove, rm, r, un e unlink.

Remover

Remove os arquivos, mas mantém a entrada no package.json.

Remover

Remove um pacote global.

Scripts

Lista todos os scripts do package.json.

Scripts

Roda o script dev, geralmente um servidor de desenvolvimento.

Scripts

Passa as flags depois de -- para o script em vez do npm.

Scripts

Não faz nada, sem falhar, quando o script não existe.

Scripts

Roda o script start; também funciona para test, stop e restart sem run.

Scripts

Roda pretest, test e posttest em ordem.

Scripts

Executa o binário de um pacote sem instalá-lo globalmente.

Segurança

Pergunta ao registry quais vulnerabilidades conhecidas existem na sua árvore de dependências.

Segurança

Aplica correções que ficam dentro dos ranges declarados.

Segurança

Permite correções fora dos seus ranges, incluindo versões major. Revise as mudanças.

Segurança

Sai com erro só para achados high ou critical, útil no CI.

Inspecionar

Mostra a árvore de dependências instalada.

Inspecionar

Lista as versões publicadas de um pacote.

Inspecionar

Mostra a pasta onde os pacotes globais são instalados.

Workspaces

Roda um script em um workspace (--workspace=a).

Workspaces

Roda um script em todos os workspaces.

Pesquisar comandos npm

Pesquisar comandos

save, global, lock, script

Filtrar por grupo

Todos

Comandos e flags do npm

Comando

Grupo

O que faz

{n} comandos exibidos

Nenhum comando corresponde a essa busca.

Copiar

Testador de ranges semver

Range

Versão

O range {r} se expande para {e}, então a versão {v} o satisfaz.

O range {r} se expande para {e}, então a versão {v} não o satisfaz.

Informe um range como ^1.2.3 e uma versão completa como 1.4.0.

Comece grátis · Sem cartão de crédito

Guia rápido de comandos npm