Changesets no Node.js

Changesets é uma ferramenta para administrar versões, changelogs e publicação de pacotes, com foco especial em monorepos. Em vez de decidir todas as versões somente no momento da release, cada pull request pode incluir um pequeno arquivo declarando quais pacotes mudaram, qual incremento semântico é necessário e um resumo legível da alteração.

Esses arquivos são acumulados até a próxima release. Depois, a ferramenta combina as intenções, calcula uma única versão por pacote, atualiza dependências internas, modifica os changelogs e prepara ou publica os pacotes afetados.

Instalação e inicialização

npm install -D @changesets/cli
npx changeset init

O comando cria a pasta .changeset e um arquivo config.json. Adicione scripts:

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

O que é um changeset

Um changeset é um arquivo Markdown com front matter:

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

Adiciona contexto estruturado aos logs e corrige o tratamento de timeout no cliente HTTP.

O nome do arquivo é gerado automaticamente. A parte superior lista pacotes e tipos de incremento; o texto vira entrada de changelog.

Criando um changeset

npx changeset

A interface pergunta quais pacotes mudaram, se o incremento é patch, minor ou major e qual resumo deve aparecer. O arquivo resultante deve ser commitado junto com o código.

O resumo deve explicar o efeito para consumidores. Evite textos como “ajustes diversos”. Prefira “adiciona suporte a timeout configurável” ou “remove o método legado createClient”.

Versionamento semântico

Use:

• patch para correções compatíveis;
• minor para funcionalidades compatíveis;
• major para mudanças incompatíveis.

Quando vários changesets atingem o mesmo pacote, a ferramenta combina os níveis. Um major prevalece sobre minor e patch.

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": []
}

baseBranch define a referência para status e automação. access controla o padrão de publicação. Para pacotes públicos com escopo, ajuste para public ou use publishConfig em cada pacote.

Aplicando versões

Quando chega a hora de preparar a release:

npm run version-packages

O comando consome os arquivos pendentes, atualiza versões, changelogs e intervalos de dependências internas. Revise o diff antes de publicar.

Publicando

npm run release

changeset publish identifica pacotes cuja versão ainda não existe no registry e os publica. A autenticação e o acesso continuam sendo responsabilidade do npm e do ambiente.

Changesets em npm Workspaces

Uma estrutura comum:

packages/
├── logger/
├── api-client/
└── config/
apps/
└── dashboard/

Pacotes com private: true não são publicados, mas podem participar do versionamento de aplicações conforme a estratégia do repositório.

Dependências internas

Se @empresa/api-client depende de @empresa/logger, uma nova versão do logger pode exigir atualização do intervalo no cliente. Changesets calcula esses ajustes conforme a configuração.

Teste o resultado com instalação limpa:

rm -rf node_modules
npm ci
npm test
npm run build --workspaces --if-present

Fixed packages

Pacotes fixos compartilham uma versão:

{
  "fixed": [
    [
      "@empresa/core",
      "@empresa/node",
      "@empresa/browser"
    ]
  ]
}

Quando um muda, todos recebem a mesma versão. Isso simplifica comunicação, mas aumenta releases sem alterações funcionais em alguns pacotes.

Linked packages

Pacotes linked mantêm alinhamento dentro de uma faixa, mas não precisam ser sempre publicados juntos. Use quando versões devem permanecer coordenadas sem a rigidez de fixed packages.

Pacotes ignorados

{
  "ignore": ["@empresa/exemplo-interno"]
}

Ignorar um pacote pode causar erro quando ele participa de dependências que precisam ser atualizadas. Use com cuidado; private: true costuma expressar melhor a intenção.

Verificando changesets no CI

npx changeset status --since=origin/main

O comando informa releases previstas. Um bot pode comentar no pull request quando falta changeset. Nem toda alteração exige release: documentação interna, testes e refatorações privadas podem usar uma convenção de “sem changeset”.

Pull request de versão

A GitHub Action oficial pode manter um pull request de release. Enquanto mudanças chegam, o PR é atualizado com versões e changelogs. Quando ele é mesclado, a action pode publicar os pacotes.

name: Release
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
  id-token: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - uses: changesets/action@v1
        with:
          publish: npm run release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Configure autenticação npm por OIDC ou token granular, conforme o registry e a ação usados.

Protegendo a release

A action de release tem permissão para alterar código e publicar pacotes. Proteja a branch, exija revisão, limite actions permitidas, fixe referências e use ambiente com aprovação quando necessário.

Pré-releases

Para entrar no modo de pré-release:

npx changeset pre enter beta
npm run version-packages
npm run release

Para sair:

npx changeset pre exit
npm run version-packages

Pré-releases permitem testar versões com tags como beta sem atualizar latest.

Snapshot releases

Snapshots geram versões temporárias para validação. São úteis quando um consumidor precisa instalar uma mudança antes da release oficial. Não trate snapshots como versões permanentes nem os use para substituir uma política de pré-release.

Changelog personalizado

O campo changelog pode apontar para um pacote próprio que inclui links de pull request, autores e issues. Mantenha o formato estável e evite chamadas externas frágeis durante o versionamento.

Aplicações não publicadas

Changesets também pode versionar aplicações, imagens ou outros artefatos, mas o comando publish é orientado ao npm. Para aplicações, use a saída de versão como entrada para tags Git, imagens OCI e notas de release.

Testando pacotes antes da publicação

Depois de changeset version:

npm ci
npm run typecheck --workspaces --if-present
npm test --workspaces --if-present
npm run build --workspaces --if-present
npm pack -w @empresa/logger --dry-run

Instale tarballs em um projeto temporário para validar exports e tipos.

Erros comuns

• esquecer changeset em uma mudança pública;
• usar patch para quebra de API;
• resumos vagos;
• publicar sem revisar o PR de versão;
• misturar mudanças manuais de versão com a ferramenta;
• não atualizar dependências internas;
• publicar pacote privado;
• usar token amplo e permanente.

Changesets ou versão única

Para um único pacote, Changesets ainda pode melhorar changelog e revisão, mas o benefício maior aparece em monorepos. Projetos pequenos podem preferir um fluxo simples com npm version. Avalie complexidade, número de pacotes e frequência de releases.

Fluxo recomendado

Crie changesets junto com o código, valide no CI, deixe a automação manter um PR de versão, revise changelogs, execute testes no estado versionado e publique com credenciais temporárias. Combine com npm Workspaces, Publicação de Pacotes npm, Exports e Imports e Segurança de Supply Chain.

Consulte o repositório oficial do Changesets e a GitHub Action oficial de Changesets.