paulasilvatech Backstage app frontend-system migration
Adapt the pinned upstream Backstage migration procedure to the target app and version without discarding working legacy behavior prematurely.
When to invoke
- "Migrate packages/app to the new frontend system."
- "Enable hybrid frontend mode in Backstage."
- "Replace FlatRoutes and the legacy app shell."
- "Enable feature discovery and finish the app migration."
Procedure
- Confirm adopter-app mode, installed Backstage version, and a green app baseline.
- Read the pinned upstream procedure.
- Compare the target version with the pinned source commit and verify changed APIs in first-party documentation.
- Inventory legacy app creation, routes, sidebar, APIs, themes, route bindings, and plugins.
- Implement the hybrid phase first, preserving compatibility helpers and observable behavior.
- Enable and validate feature discovery according to the target version.
- Migrate one surface at a time with focused rendering, route, and integration tests.
- Remove compatibility code only after every legacy surface has a new-system equivalent.
- Run app typecheck, tests, build, and startup validation using repository scripts.
Output template
## App frontend migration result
**Phase:** inventory | hybrid | incremental | complete
**Target version:** <version>
| Surface | Legacy path | New-system path | Validation | Status |
| --- | --- | --- | --- | --- |
Progressive disclosure and bundled resources
references/upstream/SKILL.md: upstream migration procedure retained for detailed compatibility guidance.
Quality gate
- Adopter-app mode and target version are evidenced.
- A green baseline exists before migration.
- The pinned procedure was checked against the target version.
- Hybrid compatibility remains until equivalent new-system behavior is validated.
- Routes, sidebar, APIs, themes, and plugin installation are covered.
- App tests, typecheck, build, and startup checks pass.