Publicação no npm e versionamento semântico

Antes de publicar, execute sempre npm publish --dry-run. Esse comando simula a publicação sem realmente enviar nada, mostrando exatamente quais arquivos seriam incluídos, seus tamanhos e o conteúdo do arquivo compactado do pacote. Ele detecta erros comuns, como incluir acidentalmente arquivos de código-fonte ou não incluir o diretório dist.

Controle o que será publicado usando o campo de arquivos no package.json: "files": ["dist", "README.md"]. Essa abordagem de lista de permissões é mais segura do que .npmignore, que funciona como uma lista de bloqueio e pode expor arquivos confidenciais se você esquecer de adicioná-los. Sempre inclua dist, declarações de tipos e documentação. Nunca inclua src, testes ou node_modules.

Os pacotes do npm seguem o versionamento semântico (semver): MAJOR.MINOR.PATCH. Incremente MAJOR para alterações incompatíveis (remover propriedades ou alterar assinaturas da API). Incremente MINOR para novos recursos compatíveis com versões anteriores (novos componentes ou novas propriedades opcionais). Incremente PATCH para correções de erros compatíveis com versões anteriores. A versão 0.x.x é considerada pré-estável, e qualquer alteração pode causar incompatibilidade.

Os identificadores de pré-lançamento indicam que uma versão ainda não está pronta para produção: 1.0.0-alpha.1 para versões experimentais iniciais, 1.0.0-beta.2 para versões com todos os recursos, mas que ainda podem conter erros, e 1.0.0-rc.1 (candidata a lançamento) para versões prontas para os testes finais. Publique versões de pré-lançamento com npm publish --tag beta para que elas não se tornem a instalação padrão.

Changesets é a ferramenta padrão para gerenciar o versionamento de pacotes e os registros de alterações em bibliotecas de componentes. Fluxo de trabalho: os colaboradores executam yarn changeset add para registrar o que mudou e o tipo de alteração (major/minor/patch). A integração contínua executa yarn changeset version para atualizar as versões dos pacotes. A publicação executa yarn changeset publish para enviá-los ao npm.

Changesets gera e mantém automaticamente o CHANGELOG.md com base nos arquivos de alterações enviados pelos colaboradores. Cada entrada inclui o número da versão, a data de lançamento e as descrições das alterações. Isso cria um histórico legível de cada versão sem exigir a manutenção manual do registro de alterações.

semantic-release é uma ferramenta totalmente automatizada de versionamento que determina a próxima versão a partir de mensagens de commit convencionais (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Ela atualiza a versão, gera o registro de alterações e publica no npm — tudo acionado pela integração contínua ao mesclar na ramificação principal. Não é necessário gerenciar versões manualmente.

Pacotes sem escopo (my-component) são sempre públicos. Pacotes com escopo (@myorg/my-component) são restritos (privados) por padrão — publique-os como públicos com npm publish --access public. Pacotes restritos exigem uma conta paga do npm ou uma organização. Confirme as configurações de acesso antes da primeira publicação.

A proveniência do npm vincula seu pacote publicado ao commit específico do git de forma verificável. Ative-a com npm publish --provenance no GitHub Actions. Os consumidores podem verificar se o pacote instalado foi criado a partir do commit exato do código-fonte mostrado na página do registro do npm. Isso melhora significativamente a segurança da cadeia de fornecimento.

Quando uma versão apresenta um erro crítico ou uma alteração incompatível, marque-a como obsoleta: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". O npm exibe um aviso de obsolescência para qualquer pessoa que instale essa versão. Isso não remove a versão — por padrão, o npm não exclui versões publicadas —, mas alerta os usuários para atualizarem.

Pacotes com escopo usam o formato @scope/package-name. O escopo normalmente é seu nome de usuário no npm ou o nome da sua organização. Pacotes com escopo deixam claro quem mantém o pacote e evitam conflitos de nomes com pacotes sem escopo. Use pacotes com escopo para pacotes privados e para pacotes de código aberto associados à sua organização.

De acordo com o versionamento semântico, quando você deve incrementar o número da versão MAJOR?

Use npm publish --dry-run para visualizar a publicação e o campo de arquivos para controlar o que será publicado. No versionamento semântico, MAJOR indica alterações incompatíveis, MINOR indica novos recursos e PATCH indica correções. Versões de pré-lançamento usam os identificadores -alpha/-beta/-rc. Changesets automatiza o versionamento e a geração do CHANGELOG para bibliotecas colaborativas. semantic-release automatiza o processo a partir de commits convencionais. Ative --provenance para aumentar a segurança da cadeia de fornecimento. Marque versões com erros como obsoletas usando npm deprecate.