Upgrading

When Astryx ships a release, bump your devDependencies, rerun the checks, widen your peer ranges, and ship a codemod for each change that breaks apps.

bash
# 1. Build and test against the new release
npm install -D @astryxdesign/cli@latest @astryxdesign/core@latest
# 2. Rerun the checks
npx astryx doctor integration validate
npx astryx doctor integration docs
npx astryx integration verify
# 3. Admit the new Core once the checks pass
npm pkg set 'peerDependencies.@astryxdesign/core=^0.6.0 || ^0.7.0'
# 4. Migrate apps across a change that breaks them
npx astryx integration add codemod rename-delay --to 0.7.0

• Run every check in astryx docs cli/integrations/ship/checks, not only the ones shown.
• Name each codemod folder after the Core version whose upgrade should run it; see astryx docs cli/integrations/building-blocks/codemods.
• Release the result as a new version of your package; see astryx docs cli/integrations/ship/publishing.

After an app installs a new Core, astryx upgrade runs the codemods for the versions it crossed. It is a dry run by default; --apply writes the changes.

bash
# Preview what would change; nothing is written
npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
# Write the changes
npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply

text
Integrations: @acme/astryx-widgets
1 codemod to run
Applying integration codemods...
  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
[ok]     [ok] src/Hero.tsx

• --from is the @astryxdesign/core version the app had before, and the target is the installed Core.
• --integration names your package. Without it, or an integrations entry in astryx.config, the upgrade skips your codemods, even when the app has your package installed.
• The count includes Core's codemods for the same versions, which run first.
• Put this command in your release notes.

Upgrades never write files that the app marks as generated, vendored, or ignored. When such a file still needs a codemod change, the upgrade stops with ERR_CODEMOD_PROTECTED and exit code 1.

• Generated: an @generated comment at the top of the file, or linguist-generated in .gitattributes.
• Vendored: linguist-vendored in .gitattributes.
• Ignored: a match in .gitignore or .hgignore.

text
!     ! src/gen/Gen.tsx - protected by @generated in the leading comment block
ERR_CODEMOD_PROTECTED: 1 protected file still requires a codemod change:
  src/gen/Gen.tsx — @generated in the leading comment block
Upgrade incomplete: protected changes remain

The upgrade still writes every other file. Its options and exit codes are in astryx docs cli/commands/upgrade.