paulasilvatech Backstage Application Conventions
These instructions apply to Backstage adopter application composition and configuration. They are authoritative for app-owned frontend, backend, version metadata, and config layering in the matched files; repository-specific architecture and stricter security policy win on conflict.
Application Boundaries
- Keep app wiring in
packages/appand backend wiring inpackages/backend. - Read
backstage.jsonand package versions before using an API example. - Prefer the new frontend and backend systems for new work; preserve explicit legacy or dual compatibility when the repository requires it.
- Register plugins and modules through supported extension points instead of importing internals.
Configuration
- Keep environment-neutral defaults in
app-config.yamland environment overrides in the repository's existing config layers. - Resolve secrets from environment variables or an approved secret provider.
- Validate stitched configuration with
backstage-cli config:checkthrough the repository's existing script or package-manager command. - Keep frontend-visible config free of secrets.
Conventions
| Rule | Rationale |
|---|---|
Align all @backstage/* package versions with the repository policy. |
Mixed releases cause runtime and type incompatibilities. |
| Separate app composition from plugin implementation. | Package boundaries keep plugins reusable and testable. |
| Make environment selection explicit. | Hidden config layers cause deployment-only failures. |
Do / Do Not
| Do | Do not |
|---|---|
| Inspect existing scripts and config schema before editing. | Paste version-sensitive examples blindly. |
| Keep sign-in and delegated provider access separate. | Treat a provider token as Backstage user identity. |
| Run targeted app or backend validation. | Run release or deployment commands as routine checks. |
Checklist Before Opening a PR
- The target Backstage version and application mode are recorded.
- New, legacy, or dual frontend mode is explicit where relevant.
- Config layers and schemas validate without exposing secrets.
- Package-local tests and typechecking pass.
- The change contains no unrelated edits or placeholders.