Versão Semântica O Que os Números no Seu package.json Significam de Fato

Todo projeto JavaScript tem um package.json. A maioria dos desenvolvedores já digitou npm install some-library centenas de vezes sem dar uma segunda olhada para a string de versão. Mas se perguntar a alguém o que ^1.2.3 realmente permite — ou seja, quais versões o npm irá agradavelmente incluir — você geralmente receberá um gesto de desinteresse.

Isso não é uma lacuna trivial. Uma faixa de versão mal interpretada é o que faz uma rotina npm install em uma máquina recém-instalada quebrar um pipeline de CI que funcionava perfeitamente por meses. Entender o contrato por trás desses números é uma das coisas de baixo esforço e alto retorno que separa desenvolvedores que resolvem problemas de versão em minutos dos que gastam horas com isso.

O Contrato MAJOR.MINOR.PATCH

A versão semântica (semver) é um formato de três números: MAJOR.MINOR.PATCH. Cada posição carrega uma promessa específica sobre o que mudou:

• MAJOR — mudanças que quebram. Uma atualização entre versões maiores pode exigir que você atualize seu código.
• MINOR — novas funcionalidades, compatíveis para versões anteriores. Seu código existente deve continuar funcionando.
• PATCH — correções de bugs apenas. Seguro para atualização; sem mudanças na API.

É esse o contrato que os pacotes publicam. Ir de 2.3.1 para 2.4.0 deve adicionar novas funcionalidades sem quebrar o comportamento existente. Ir para 3.0.0 é sua advertência: leia o histórico de mudanças antes de atualizar.

Na prática, os mantenedores às vezes cometem erros e introduzem mudanças que quebram em uma atualização de versão menor. O semver não é obrigatório — é uma convenção. Mas oferece um quadro para raciocinar sobre riscos, e é sobre isso que todos os operadores de faixa são construídos.

O que Conta como uma Mudança que Quebra?

Uma mudança que quebra é qualquer coisa que obriga os consumidores a atualizarem seu código:

• Remoção ou renomeação de uma função, classe ou constante exportada
• Mudança na assinatura de uma função — remoção de parâmetros, adição de parâmetros obrigatórios ou mudança nos tipos de retorno
• Mudança no comportamento observável de forma que o código chamador agora se comporte incorretamente
• Mudança no formato de um arquivo de configuração de forma incompatível

Adicionar um novo parâmetro opcional? Isso é MINOR. Adicionar uma nova exportação? MINOR. Corrigir um bug que alguém estava usando acidentalmente como uma funcionalidade? Isso é uma decisão de julgamento, mas convencionalmente PATCH. Quando houver dúvida, aumente o MINOR e documente claramente.

Operadores de Faixa em package.json

Abra qualquer package.json e você verá strings de versão como "^4.17.21" ou "~1.0.4". Essas não são pinos exatos — são faixas que indicam ao npm ou ao yarn quais versões são aceitáveis ao resolver sua árvore de dependências.

Caret ^ — Compatível com Versão

O caret é o operador padrão quando você executa npm install. Isso significa: "aceite qualquer versão que não mude o dígito não-zero mais à esquerda". Na prática, para pacotes estáveis, isso significa mesma versão principal, qualquer versão secundária ou de patch:

^1.2.3  →  >=1.2.3 <2.0.0   (any 1.x.x at or above 1.2.3)
^0.2.3  →  >=0.2.3 <0.3.0   (zero-major: pins to minor)
^0.0.3  →  >=0.0.3 <0.0.4   (zero-zero: pins to exact patch)

O comportamento com versão zero é intencional. Pacotes em 0.x.x indicam uma "API instável" — qualquer versão secundária pode quebrar coisas. O caret respeita esse sinal e se torna muito mais conservador.

Tilde ~ — Atualizações apenas no Nível de Patch

O tilde é mais conservador. Aceita novos patches, mas não toca na versão secundária:

~1.2.3  →  >=1.2.3 <1.3.0   (any 1.2.x at or above 1.2.3)
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0   (when only major given — same as ^1)

Use ~ quando quiser correções de bugs, mas estiver incerto se a biblioteca respeita o semver para atualizações de versão secundária, ou quando seu código estiver fortemente acoplado a uma superfície específica de API e uma nova versão com funcionalidade histórica traga mudanças sutis de comportamento.

Operadores de Comparação: >=, <=, >

Você pode escrever faixas arbitrárias usando operadores de comparação. Um espaço entre duas restrições significa AND:

