Bbackstage

backstage/migrate-nav-item-to-page

Migrate NavItemBlueprint to PageBlueprint title/icon params for Backstage 1.51.0

backstagemigrationfrontend-plugin-apiNavItemBlueprintPageBlueprint1.51.0
Public
0 executions
Apply to Repository

Run locally

npx codemod @backstage/migrate-nav-item-to-page

@backstage/migrate-nav-item-to-page

Backstage 1.51.0 migration codemod that merges NavItemBlueprint navigation metadata into matching PageBlueprint extensions.

What it does

NavItemBlueprint was removed from @backstage/frontend-plugin-api in Backstage 1.51.0. Navigation items are now discovered from PageBlueprint extensions via their title and icon params.

For each NavItemBlueprint.make call, the codemod:

  1. Extracts title, icon, and routeRef from params
  2. Finds the matching PageBlueprint.make or PageBlueprint.makeWithOverrides with the same static routeRef
  3. Adds title and icon to the page extension params (or the originalFactory argument for makeWithOverrides)
  4. Wraps MUI icon identifiers as <Icon fontSize="inherit" /> when the icon is not already JSX
  5. Removes the nav item declaration and its entry from extensions arrays
  6. Removes unused NavItemBlueprint imports

Before / After

ts

Known limitations

  • MUI to Remix icon migration is not performed — icons are wrapped as JSX elements only. Use --param aiFixup=true for heuristic MUI → @remixicon/react conversion.
  • Dynamic routeRef values (non-identifier expressions) are flagged with TODO(backstage-codemod) for manual migration.
  • Unpaired nav items (no matching PageBlueprint with the same routeRef) are flagged with TODO(backstage-codemod) and left in place.
  • Ambiguous pairings (multiple pages sharing the same static routeRef) are flagged with TODO(backstage-codemod).
  • Non-static icons (computed expressions, function calls) may need manual conversion to IconElement JSX.
  • Namespace imports of NavItemBlueprint are detected via usage patterns but not fully decomposed — use AI fixup for complex cases.

Optional: AI fixup step

Enable the AI-powered fixup step with --param aiFixup=true to address edge cases:

  • Pair orphaned NavItemBlueprint extensions with the correct PageBlueprint
  • Convert MUI icons to @remixicon/react where only used for navigation
  • Clean up createFrontendModule / createFrontendPlugin extension arrays
  • Resolve ambiguous pairings and dynamic routeRef values

Installation

bash

Usage (from this repo)

bash

Development

From the repo root:

bash

Or from this package directory:

bash

Ready to contribute?

Build your own codemod and share it with the community.

Publish a codemodJoin the community