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 codemod below in one pass, or run any individual codemod on its own.
| Codemod | Description |
|---|---|
| migrate-bui-props-to-intersection | Migrate ComboboxProps/SelectProps interface extends to type intersection |
| migrate-select-combobox-props | Migrate deprecated Select/Combobox search props and option value to id |
| migration-recipe | Migration recipe that runs every @backstage v1.52.0 codemod from the registry in a safe order. |
| remove-stitching-strategy-mode | Remove deprecated catalog.stitchingStrategy.mode from app-config |
| rename-bui-css-tokens-v1-52 | Rename deprecated BUI semantic color tokens |
Run the migration-recipe to apply every codemod below in one pass, or run any individual codemod on its own.
| Codemod | Description |
|---|---|
| experimental-form-decorators-to-stable | Rename EXPERIMENTAL_formDecorators to formDecorators in Backstage template specs for 1.51.0 |
| loading-to-is-pending | Rename deprecated loading prop to isPending in @backstage/ui and data-loading to data-ispending in CSS |
| migrate-nav-item-to-page | Migrate NavItemBlueprint to PageBlueprint title/icon params for Backstage 1.51.0 |
| migrate-policy-query-user | Migrate PolicyQueryUser off removed token, expiresInSeconds, and identity fields |
| migration-recipe | Migration recipe that runs every @backstage v1.51.0 codemod from the registry in a safe order. |
| portable-schema-method-call | Call PortableSchema.schema() as a method instead of property access |
| remove-immediate-stitching-mode | Migrate catalog.stitchingStrategy.mode from immediate to deferred |
| rename-header-main-class | Rename removed .bui-Header to .bui-HeaderContent and classNames.root to classNames.content |
| render-test-app-nav-migration | Migrate renderInTestApp nav-item tests to renderTestApp for Backstage 1.51.0 |
Older versions are available in the codemods/ directory.
| Codemod | Description |
|---|---|
| migrate-mui-accordion-to-bui-accordion | MUI 4 to BUI: Replace Accordion with BUI Accordion (packaged with form-control codemods; Accordion is a complex component) |
| migrate-mui-alert-to-bui-alert | MUI 4 to BUI: Replace MUI Alert with BUI Alert |
| migrate-mui-bootstrap-to-bui | MUI 4 to BUI: Bootstrap app dependencies and root CSS |
| migrate-mui-button-to-bui-button | MUI 4 to BUI: Replace MUI Button with BUI Button |
| migrate-mui-chip-to-tag | MUI 4 to BUI: Replace Chip with Tag (omits -bui-; BUI export is Tag) |
| migrate-mui-dialog-to-bui-dialog | MUI 4 to BUI: Replace Dialog shell with BUI Dialog |
| migrate-mui-icon-button-to-button-icon | MUI 4 to BUI: Replace IconButton with ButtonIcon. Package name omits -bui- because ButtonIcon is the BUI export name. |
| migrate-mui-icons-to-remix-icons | MUI 4 to BUI: Replace MUI icons with Remix icons |
| migrate-mui-layout-to-bui-layout | MUI 4 to BUI: Convert common MUI layout primitives to BUI layout |
| migrate-mui-list-family-to-bui-list | MUI 4 to BUI: Replace List family primitives with BUI List |
| migrate-mui-menu-popover-to-bui-menu | MUI 4 to BUI: Replace Menu and Popover patterns with BUI Menu |
| migrate-mui-radio-checkbox-to-bui | MUI 4 to BUI: Replace radio and checkbox group patterns with BUI groups |
| migrate-mui-select-family-to-bui-select | MUI 4 to BUI: Replace Select wrapper patterns with BUI Select |
| migrate-mui-slider-to-bui-slider | MUI 4 to BUI: Replace Slider with BUI Slider |
| migrate-mui-styles-to-bui-css-modules | MUI 4 to BUI: Migrate makeStyles usage to BUI CSS modules |
| migrate-mui-tabs-to-bui-tabs | MUI 4 to BUI: Replace MUI Tabs with BUI Tabs |
| migrate-mui-textfield-to-bui-textfield | MUI 4 to BUI: Replace TextField with BUI TextField |
| migrate-mui-tooltip-to-bui-tooltip | MUI 4 to BUI: Replace Tooltip with TooltipTrigger |
| migrate-mui-typography-to-text | MUI 4 to BUI: Replace Typography with Text. Package name omits -bui- because Text is the BUI export name. |
| mui4-to-bui-migration-recipe | MUI 4 to BUI: Migration recipe that runs every deterministic MUI→BUI codemod from the registry in a safe order. |
| remove-mui-dependencies | MUI 4 to BUI: Remove unused @material-ui/* dependencies from package.json |
Run any codemod in this repo against your Backstage project with the Codemod CLI:
npx 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
npx codemod <codemod-name> --param aiFixup=true
# Migration recipe — forwards aiFixup to all supported child codemods
npx 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