Changesets no Node.js

Changesets no Node.js organiza versões e changelogs de pacotes, especialmente em monorepos. Em vez de decidir tudo no momento do release, a pessoa que cria uma alteração adiciona um pequeno arquivo Markdown informando quais pacotes mudaram, se o impacto é patch, minor ou major e qual texto deve aparecer no changelog.

Quando uma release é preparada, a ferramenta consome esses arquivos, atualiza versões, dependências internas e changelogs. Depois, publica somente pacotes cuja versão é maior que a registrada no npm. O fluxo separa a decisão sobre impacto da execução da publicação.

Neste guia, você aprenderá a instalar Changesets, criar arquivos, configurar monorepo npm Workspaces, preparar versões, publicar, usar pré-releases, fixed groups, linked groups e GitHub Actions.

O que é um changeset?

Um changeset guarda duas informações principais:

• tipo de versão SemVer para cada pacote afetado;
• descrição que será adicionada ao changelog.

O guia oficial Using Changesets descreve o ciclo: adicionar changesets com as mudanças, executar version quando uma release estiver pronta e executar publish depois.

Instalação

npm install --save-dev @changesets/cli
npx changeset init

A inicialização cria:

.changeset/
├── config.json
└── README.md

Scripts

{
  "scripts": {
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "changeset publish"
  }
}

Consulte npm Scripts no Node.js.

Criando um changeset

npm run changeset

A CLI pergunta:

• quais pacotes mudaram;
• quais são major;
• quais são minor;
• quais são patch;
• qual resumo deve entrar no changelog.

O resultado:

---
"@empresa/domain": minor
"@empresa/api-client": patch
---

Adiciona suporte a cancelamento de pedidos.

Comitando o arquivo

O changeset deve entrar no mesmo pull request da alteração. Assim, revisão de código também revisa:

• pacotes afetados;
• classificação SemVer;
• texto de release;
• dependências internas impactadas.

Nem toda mudança precisa

Documentação interna, configuração de CI e refactors sem impacto publicado podem não exigir changeset. O projeto oficial recomenda não bloquear toda contribuição apenas pela ausência do arquivo.

Defina uma política clara, por exemplo:

• pacote publicável alterado: obrigatório;
• aplicação privada: opcional;
• documentação sem release: dispensado;
• chore de tooling: dispensado;
• breaking change: obrigatório e revisado.

Preparando versões

npm run version-packages

O comando:

• consome changesets pendentes;
• calcula a maior mudança necessária;
• atualiza versões;
• atualiza ranges internos quando necessário;
• escreve changelogs;
• remove os arquivos consumidos.

Revise o diff antes de publicar.

Publicação

npm run release

changeset publish verifica versões no registry e publica pacotes com versão nova. Ele não decide o bump; essa etapa já aconteceu em changeset version.

Veja Publicar Pacote no npm para autenticação, npm pack e provenance.

Configuração básica

