Backstage codemods automate the repeatable parts of upgrades, not the judgment calls
The project’s new recipes belong after dependency and template updates, while larger migrations such as MUI-to-BUI remain deliberate, review-heavy work.
Backstage has added an automation layer to its familiar upgrade routine, but the project is explicit about where that layer belongs. The new official recipes can rewrite recurring source changes in application and plugin code; they do not replace dependency updates, template comparison or human review.
For platform teams, the useful change is not merely that codemods exist. It is that Backstage now defines a sequence for using them without confusing mechanical cleanup with compatibility decisions.
Start with the existing upgrade path
The project’s codemod announcement keeps the established first steps intact: run yarn backstage-cli versions:bump, then use the Backstage Upgrade Helper to compare and apply changes from the create-app template.
Those steps answer two different questions. The package bump moves the dependency set toward the target release. The template diff shows how freshly generated application scaffolding changed. Neither step is intended to clean up custom plugin code, deprecated properties, renamed configuration keys or stale imports.
That is the gap the new recipes target. Backstage publishes ordered bundles of transforms in the backstage/codemods repository and on the Codemod Registry. Teams run them with the Codemod CLI against their own source tree.
Match the recipe to the target release
Backstage separates release-specific recipes from broader, optional migrations. A versioned recipe follows the naming pattern @backstage/v1-XX-0-migration-recipe; the project’s example for a move toward 1.52.0 is @backstage/v1-52-0-migration-recipe.
The safe operating sequence is therefore dependency bump, Upgrade Helper and template changes, then the recipe for the target release. Backstage recommends running the recipe in dry-run mode before applying it. If no recipe exists for a release, the codemod step is skipped rather than replaced with a recipe for a different version.
Automation still leaves a review queue. After applying a recipe, teams are told to search for TODO(backstage-codemod) markers and read the recipe README for work that remains outside the transforms. Those markers are the boundary between changes the recipe can make deterministically and compatibility work that needs local context.
Treat MUI-to-BUI as a separate migration
The first miscellaneous recipe moves code from Material UI 4 toward Backstage UI. It runs an ordered set of transforms covering bootstrap work, icons, styles, components, layout and dependency cleanup.
Backstage does not present that recipe as a mandatory part of every monthly upgrade. It is an opt-in migration to run when a team has chosen to leave MUI behind. That distinction matters operationally: combining a routine version bump with a cross-cutting UI migration would enlarge the change set and make regressions harder to isolate.
The practical rule is narrow: automate the repetitive edits, but preserve explicit checkpoints around package resolution, generated-template differences and repository-specific leftovers. Codemods shorten the mechanical part of an upgrade; they do not turn an application migration into an unattended operation.
sources
- Automating Backstage upgrades with codemodsbackstage.io
comments · 0