Bbackstage

backstage/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.

backstagemigrationmuibuirecipeworkflow
PublicBundle
1 executions
Use dashboardApply to Repository

Run locally

npx codemod @backstage/mui4-to-bui-migration-recipe

mui4-to-bui-migration-recipe

Run every deterministic @backstage/* MUI 4 → BUI codemod from the Codemod Registry in a single ordered pass.

This recipe is not tied to a single Backstage release. It is the orchestration package for the ongoing MUI 4 to BUI migration work in app and plugin repositories.

Recommended order

  1. Bootstrap first — @backstage/migrate-mui-bootstrap-to-bui adds @backstage/ui / @remixicon/react dependencies and the global BUI stylesheet.
  2. Transforms — icons, styles, components, form controls, then layout, in the stable sequence below.
  3. Cleanup last — @backstage/remove-mui-dependencies drops unused @material-ui/* packages from package.json only after source files no longer import them.

Do not run remove-mui-dependencies before the component transforms finish, or packages that still have MUI imports may be removed incorrectly.

What it runs

#PackageDomainCovers
1@backstage/migrate-mui-bootstrap-to-buiBootstrap / package setupAdds BUI and Remix deps; ensures root CSS import where MUI is used
2@backstage/migrate-mui-icons-to-remix-iconsIcon source migrationReplaces @material-ui/icons imports with @remixicon/react equivalents
3@backstage/migrate-mui-styles-to-bui-css-modulesStyling architectureMigrates makeStyles / withStyles toward BUI CSS modules
4@backstage/migrate-mui-typography-to-textTypographyReplaces MUI Typography with BUI Text
5@backstage/migrate-mui-alert-to-bui-alertAlert bannersMigrates MUI Alert to BUI Alert
6@backstage/migrate-mui-button-to-bui-buttonStandard buttonsMigrates MUI Button to BUI Button
7@backstage/migrate-mui-icon-button-to-button-iconIcon buttonsMigrates MUI IconButton to BUI ButtonIcon
8@backstage/migrate-mui-tooltip-to-bui-tooltipTooltipsMigrates MUI Tooltip toward BUI TooltipTrigger
9@backstage/migrate-mui-dialog-to-bui-dialogDialogsMigrates Dialog shell patterns to BUI Dialog
10@backstage/migrate-mui-tabs-to-bui-tabsTabsMigrates MUI Tabs to BUI Tabs
11@backstage/migrate-mui-menu-popover-to-bui-menuMenus / popoversMigrates Menu / Popover patterns to BUI Menu
12@backstage/migrate-mui-list-family-to-bui-listListsMigrates List family primitives to BUI List
13@backstage/migrate-mui-chip-to-tagTags / chipsMigrates MUI Chip to BUI Tag
14@backstage/migrate-mui-select-family-to-bui-selectSelectMigrates Select wrapper patterns to BUI Select
15@backstage/migrate-mui-textfield-to-bui-textfieldTextFieldMigrates MUI TextField to BUI TextField
16@backstage/migrate-mui-accordion-to-bui-accordionAccordionMigrates Accordion patterns to BUI Accordion
17@backstage/migrate-mui-radio-checkbox-to-buiRadio / checkbox groupsMigrates radio and checkbox group patterns to BUI groups
18@backstage/migrate-mui-slider-to-bui-sliderSliderMigrates MUI Slider to BUI Slider
19@backstage/migrate-mui-layout-to-bui-layoutLayout primitivesConverts common layout primitives (e.g. Box / Paper / Grid) toward BUI layout
20@backstage/remove-mui-dependenciesCleanupRemoves unused @material-ui/* dependencies from package.json after source migration

Also see the short ordering note in ../README.md.

Package naming

Most transforms use migrate-mui-<source>-to-bui-<target>. A few intentionally omit -bui- in the target segment when the BUI export name is the product surface (not a “BUI-prefixed” alias):

PackageWhy the name looks different
@backstage/migrate-mui-typography-to-textTarget is BUI Text
@backstage/migrate-mui-chip-to-tagTarget is BUI Tag
@backstage/migrate-mui-icon-button-to-button-iconTarget is BUI ButtonIcon
@backstage/migrate-mui-icons-to-remix-iconsTarget is @remixicon/react, not @backstage/ui
@backstage/migrate-mui-radio-checkbox-to-buiCovers radio/checkbox groups → BUI groups

Usage

bash

Recipe behavior

  • Every step runs at default deterministic settings.
  • The recipe ships no aiFixup parameter.
  • Ambiguous cases are marked with TODO(backstage-codemod) in the transformed source rather than embedded AI workflow nodes.

Manual follow-up

After the recipe finishes:

  1. Search the repo for TODO(backstage-codemod) and resolve each marker.
  2. Search for remaining Material UI imports, for example:
    • @material-ui/
    • @mui/
  3. Re-run typecheck / tests for the packages you migrated.
  4. Spot-check visual polish (spacing, dark mode, token usage) — the recipe does not aim for perfect theme parity.

Out of scope

The following are not covered by this recipe (document-only / manual):

  • Timeline and unsupported Material UI Lab widgets without a stable BUI equivalent
  • @material-table/core and broader table-system migrations that are not a safe 1:1 replacement
  • Perfect theme parity, dark-mode polish, and final design-token tuning after the source-level migration
  • Custom wrapper abstractions that hide MUI components behind project-specific APIs

Notes

  • Each step resolves from the Codemod registry (source: '@backstage/<package>'), so underlying packages must be published before the recipe can run end-to-end.
  • This recipe is orchestration only — it has no transform script of its own. Running yarn test validates the workflow schema via codemod workflow validate.

Ready to contribute?

Build your own codemod and share it with the community.

Publish a codemodJoin the community