using-backstage-backend-services
Use when a Backstage backend plugin or module needs a core service — logger, config, http router, database, scheduler, lifecycle, cache, urlReader, discovery, auth, httpAuth, or userInfo. Triggers on imports of coreServices.* refs from @backstage/backend-plugin-api or any deps map in a plugin/module register block.
How do I install this agent skill?
npx skills add https://github.com/vinzscam/backstage-skills --skill using-backstage-backend-servicesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a set of reference materials and code templates for developing Backstage backend plugins. It demonstrates how to interact with core services like logging, configuration, databases, and authentication using the recommended patterns of the Backstage framework. The provided code emphasizes security best practices such as schema validation and isolated service scoping.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Backstage Backend Services
When to use this skill
- Plugin or module needs logging, configuration, HTTP routing, database, scheduling, caching, URL fetching, service discovery, or auth
- User mentions any specific
coreServices.*ref - Adding a new dep to a
register({ deps: {...} })block
Defaults
- All HTTP routes are authenticated by default. Normal plugin endpoints need no auth configuration — the frontend's
fetchApihandles tokens automatically. Never useaddAuthPolicy({ allow: 'unauthenticated' })for normal data endpoints; seereferences/http-router.md→ Auth policies.
Choose the right service
| Need | Service | Reference |
|---|---|---|
| Logging | coreServices.logger (plugin-scoped, pre-tagged with pluginId) | references/logger-and-config.md |
| Read app-config.yaml | coreServices.rootConfig | references/logger-and-config.md |
| Register HTTP routes | coreServices.httpRouter | references/http-router.md |
| Knex DB access | coreServices.database (plugin-scoped, isolated schema) | references/database.md |
| Periodic / cron tasks | coreServices.scheduler | references/scheduler-and-lifecycle.md |
| Startup / shutdown hooks | coreServices.lifecycle (plugin) or coreServices.rootLifecycle (root) | references/scheduler-and-lifecycle.md |
| Service-to-service tokens | coreServices.auth | references/auth.md |
| Authenticate incoming requests | coreServices.httpAuth | references/auth.md |
| Resolve current user from credentials | coreServices.userInfo | references/auth.md |
| Read external URLs (GitHub, GitLab, etc.) | coreServices.urlReader | references/urlReader-and-discovery.md |
| Resolve a backend plugin's base URL | coreServices.discovery | references/urlReader-and-discovery.md |
| Key-value cache | coreServices.cache | references/cache.md |
Two invocation modes
- Standalone: adding a service dep to an existing plugin or module.
- Post-scaffold (called by
creating-backstage-pluginfor backend templates): includecoreServices.loggerandcoreServices.httpRouteras defaults; surface additional services if intent suggests them (e.g. "stores X" → database; "polls every N minutes" → scheduler).
Common gotchas
- All refs come from
@backstage/backend-plugin-api. The actual implementations come from@backstage/backend-defaults, but plugins consume the refs only. - Plugin-scoped services give each plugin an isolated instance —
coreServices.databasereturns a Knex client scoped to a per-plugin schema;coreServices.loggeris pre-tagged withpluginId. Don't try to share a Knex instance across plugins by passing it around — call cross-plugin viacoreServices.discovery+ HTTP instead. - The
auth,httpAuth, anduserInfoservices are easy to confuse.authmints/verifies tokens for service-to-service calls;httpAuthauthenticates an incoming Express request;userInforesolves a user identity from credentials returned byhttpAuth. coreServices.schedulerschedules durable tasks across replicas — don't usesetIntervalfor production tasks.- For tests: use
mockServices.<name>(...)to get an instance for unit tests; usemockServices.<name>.factory(...)when passing tostartTestBackend({ features: [...] }). Not every service has a factory —httpRouter,cache,urlReader,lifecycleare typically provided by the test backend's defaults. - When calling another Backstage plugin via
discovery+auth(cross-plugin HTTP), handle non-OK responses withthrow await ResponseError.fromResponse(response)from@backstage/errors. It parses the response body for structured error info and produces a typed error other Backstage layers (logging, error reporting, frontend<ResponseErrorPanel>) understand. Never justthrow new Error(\Failed: ${response.status}`)`. - Inside route handlers, throw typed errors from
@backstage/errors(NotFoundError,InputError,NotAllowedError,ConflictError,ServiceUnavailableError,ForwardedError, etc.) — the default backend error middleware turns them into properly-formatted HTTP responses. Don'tres.status(...).json(...)for error cases. Seereferences/http-router.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vinzscam/backstage-skills/using-backstage-backend-services">View using-backstage-backend-services on skillZs</a>