Official codemods for upgrading and maintaining Backstage projects, built by the community and approved by the Backstage core team.
Backstage moves fast! APIs get deprecated, plugin systems get rewritten, and manual upgrades across a large app become tedious and error-prone. This repo provides automated transformations that handle the mechanical parts of those migrations for you.
See the Codemod docs for more on building and running codemods.
Run the migration-recipe to apply every migration in one pass. Individual scripts can still be run on their own; see the recipe's README.
Run the migration-recipe to apply every migration in one pass. Individual scripts can still be run on their own; see the recipe's README.
Older versions are available in the codemods/ directory.
| Codemod | Description |
|---|---|
| mui4-to-bui-migration-recipe | MUI 4 to BUI: Migration recipe that runs every deterministic MUI→BUI codemod script in a safe order. |
Run any codemod in this repo against your Backstage project with the Codemod CLI:
yarn dlx codemod <codemod-name>Most codemods include an optional AI-powered fixup step that catches edge cases the AST transforms cannot handle mechanically (namespace imports, spread props, aliased re-exports, etc.). It is disabled by default. Enable it on a single codemod or on a migration recipe (which forwards it to every child codemod that supports it):
# Single codemod
yarn dlx codemod <codemod-name> --param aiFixup=true
# Migration recipe — forwards aiFixup to all supported child codemods
yarn dlx codemod @backstage/v1-51-0-migration-recipe --param aiFixup=trueCodemods in this repo are written using jssg (JS ast-grep) TypeScript transformation scripts that operate on ASTs generated by ast-grep. See the jssg docs for the full API reference.
# Install dependencies
yarn install
# Run all tests
yarn test
# Lint all files
yarn lint
# Format all files
yarn formatContributions are welcome especially codemods that automate common Backstage upgrade steps. See CONTRIBUTING.md for guidelines on submitting changes, adding changesets, and the release process.
codemods/
<version>/
<name>/
scripts/codemod.ts # Codemod logic (jssg / ast-grep)
tests/ # Input/expected test fixtures
codemod.yaml # Codemod manifest
workflow.yaml # Execution workflow
package.json
MIT