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

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, 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 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 version fields locally
• Rewrites each package’s 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 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, 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.

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, 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:

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:

# 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:

# Publishes all packages in dependency order

pnpm -r publish

Upgrading Consumer Projects

When Astryx releases a new version, consumers migrate automatically:

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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}