{
  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Fixe a versão compatível e consulte o schema atual da ferramenta.

access

Para pacotes públicos scoped:

{
  "access": "public"
}

Confirme também publishConfig.access nos pacotes.

baseBranch

{
  "baseBranch": "main"
}

A ferramenta usa a branch para comparar mudanças e integrações.

Dependências internas

Imagine:

• @empresa/api depende de @empresa/domain;
• domain recebe uma versão major;
• api precisa de range atualizado.

Changesets calcula bumps necessários conforme configuração e ranges. Revise consumidores quando a alteração é breaking.

npm Workspaces

Na raiz:

{
  "private": true,
  "workspaces": ["packages/*"]
}

Cada pacote publicável possui nome, versão, exports e files. Veja npm Workspaces no Node.js.

Fixed groups

Pacotes em um grupo fixed sempre compartilham a mesma versão:

{
  "fixed": [
    ["@empresa/core", "@empresa/react", "@empresa/vue"]
  ]
}

Se um recebe minor, todos sobem para a mesma versão adequada. Use quando componentes são lançados como conjunto.

Linked groups

{
  "linked": [
    ["@empresa/plugin-a", "@empresa/plugin-b"]
  ]
}

Linked mantém versões alinhadas conforme regras da ferramenta, mas permite comportamento diferente de fixed. Avalie com exemplos reais antes de aplicar.

Ignore

{
  "ignore": ["@empresa/docs"]
}

Ignorar pacote pode causar erro quando um pacote publicável depende dele ou quando mudanças cruzam limites. Prefira private: true para aplicações não publicáveis.

Changelog personalizado

O campo changelog pode apontar para módulo que inclui autores, links de PR e commits. Não dependa de serviços externos sem lidar com falhas e rate limits.

Pré-releases

npx changeset pre enter next
npx changeset version
npm run release

As versões recebem identificador, como 2.0.0-next.0. Ao finalizar:

npx changeset pre exit
npx changeset version

Publique com dist-tag adequada e nunca mova latest para uma beta por engano.

Snapshot releases

Versões snapshot permitem testar builds de uma branch sem consumir changesets como release estável. A disponibilidade e sintaxe dependem da versão do CLI. Use tag dedicada e política de limpeza.

Semantic Versioning

A pessoa que cria o changeset precisa classificar corretamente:

• patch: correção compatível;
• minor: funcionalidade compatível;
• major: breaking change.

Veja Semantic Versioning no Node.js.

GitHub Action

A action oficial pode manter um pull request de versão. Quando changesets chegam à main, o bot atualiza um PR com versões e changelogs. Ao fazer merge ou acionar publicação, os pacotes são lançados.

Workflow conceitual:

permissions:
  contents: write
  pull-requests: write
  id-token: write

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      cache: npm
  - run: npm ci
  - run: npm run check
  - uses: changesets/action@v1
    with:
      publish: npm run release

Fixe actions por SHA em ambientes com exigência elevada e use OIDC para npm quando suportado.

Release PR

O pull request de versão concentra:

• package.json atualizados;
• lockfile;
• changelogs;
• changesets consumidos.

Revise a classificação antes do merge. A automação reproduz decisões; não detecta sozinha que uma mudança foi breaking.

CI de changeset

Uma verificação pode avisar quando pacotes mudaram sem changeset. Permita label ou comando para casos dispensados, evitando arquivos vazios só para satisfazer o bot.

Testando tarballs

Antes de publicar:

npm pack -w @empresa/domain --dry-run

Instale o tarball em consumidor temporário. Confirme exports, tipos e dependências.

Publicação parcial

Se um pacote falha após outros serem publicados, não é possível reverter o registry. Corrija a causa, incremente versões afetadas e publique novamente. Use staging quando revisão humana é necessária.

Changelogs úteis

Escreva para consumidores:

Adiciona `createOrder(input, { signal })` para permitir cancelamento com AbortSignal.

Evite:

Refatora service.

Informe impacto, API e migração.

Erros comuns

• Changeset genérico: changelog não ajuda.
• Bump errado: breaking sai como minor.
• Toda mudança obrigatória: gera ruído.
• Ignorar dependência interna: ranges quebram.
• Publicar sem revisar version: versões inesperadas.
• Token permanente: risco de supply chain.
• Latest em pré-release: consumidores recebem beta.
• Pacote private sem marcação: tentativa de publicação.

Fluxo recomendado

1. Desenvolvedor altera pacote.
2. Executa changeset.
3. PR revisa código e impacto.
4. Main acumula changesets.
5. Action atualiza release PR.
6. Equipe revisa versões e changelogs.
7. CI testa tarballs.
8. Merge aciona publicação segura.
9. Release e tags são criadas.
10. Erros são monitorados.

Conclusão

Changesets no Node.js leva a decisão de versão para o momento em que a mudança é criada. Arquivos pequenos registram pacote, impacto SemVer e texto de changelog, tornando releases de monorepos mais previsíveis.

Use release PR, revise versões, teste tarballs e publique com OIDC ou staging. A ferramenta automatiza cálculo e changelog, enquanto a equipe mantém responsabilidade sobre compatibilidade e qualidade da comunicação.