v1.50.0-migration-recipe

One-shot migration recipe for upgrading a Backstage app to 1.50.0. Chains every @backstage/* v1.50.0 codemod from the Codemod registry through a single workflow so you don't have to run each one by hand.

What it runs

Each step below is a registry package that you can also run on its own. The recipe executes them sequentially in an order aligned with the Backstage 1.50.0 release notes: catalog-node import normalization first, then the remaining breaking changes grouped by domain, then the deprecations.

Usage

bash
Copy
# Dry run (preview every step without writing any changes)
yarn dlx codemod@latest run @backstage/v1-50-0-migration-recipe \
  --target /path/to/backstage-app \
  --dry-run

# Apply the full recipe
yarn dlx codemod@latest run @backstage/v1-50-0-migration-recipe \
  --target /path/to/backstage-app

You can also run the recipe directly from this repo:

bash
Copy
yarn dlx codemod@latest workflow run \
  -w codemods/v1.50.0/migration-recipe/workflow.yaml \
  --target /path/to/backstage-app \
  --dry-run

AI fixup

The recipe runs every codemod at its default settings (no AI fixup). Ten of the eleven codemods ship an optional aiFixup param that uses an LLM to refine edge cases the AST transform cannot handle mechanically. If you want AI fixup for one of those, run that package on its own after the recipe:

bash
Copy
yarn dlx codemod@latest run @backstage/humanize-entity-ref-to-presentation \
  --target /path/to/backstage-app \
  --param aiFixup=true

The Codemod workflow engine does not currently support string interpolation inside a step's args:, so the recipe cannot forward a single top-level aiFixup flag to every step. Running the individual package with --param aiFixup=true is the supported path for now.

Notes

• Each step is invoked through the codemod: workflow action and resolved from the Codemod registry, so running the recipe installs the latest published version of every referenced package.
• The recipe does not reorder edits across codemods; each registry package owns its own before/after behavior. Check the individual READMEs for the details of any single step.
• Several of the codemods insert TODO(backstage-codemod) markers where a value needs a human review. After the recipe finishes, grep for TODO(backstage-codemod) in your repo to find everything that still needs attention.
• This recipe is orchestration only -- it has no transform script of its own, so there are no fixture tests. Running yarn test in this package validates the workflow schema via codemod workflow validate.