Complete List of Astryx Upgrade Codemods for Version Migration

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
• Queries the registry for applicable transforms
• Runs codemods sequentially with optional Prettier/ESLint cleanup

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

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

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