backstage-plugin-frontend-system-migration
Multi-step Codemod workflow for a full Backstage new frontend system migration (drops legacy @backstage/core-plugin-api usage).
Workflow
Everything lives in workflow.yaml. The workflow has one automatic node (deterministic-nfs-migration) so Codemod Cloud runs a single task (sequential steps, one git checkout—avoids parallel .git/index.lock conflicts).
| Step group | Purpose |
|---|---|
| Deterministic JSSG (always) | One js-ast-grep step: scripts/unified.ts runs metrics → route refs → plugin shell → APIs → pages/hooks in order (implemented in inventory.ts … pages-hooks.ts). |
| Optional (last two steps) | AI and/or package.json + lockfile updates, gated by parameters (both off by default). |
Parameters
Defaults are false for both:
| Parameter | When true |
|---|---|
run_ai_followups | Runs the AI step (SubPageBlueprint, useRouteRef guards, external route defaults). |
update_package_dependencies | Removes legacy @backstage/core-* deps and adds @backstage/frontend-plugin-api (uses npm by default; see env below). |
Usage
Target directory: set CODEMOD_TARGET or CODEMOD_TARGET_PATH when the shell working directory is not the plugin package root (used by the optional package step).
Package manager for update_package_dependencies: set CODEMOD_PACKAGE_MANAGER to pnpm or yarn if the repo does not use npm.
Scripts
scripts/unified.ts— workflow entrypoint; runs each phase in order, re-parses after eachcommitEditsresult, and passes the real file path via transformparamswhenfilename()isanonymous(seescripts/lib/effective-filename.ts)scripts/inventory.ts— metrics:backstage-nfs-migrationwithstep=inventory(patterns and risk: safe / medium / tricky)scripts/route-refs.ts— route refs (uses@jssg/utilsfor imports)scripts/plugin-shell.ts— plugin shell + optionalplugin.ts→plugin.tsxscripts/apis.ts— API factories and refsscripts/pages-hooks.ts— pure imports + same metric withstep=pages-hooksfor internal<Routes>usage
Agent skill (Cursor / coding agents)
See SKILL.md for when to use this migration, how to run the workflow, and how optional AI and package steps fit after the deterministic JSSG steps (same node).
Development
npm test runs JSSG tests: tests/inventory uses scripts/inventory.ts alone (metrics-only expectations); other suites use scripts/unified.ts to match the workflow.
License
MIT