# How to Use Codemods for Migrating Astryx Versions with `astryx upgrade` > Effortlessly migrate Astryx versions using astryx upgrade. This command leverages built-in codemods to automatically transform your source code, ensuring a smooth transition to the latest release. - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: how-to-guide - Published: 2026-08-05 --- **Run `npx astryx upgrade --from ` 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 ` or `--list`. The version string must conform to **Semantic Versioning**. ```bash # 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: ```html ``` ### 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. ```javascript // 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 ```bash npx astryx upgrade --list ``` This outputs all version transitions defined in the codemod registry without modifying any files. ### Upgrade From a Specific Version ```bash 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 ```bash 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 ```bash 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: ```javascript 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: ```json { "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 `** 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 `** to rerun the upgrade while excluding problematic transforms, then apply those changes manually or debug the transform against your specific codebase.