# Complete List of Astryx Upgrade Codemods for Version Migration

> Explore over 42 Astryx upgrade codemods for seamless version migration. Automatically update React APIs, design tokens, and imports with jscodeshift transforms.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: api-reference
- Published: 2026-08-04

---

**The `astryx upgrade` command provides 42+ codemods organized by release version, from v0.0.2 through v0.3.0, that automatically migrate React component APIs, design tokens, and import paths using jscodeshift transforms.**

The Astryx design system by Meta (formerly XDS) ships with a built-in CLI migration tool that eliminates manual refactoring across breaking changes. Each codemod targets a specific API shift—from prop renames to component replacements—and executes in deterministic order based on your current `@astryxdesign/core` version.

## How the Astryx Upgrade Command Works

The upgrade system lives in `packages/cli/assets/codemods/` and operates through three coordinated layers:

1. **Registry** (`registry.mjs`): Maps version ranges to codemod sets
2. **Transforms** (`transforms/<version>/*.mjs`): Individual jscodeshift files
3. **Runner** (`runner.mjs`): Executes transforms, handles dry-runs, and runs post-processing hooks

When you invoke `npx astryx upgrade`, the CLI:

- Detects installed version via [`package.json`](https://github.com/facebook/astryx/blob/main/package.json)
- Queries the registry for applicable transforms
- Runs codemods sequentially with optional Prettier/ESLint cleanup

```bash

# Apply all codemods for your version range

npx astryx upgrade --apply

# Preview changes without writing files

npx astryx upgrade --dry-run

# Run a single specific codemod

npx astryx upgrade --codemod migrate-table-tableprops-to-direct-props --apply

# List all planned migrations

npx astryx upgrade --list

```

## Astryx Codemods by Release Version

### v0.0.2 Codemods (12 transforms)

The initial batch establishes Astryx's unified prop naming conventions:

- **`unify-visibility-to-onOpenChange`** — Consolidates visibility callbacks to `onOpenChange` pattern
- **`unify-uncontrolled-to-defaultX`** — Renames `initialX` props to `defaultX` (e.g., `initialOpen` → `defaultOpen`)
- **`rename-topnav-title-to-heading`** — `XDSTopNavTitle` → `XDSTopNavHeading`; `title` prop → `heading`
- **`rename-sidenav-header-to-heading`** — `XDSSideNavHeader` → `XDSSideNavHeading`
- **`rename-selector-items-to-options`** — `items` → `options` on `XDSSelector`
- **`rename-isShown-to-isOpen`** — `isShown` → `isOpen` for `Dialog` and `Popover`
- **`rename-form-tooltip-startIcon`** — `tooltip` → `labelTooltip`; `startIcon` → `labelIcon`
- **`rename-banner-endButton-to-endContent`** — `endButton` → `endContent` on `XDSBanner`
- **`migrate-useXDSIcon-to-getIcon`** — Replaces hook with direct `getIcon` call, removes `IconRegistryContext`
- **`migrate-isFullBleed-to-padding`** — `isFullBleed` → `padding={0}`
- **`migrate-gap-to-numeric`** — Converts `gap`/`rowGap`/`columnGap` token strings to numeric values
- **`migrate-badge-dot-to-statusdot`** — Badge `dot` mode → standalone `StatusDot` component

Source: `packages/cli/assets/codemods/transforms/v0.0.2/`

### v0.0.6 Codemods (6 transforms)

Design token system overhaul:

- **`migrate-token-names`** — Updates renamed design-token identifiers
- **`migrate-skeleton-radius`** — Moves `Skeleton` radius to numeric scale
- **`migrate-shadow-tokens`** — Elevation tokens → semantic shadow naming
- **`migrate-radius-tokens`** — Semantic radius → numeric scale
- **`migrate-collapse-to-collapsible`** — `collapse` props → `collapsible`
- **`migrate-badge-children-to-label`** — `<Badge>text</Badge>` → `<Badge label="text" />`

### v0.0.7 Codemods

- **`rename-banner-variant-to-container`** — `XDSBanner` `variant` → `container`

### v0.0.8 Codemods (2 transforms)

- **`rename-endslot-to-endcontent`** — `XDSButton` `endSlot` → `endContent`
- **`migrate-token-renames`** — Final v0.0.8 token name conventions

### v0.0.10 Codemods

- **`remove-size-props`** — Strips `size` from `XDSStatusDot` and `XDSProgressBar`

### v0.0.12 Codemods

- **`add-is-icon-only`** — Migrates `iconOnly` buttons to `XDSIconButton` component

### v0.0.13 Codemods (3 transforms)

- **`toolbar-density-to-size`** — `Toolbar` `density` → `size`
- **`rename-attachments-to-drawer`** — `XDSChatComposerAttachments` → `XDSChatComposerDrawer`
- **`icon-name-deprecations`** — Updates deprecated icon identifiers

### v0.0.14 Codemods (3 transforms)

React 19 preparation and semantic naming:

- **`rename-action-props`** — `on*Action` → `*Action` convention
- **`rename-status-variants`** — `positive`/`negative` → `success`/`error`
- **`rename-section-wash-to-muted`** — `wash` variant → `muted`

### v0.0.15 Codemods (7 transforms)

Major API simplification release:

- **`rename-stack-element-to-as`** — `element` prop → `as`
- **`rename-isStreaming-to-isStopShown`** — Chat component prop rename
- **`rename-imperative-ref-to-handleRef`** — Ref prop standardization
- **`rename-date-picker-to-input`** — `DatePicker` → `DateInput`; `DateRangePicker` → `DateRangeInput`
- **`migrate-theme-selectors-to-data-attrs`** — CSS selectors → `data-*` attributes
- **`migrate-selector-children-to-render-option`** — Children API → `renderOption` prop
- **`migrate-item-children-to-endcontent`** — Generic item children → `endContent` slot

### v0.1.0 Codemods (4 transforms)

**XDS-to-Astryx rebrand** — mandatory for package migration:

- **`migrate-xds-module-specifiers`** — `@xds/*` → `@astryxdesign/*` imports
- **`migrate-xds-declare-module`** — Updates TypeScript module augmentations
- **`migrate-xds-css-surfaces`** — CSS surface definitions to Astryx equivalents
- **`drop-xds-prefix-imports`** *(mandatory)* — Removes `XDS` prefix from all components

### v0.1.2 Codemods

- **`rename-text-color-active-to-accent`** — `color="active"` → `color="accent"`

### v0.1.3 Codemods

- **`migrate-layout-components-to-experimental`** — `layout.components` → `experimental.xle.components`

### v0.1.5 Codemods

- **`rename-switch-label-spacing-default-to-hug`** — `labelSpacing="default"` → `"hug"`

### v0.1.7 Codemods (2 transforms)

- **`rename-table-renderprops-styles-to-xstyle`** — `styles` → `xstyle` in render props
- **`migrate-table-tableprops-to-direct-props`** — Lifts `tableProps` object into direct props

### v0.1.8 Codemods

- **`rename-avatar-size-scale`** — Avatar sizes to abbreviated scale (`xsm`, `sm`, `md`, `lg`, `xlg`, `xxlg`)

### v0.2.0 Codemods

- **`remove-tablist-orientation`** — Removes no-op `orientation` prop from `TabList`

### v0.2.1 Codemods

- **`migrate-dialog-position-to-logical`** — `position="left/right"` → `start/end`

### v0.3.0 Codemods (4 transforms)

Authoring system cleanup:

- **`unwrap-authoring-factories`** — Removes `create*` authoring factories
- **`rename-radiogroup-arialabel-to-label`** — `aria-label` → `label` on `RadioGroup`
- **`rename-authoring-doctypes`** — Doc field types to domain-prefixed names
- **`migrate-authoring-imports`** — Re-points to `@astryxdesign/cli/authoring`

## Running Astryx Upgrade in CI

For automated version migration in continuous integration, use the JSON output mode:

```yaml
- name: Upgrade Astryx
  run: |
    npx astryx upgrade \
      --from ${{ steps.detect.outputs.current }} \
      --to ${{ steps.detect.outputs.latest }} \
      --apply \
      --json > upgrade-report.json

```

The `--json` flag produces a structured receipt with `upgrade.run`, `upgrade.status`, and `upgrade.list` fields for downstream parsing.

## Key Implementation Files

| File Path | Purpose |
|-----------|---------|
| `packages/cli/assets/codemods/registry.mjs` | Version-to-codemod mapping manifest |
| `packages/cli/assets/codemods/transforms/*/*.mjs` | Individual jscodeshift implementations |
| `packages/cli/clients/cli/commands/upgrade.mjs` | CLI command definition and option parsing |
| `packages/cli/assets/codemods/runner.mjs` | Core execution engine |
| `packages/cli/api/upgrade/*/*.mjs` | Programmatic API (`upgrade.run`, `upgrade.list`, `upgrade.status`) |
| [`packages/cli/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/cli/CHANGELOG.md) | Per-release codemod documentation |

## Summary

- **42+ codemods** ship with Astryx, spanning v0.0.2 through v0.3.0
- **jscodeshift-powered transforms** handle React component, prop, and import migrations
- **`--apply`, `--dry-run`, `--codemod <name>`** flags control execution scope
- **Registry-driven** system automatically selects transforms based on detected version
- **CI-ready** with `--json` structured output for automation pipelines

## Frequently Asked Questions

### How do I run only specific Astryx codemods instead of the full upgrade?

Use the `--codemod` flag with the transform name: `npx astryx upgrade --codemod migrate-table-tableprops-to-direct-props --apply`. This bypasses version detection and executes only that transform.

### Can I preview what changes a codemod will make before applying?

Yes. Run `npx astryx upgrade --dry-run` to see a diff preview of all pending migrations, or combine with `--codemod` to preview a single transform. No files are modified in dry-run mode.

### What happens if a codemod fails partway through an upgrade?

The runner in `packages/cli/assets/codemods/runner.mjs` processes codemods sequentially with isolated error boundaries. Failed transforms are reported in the output, but subsequent codemods continue executing unless `--bail` is specified.

### Where are the codemod source files located in the repository?

All transforms live under `packages/cli/assets/codemods/transforms/<version>/` as individual `.mjs` files. The registry at `packages/cli/assets/codemods/registry.mjs` maps version ranges to these files for automatic selection.