>=1.2.0           # at least 1.2.0, no upper bound
>=1.2.0 <2.0.0   # same as ^1.2.0 (explicit AND)
>1.2.0 <=1.5.0   # between these values, exclusive/inclusive

Essas aparecem mais comumente em peerDependencies, onde uma biblioteca diz algo como "react": ">=16.8.0 <19.0.0" para declarar quais versões de host são compatíveis.

Wildcards: * e x

As formas de wildcard são principalmente para legibilidade em documentação; o npm as trata como equivalentes ao caret/tilde com base zero:

• * ou "" — qualquer versão. Não use isso em produção.
• 1.x ou 1.x.x — qualquer 1.x.x (igual a ^1.0.0)
• 1.2.x — qualquer 1.2.x (igual a ~1.2.0)

Versões Pré-Lançamento

Versões pré-lançamento parecem com 1.0.0-alpha.1, 2.0.0-beta.3, ou 3.1.0-rc.1. Elas são consideradas menores do que a versão de lançamento com os mesmos números — 1.0.0-alpha.1 < 1.0.0.

Crucialmente, os operadores de faixa não incluem automaticamente versões pré-lançamento. Uma faixa ^1.0.0 não irá incluir 1.1.0-beta.1, mesmo que tecnicamente satisfaça >=1.0.0 <2.0.0. Você precisa optar explicitamente:

npm install some-library@next
npm install some-library@2.0.0-beta.3

Isso é uma segurança intencional. Você raramente quer que o CI pegue silenciosamente uma -alpha versão de um pacote de dependência porque ela tecnicamente satisfaz uma faixa de versão. Se você estiver testando versões pré-lançamento, faça isso deliberadamente.

Arquivos de bloqueio não são opcionais

Quando o npm resolve sua ^1.2.3 faixa, ele escolhe a versão mais compatível disponível no momento. Execute npm install hoje e você obtém 1.5.0. Execute novamente seis meses depois e você pode obter 1.9.2. Mesma package.json, árvore de dependências diferente, comportamento potencialmente diferente.

Isso é o que os arquivos de bloqueio resolvem. package-lock.json (npm) e yarn.lock (yarn) registram a versão exata instalada para cada dependência — direta e transitiva. Quando alguém clona seu repositório e executa npm ci, eles obtêm uma árvore idêntica.

Comita seu arquivo de bloqueio. Sempre. Não comitar isso significa:

• Diferentes desenvolvedores podem executar versões diferentes de dependência sem saber
• Seu ambiente de CI pode se desviar silenciosamente do seu ambiente local
• Uma atualização de dependência transitiva pode mudar o comportamento em produção sem mudança visível em seu git diff

A principal exceção: bibliotecas publicadas (não aplicações) convencionalmente deixam arquivos de bloqueio não comitados para que os consumidores possam resolver sua própria árvore de dependência. Se você está construindo um aplicativo, não há boa razão para deixar o arquivo de bloqueio fora do controle de fonte.

"latest" em package.json É Sempre um Erro

Ocassionalmente você verá isso em um package.json:

"dependencies": {
  "some-package": "latest"
}

Não faça isso. "latest" mapeia para a versão atualmente marcada latest no npm — muda sempre que o mantenedor publica uma nova versão. Uma nova npm install em qualquer máquina nova pode puxar uma versão principal completamente diferente daquela que você testou.

Pode funcionar bem por semanas, mas quebrar silenciosamente quando a biblioteca publicar uma nova versão principal. Pior, torna package.json inútil como um especificador reprodutível — você não pode raciocinar sobre qual versão está rodando sem verificar manualmente o npm. Fixe uma versão real e deixe o caret lidar com atualizações seguras dentro dessa faixa.

Verifique se uma Versão Satisfaz uma Faixa

Se você não estiver certo se uma versão corresponde a uma dada faixa — especialmente com pacotes de versão zero ou expressões compostas estranhas — o Calculadora de Versão Semver e Testador de Intervalo no iotools.cloud dá uma resposta imediata. Insira a faixa (^1.2.3, ~0.5.0, >=2.0.0 <3.0.0) e a versão candidata, e ele diz se a restrição é satisfeita.

Isso é útil ao revisar solicitações de atualização de dependência, depurar por que npm install resolveu para uma versão inesperada, ou verificar uma peerDependencies faixa antes de publicar uma biblioteca.

Referência Rápida

Operador	Exemplo	Resolve para
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	1.2.0 ou superior, sem limite
*	*	Qualquer versão (evite)
x	1.2.x	Qualquer 1.2.x patch
exata	1.2.3	Exatamente 1.2.3

Você também pode gostar