How to Use Codemods for Migrating Astryx Versions with `astryx upgrade`

Run npx astryx upgrade --from <old-version> to automatically migrate your Astryx project using built‑in codemods that transform your source code from any previous release to the currently installed version.

The Astryx CLI provides a complete upgrade pipeline for the Astryx design system (from facebook/astryx). Instead of manually fixing breaking changes, you can use codemods—automated code transformation scripts—to update imports, component APIs, and prop names across your entire codebase. This guide explains how the astryx upgrade command works and how to customize its behavior.

Understanding the Astryx Upgrade Pipeline

When you invoke astryx upgrade, the CLI executes a nine‑step pipeline defined across packages/cli/api/upgrade/upgrade.mjs and packages/cli/api/upgrade/_adapter.mjs. Each step handles a specific aspect of the migration process.

Step 1: Validate the Invocation

The entry point in packages/cli/api/upgrade/upgrade.mjs (lines 47‑58) enforces that you provide either --from <version> or --list. The version string must conform to Semantic Versioning.

# Invalid: missing --from

npx astryx upgrade

# Error: --from is required when not using --list

# Valid

npx astryx upgrade --from 0.0.5

Step 2: Detect the Installed Target Version

The detectInstalledTargetVersion function in _adapter.mjs (lines 60‑80) reads your node_modules to determine the installed version of @astryxdesign/core (or the legacy @xds/core). This becomes the migration target—you do not specify it manually.

Step 3: Refresh the Agent‑Docs Block

Every Astryx release includes a machine‑readable documentation block used by AI agents. The refreshAgentDocs function (lines 42‑100 in _adapter.mjs) synchronizes this block even when no codemods run. Look for these comments in your files:

<!-- ASTRYX:START -->
<!-- Component index for AI agents -->
<!-- ASTRYX:END -->

Step 4: Collect Applicable Core Codemods

The registry at packages/cli/assets/codemods/registry.mjs maps each Astryx version to its associated transforms. The collectAllCodemods and getCoreVersionManifests functions (lines 12‑28 and 30‑40 in _adapter.mjs) load transforms for the version range (from, to].

Step 5: Run Core Codemods

The runCoreCodemods function (lines 57‑65 in _adapter.mjs) invokes JSCodeshift through packages/cli/assets/codemods/runner.mjs to apply transforms to your source files.

Step 6: Load Project Configuration and Integrations

The loadProjectContext function (lines 74‑84 in _adapter.mjs) reads:

• astryx.config.* files
• Integration manifests that may contribute additional codemods

Step 7: Select and Run Integration Codemods

Third‑party integrations can expose their own migration scripts. The selectIntegrationCodemodsFor and runIntegrationCodemodsStep functions (lines 9‑30 and 31‑47 in _adapter.mjs) discover, filter, and execute these after core codemods complete.

Step 8: Execute Post‑Codemod Hooks

Projects define custom commands in astryx.config.mjs under hooks.postCodemod. The runPostCodemodHooks function (lines 99‑140 in _adapter.mjs) runs these after file modifications—commonly for formatting or lint fixes.

// astryx.config.mjs
export default {
  hooks: {
    postCodemod: ['prettier --write', 'eslint --fix .']
  }
};

Step 9: Return a Typed Receipt

The CLI emits a structured JSON envelope with type upgrade.run, upgrade.status, or upgrade.list, containing applied transforms, errors, and changed files.

Running astryx upgrade: Command Examples

List Available Migrations Without Making Changes

npx astryx upgrade --list

This outputs all version transitions defined in the codemod registry without modifying any files.

Upgrade From a Specific Version

npx astryx upgrade --from 0.0.5

The CLI detects the installed target version automatically and applies all codemods in the range.

Apply a Specific Codemod Only

npx astryx upgrade --from 0.0.8 --codemod rename-date-picker-to-input

Use this to run a single transform when you need precise control.

Skip a Problematic Codemod

npx astryx upgrade --from 0.0.10 --skip-codemod drop-xds-prefix-imports

Skip transforms that fail on your codebase; you can apply them manually later.

Programmatic API Usage

Import upgrade() from @astryxdesign/cli/api for scripted migrations:

import {upgrade} from '@astryxdesign/cli/api';

const result = await upgrade({from: '0.0.8'});
console.log(result.data.transformsApplied);

The function returns an UpgradeRunResponse with full details about the migration.

Understanding the Upgrade Receipt

The JSON response from astryx upgrade follows this structure:

{
  "type": "upgrade.run",
  "data": {
    "installedVersion": "0.0.14",
    "fromVersion": "0.0.8",
    "transformsApplied": [
      {"name": "rename-date-picker-to-input", "version": "0.0.9"},
      {"name": "drop-xds-prefix-imports", "version": "0.0.9"}
    ],
    "filesChanged": [
      "src/components/DatePicker.tsx",
      "src/pages/home.tsx"
    ],
    "postCodemodHooks": ["prettier --write"]
  }
}

Check result.data.transformsApplied.length to verify that expected migrations ran.

Key Source Files Reference

File	Purpose
packages/cli/api/upgrade/upgrade.mjs	Top‑level dispatcher; validates arguments and routes to list/run modes
packages/cli/api/upgrade/_adapter.mjs	Core engine: version detection, codemod selection, agent‑docs refresh, integration handling
packages/cli/assets/codemods/registry.mjs	Manifest of core transforms keyed by target version
packages/cli/assets/codemods/runner.mjs	JSCodeshift execution for core transforms
packages/cli/assets/codemods/integration-discovery.mjs	Discovers third‑party integration codemods
packages/cli/assets/codemods/integration-runner.mjs	Executes integration‑provided transforms

Summary

• astryx upgrade --from <version> runs automated codemods to migrate your Astryx project forward.
• The pipeline validates input, detects installed versions, refreshes AI agent documentation, and executes core plus integration codemods.
• Use --list to preview migrations, --codemod to run specific transforms, and --skip-codemod to bypass failures.
• Configure hooks.postCodemod in astryx.config.mjs to run formatting or lint commands after migration.
• The typed JSON receipt reports all applied transforms and changed files for audit purposes.

Frequently Asked Questions

What is an Astryx codemod?

A codemod is a file‑based transformation script written for JSCodeshift. In Astryx, codemods update import paths, rename components, migrate prop names, and handle other breaking changes between versions. They are stored in packages/cli/assets/codemods/ and registered by target version in registry.mjs.

Why does astryx upgrade require the --from flag?

The --from flag specifies your project's current Astryx version, which the CLI uses to calculate the range of transforms needed. The target version is detected automatically from your node_modules. Without --from, the CLI cannot determine which migrations are applicable.

Can I run custom codemods through astryx upgrade?

Integration codemods from third‑party packages are automatically discovered and executed. For fully custom transforms, add them as an integration package with a proper manifest, or run JSCodeshift directly on your source files after the core upgrade completes.

What happens if a codemod fails during upgrade?

Failed transforms are reported in the JSON receipt with error details. Use --skip-codemod <name> to rerun the upgrade while excluding problematic transforms, then apply those changes manually or debug the transform against your specific codebase.

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