# How Astryx Handles Component Versioning: Changesets, Fixed Groups, and Automated Codemods

> Discover how Astryx manages component versioning with Changesets and fixed groups. Learn about automated codemods for easy, synchronized package upgrades in the facebook/astryx repository.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: deep-dive
- Published: 2026-07-15

---

**Astryx uses a Changesets-based fixed-group strategy that bumps all `@astryxdesign/*` packages to identical versions simultaneously, ensuring dependency alignment while providing automated codemods for seamless upgrades.**

The Astryx design system—maintained in the `facebook/astryx` repository—manages its component library through a deterministic versioning pipeline built atop Changesets. This architecture guarantees that core components, themes, and experimental packages remain synchronized, eliminating peer-dependency mismatches and simplifying consumer upgrade paths.

## Changesets Integration and Configuration

Astryx stores its versioning configuration in [`.changeset/config.json`](https://github.com/facebook/astryx/blob/main/.changeset/config.json), which defines a **fixed group** containing every publishable package under the `@astryxdesign/*` namespace.

When contributors introduce changes, they run `pnpm changeset` to generate a markdown file describing the impact (patch, minor, or major). According to the [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) guidelines, the repository uses a custom wrapper script rather than invoking Changesets directly.

The `pnpm version-packages` command executes `changeset version && scripts/format-changelogs.mjs`. This workflow:

- Updates all [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) version fields locally
- Rewrites each package’s [`CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/CHANGELOG.md) into the doc-site format
- Requires no npm authentication, operating completely offline

## Fixed-Group Co-Versioning Strategy

The `fixed` array in [`.changeset/config.json`](https://github.com/facebook/astryx/blob/main/.changeset/config.json) lists every publishable package—including `@astryxdesign/core`, `@astryxdesign/lab`, and `@astryxdesign/theme-*` packages. When a changeset is applied, **all** packages in this array receive the same version number.

As documented in [`packages/vega/README.md`](https://github.com/facebook/astryx/blob/main/packages/vega/README.md), this approach ensures that even packages unaffected by a specific change receive a "clean" bump. The result is a consistent workspace dependency graph where `workspace:*` and `catalog:` references resolve predictably across the entire monorepo.

## Publishing Pipeline and OIDC Trust

After local versioning completes, the release process shifts to a trusted-publish OIDC workflow documented in [`docs/release.md`](https://github.com/facebook/astryx/blob/main/docs/release.md).

The command `pnpm -r publish` executes the following sequence:

1. Resolves `workspace:*` and `catalog:` references to the newly bumped versions
2. Publishes packages in dependency order (respecting the monorepo graph)
3. Skips already-published versions, making the operation idempotent

This tokenless publishing mechanism leverages OIDC authentication, removing the need for long-lived npm credentials in CI environments.

## Automated Migration with Codemods

Astryx provides an `astryx upgrade` CLI command that automates breaking-change migrations. As implemented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md), this command:

- Reads the current `@astryxdesign/core` version from the consumer's workspace
- Determines the required transform chain between the current and target versions
- Applies codemods automatically to migrate code between releases

This ensures that breaking API changes in component packages are accompanied by executable migration paths, reducing manual upgrade effort.

## Canary Releases for Experimental Packages

Experimental packages like `@astryxdesign/vega` and `@astryxdesign/lab` publish under the `@canary` dist-tag rather than the default `latest` tag. These versions follow the pattern `0.x.y-canary.<sha>`, allowing consumers to install specific commits or track the latest development build.

To install a canary release:

```bash
pnpm add @astryxdesign/vega@canary

```

The installed version resolves to something like `0.2.0-canary.abcdef12`, providing stability for production use while enabling testing of prerelease features.

## Working with the Versioning Workflow

### Adding a Changeset

When modifying components, contributors generate changesets through the CLI:

```bash

# Generate the changeset file

pnpm changeset

# Select semver bump type and describe changes

# Creates .changeset/<timestamp>-<name>.md

# Bump versions locally (no network required)

pnpm version-packages

```

### Publishing Packages

After versioning commits merge to the release branch:

```bash

# Publishes all packages in dependency order

pnpm -r publish

```

### Upgrading Consumer Projects

When Astryx releases a new version, consumers migrate automatically:

```bash
npx astryx upgrade

```

This detects the project's current `@astryxdesign/core` version and runs the appropriate codemods to reach the latest release.

## Summary

- **Fixed-group versioning** ensures all `@astryxdesign/*` packages share identical version numbers, preventing dependency drift.
- **Changesets integration** in [`.changeset/config.json`](https://github.com/facebook/astryx/blob/main/.changeset/config.json) drives the versioning process through `pnpm version-packages`, which combines `changeset version` with custom changelog formatting via `scripts/format-changelogs.mjs`.
- **OIDC-based publishing** via `pnpm -r publish` executes tokenless, idempotent releases that respect workspace dependency ordering.
- **Automated codemods** through the `astryx upgrade` CLI command provide deterministic migration paths across breaking changes.
- **Canary releases** for experimental packages use the `@canary` dist-tag with `0.x.y-canary.<sha>` versioning to enable prerelease testing without destabilizing production workflows.

## Frequently Asked Questions

### What is a "fixed group" in Changesets?

A fixed group is a Changesets configuration where all listed packages receive identical version bumps regardless of which packages actually changed. In `facebook/astryx`, the [`.changeset/config.json`](https://github.com/facebook/astryx/blob/main/.changeset/config.json) defines a fixed array containing every `@astryxdesign/*` package, ensuring that core components, themes, and labs move in lockstep to maintain dependency consistency.

### How do I publish a new version of Astryx components?

Run `pnpm version-packages` locally to bump versions and format changelogs, then commit the changes. Once merged, the CI pipeline executes `pnpm -r publish` using OIDC authentication, which publishes packages in dependency order and skips any versions already present on the registry.

### What happens if a changeset only affects one package?

Even when a changeset affects only one package—such as `@astryxdesign/core`—the fixed-group configuration bumps **every** package in the group to the same new version. Unaffected packages receive a version increment without changelog entries, ensuring that `workspace:*` references remain resolvable across the monorepo.

### How do canary releases differ from stable releases?

Canary releases publish experimental packages under the `@canary` dist-tag with versions formatted as `0.x.y-canary.<sha>`, whereas stable releases use standard semantic versioning under the `latest` tag. Consumers can pin exact canary versions for stability or use the tag to track the newest development build of packages like `@astryxdesign/vega`.