using-backstage-backend-system
Use when defining or authoring a Backstage backend plugin or module. DEFAULT is createBackendPlugin when you own the HTTP routes and database; use createBackendModule only when extending another plugin (e.g. adding a processor to the catalog plugin). Triggers on imports from @backstage/backend-plugin-api or when writing src/plugin.ts, src/module.ts, src/index.ts in a backend package.
How do I install this agent skill?
npx skills add https://github.com/vinzscam/backstage-skills --skill using-backstage-backend-systemIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard patterns and templates for developing Backstage backend plugins and modules using the official @backstage/backend-plugin-api. No security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Backstage Backend System Patterns
When to use this skill
- Defining a new backend plugin (
src/plugin.ts) - Defining a backend module (
src/module.ts) that extends another plugin - Choosing between a full plugin vs a module
- Exposing extension points so other modules can extend your plugin
Defaults
- Your code owns HTTP routes or a database →
createBackendPlugin. The plugin gets its own pluginId, its own scoped services (logger, database, httpRouter), and mounts routes at/api/<pluginId>/. - Your code extends another plugin (e.g. adding a catalog processor, a scaffolder action) →
createBackendModule. The module targets an existing plugin'spluginIdand registers against that plugin's extension point. - Extension points are only needed when you're building a plugin that other teams will extend via modules. Most plugins don't need them.
Choose the right pattern
| Building... | Pattern | Reference |
|---|---|---|
| A standalone backend service (use this by default) | createBackendPlugin({ pluginId, register }) | references/plugin-definition.md |
| A module that extends another plugin | createBackendModule({ pluginId, moduleId, register }) | references/modules.md |
| An extension point so other modules can extend yours | createExtensionPoint<T>({ id }) | references/extension-points.md |
Two invocation modes
- Standalone: editing an existing backend plugin/module.
- Post-scaffold (called by
creating-backstage-pluginforbackend-plugin,backend-plugin-module,catalog-provider-module,scaffolder-backend-module): wire up the canonical structure (src/plugin.tsorsrc/module.ts,src/index.tsre-export).
Common gotchas
- All wiring imports come from
@backstage/backend-plugin-api, not@backstage/core-plugin-api(which is frontend-only). - The
register(env)callback receives an environment object withenv.registerInit({ deps, async init })andenv.registerExtensionPoint(point, impl).depsis a map of service refs the init function needs;initreceives the resolved instances. registerInitmay be called only once per plugin/module.registerExtensionPointmust be called beforeregisterInit.- Plugin-scoped vs root-scoped services: most refs (
logger,httpRouter,database,scheduler,auth,httpAuth,userInfo,cache,discovery,urlReader,lifecycle,permissions) are plugin-scoped — each plugin gets its own instance with plugin-aware behavior (e.g. logger pre-tagged withpluginId, database giving a per-plugin schema). Six refs (rootConfig,rootLogger,rootLifecycle,rootHealth,rootHttpRouter,rootInstanceMetadata) are root-scoped — single shared instance. Both can be depended on from a plugin'sregisterblock; the distinction matters for behavior, not for injection syntax. - A plugin's
pluginIdand a module'smoduleIdmust match the pattern[a-z][a-z0-9-]*(letters, digits, dashes; starts with a letter). - Modules depend on the extension points exported by the target plugin's library package (e.g.
@backstage/plugin-catalog-node), not on the plugin's main package.
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-system">View using-backstage-backend-system on skillZs</a>