paulasilvatech Backstage framework
Choose public services and extension points from the target Backstage version instead of coupling plugins to implementation internals.
When to invoke
- "Which Backstage core service should this plugin use?"
- "Create a backend module for an extension point."
- "Use a frontend blueprint or service ref."
- "Find the supported API in the generated framework reference."
Procedure
- Confirm Backstage version, adopter or core mode, frontend mode, and plugin boundary.
- Start from the generated framework index and stable API documentation for that exact release.
- Map the requirement to:
- a core backend service,
- a plugin-specific extension point,
- a frontend blueprint or utility API,
- an app module,
- or a separate plugin boundary.
- Prefer
coreServicesand public service refs for config, logging, URL reading, databases, discovery, auth, HTTP auth, lifecycle, health, schedulers, metrics, tracing, and user info. - Use
createBackendModuleonly to extend one plugin through an exported extension point. - Keep service dependencies explicit in registration and inject test doubles in unit tests.
- Treat alpha APIs as version-sensitive and document the exact target version.
- Validate startup ordering, lifecycle cleanup, permission and auth propagation, scheduled-task uniqueness, and error handling.
Output template
## Backstage framework decision
**Backstage version:** <version>
| Requirement | Public API | Stability | Package | Test strategy |
| --- | --- | --- | --- | --- |
### Rejected coupling
- <internal API or boundary and reason>
Quality gate
- The selected API exists in the target release's generated reference.
- Core services and extension points replace internal imports.
- Alpha or deprecated APIs are clearly labeled.
- Lifecycle, auth, permissions, scheduler, and observability behavior is covered.
- Service dependencies are injectable and unit tested.
- Package boundaries contain no cycles or app-specific leakage.