Changesets

Qué es

Changesets es una herramienta open source (CLI) para gestionar el versionado y los changelogs de paquetes, pensada especialmente para monorepos. Quien hace un cambio declara su intención en un fichero “changeset” indicando qué paquetes se ven afectados y con qué tipo de salto de versión (semver: patch, minor o major). A partir de esas declaraciones, la herramienta calcula las versiones, actualiza los changelogs y prepara la publicación. Está escrita en TypeScript y se distribuye como el paquete @changesets/cli.

Para qué sirve

• Declarar de forma explícita, en cada pull request, qué cambios deben publicarse y con qué tipo de versión.
• Calcular automáticamente los saltos de versión semver de uno o varios paquetes a la vez.
• Generar y mantener los changelogs a partir de las descripciones escritas por quien contribuye.
• Coordinar el versionado de dependencias internas dentro de un monorepo para que los paquetes interconectados queden sincronizados.

Cuándo usarlo

• Cuando mantienes un monorepo con varios paquetes publicables (por ejemplo con pnpm, Yarn o npm workspaces) y necesitas versionarlos de forma coherente.
• Cuando quieres separar el acto de “decidir el cambio de versión” (en cada PR) del acto de “publicar” (en CI), evitando errores manuales.
• Si buscas una alternativa más orientada a monorepos que semantic-release, integrándose bien con GitHub Actions para automatizar releases.

Ejemplo

Instalación y flujo básico:

npm install @changesets/cli
npx changeset init

# Tras hacer cambios, declara un changeset (modo interactivo):
npx changeset

# Aplica las versiones y actualiza changelogs:
npx changeset version

# Publica los paquetes:
npx changeset publish

El comando changeset status permite comprobar en CI si un pull request incluye changesets pendientes.

Puntos clave

• Diseño orientado a monorepos: maneja dependencias internas entre paquetes y mantiene las versiones sincronizadas.
• Separa la declaración del cambio (en el PR) de la publicación (en CI), lo que reduce errores.
• Genera changelogs a partir de descripciones escritas por humanos, no solo de mensajes de commit.
• Se integra con GitHub Actions y otros sistemas de CI para automatizar el flujo de release.

Ten en cuenta

Licencia MIT y proyecto activo: la rama principal corresponde al desarrollo de la v3 y el código de la v2 vive en la rama maintenance/v2. El modelo se basa en que cada contribución declare su changeset, así que requiere disciplina en el equipo para que el flujo funcione. Para repositorios de un solo paquete puede resultar más pesado que herramientas más simples; su valor aparece sobre todo en escenarios de monorepo.