plugin-full-frontend-system-migration
Full Plugin Migration to the New Frontend System
This skill helps fully migrate an existing Backstage plugin from the old frontend system to the new one. Unlike adding dual support (which keeps the old system working), this is a complete migration that removes all @backstage/core-plugin-api usage and makes the plugin work exclusively with the new frontend system.
This is the preferred approach for internal plugins that are only used in a single app, since there is no need to maintain backward compatibility. It can also be used for published plugins when you're ready to drop old system support entirely.
It is highly recommended to be on Backstage version 1.49.x or above before starting this, although not mandatory, you may face issues with some of the instructions below. This can be verified by looking in the backstage.json file in the root of the repository.
Key Differences from Dual Support
| Aspect | Dual Support | Full Migration |
|---|---|---|
| Entry point | Old src/plugin.ts + new src/alpha.tsx |
Single src/plugin.tsx |
| Plugin creation | Both createPlugin and createFrontendPlugin |
Only createFrontendPlugin |
| Core dependency | Keeps @backstage/core-plugin-api |
Removes it, uses only @backstage/frontend-plugin-api |
| Route refs | Reuses @backstage/core-plugin-api refs directly |
Uses createRouteRef from @backstage/frontend-plugin-api |
| Page shell | Old pages keep Page/Header, NFS pages skip it |
All pages rely on framework's PageLayout/PluginHeader |
| Internal routing | May keep legacy <Route> trees in components |
Replaced with SubPageBlueprint tabbed pages |
| Compatibility | Not needed | Not needed |