using-backstage-frontend-system
Use when defining or authoring extensions for a Backstage frontend plugin in the new frontend system. Covers createFrontendPlugin, route refs, PageBlueprint, SubPageBlueprint, and hook-based API calls. DEFAULT for backend calls is a data hook (useAsync + fetchApi) — NOT ApiBlueprint. Only use ApiBlueprint for open-source plugins needing swappable implementations. Triggers on imports from @backstage/frontend-plugin-api or when writing src/plugin.tsx, src/routes.ts, src/apis.ts, src/extensions.tsx.
How do I install this agent skill?
npx skills add https://github.com/vinzscam/backstage-skills --skill using-backstage-frontend-systemIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a comprehensive technical reference for developing Backstage frontend plugins using the New Frontend System. It contains legitimate code patterns, instructional guidance, and framework-specific best practices without any malicious behavior, data exfiltration, or security risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Backstage New Frontend System (NFS) Patterns
Defaults
Before designing or implementing API access, apply these defaults:
- Calling a backend endpoint → data hook. Wrap
useAsync/useAsyncFnaroundfetchApi.fetchdirectly in a hook. No client class, nocreateApiRef, noApiBlueprint, no extra file. This is the right choice for almost every plugin. ApiBlueprint→ only for open-source plugins where adopters need to swap the implementation viacreateFrontendModule. If the plugin is internal or the API surface doesn't need to be overridable, do not useApiBlueprint.
If you are in a brainstorming or design phase and considering ApiBlueprint, stop and ask: "Will external adopters need to replace this implementation?" If no → use a data hook.
When to use this skill
- Defining a new frontend plugin (
src/plugin.tsx) - Declaring route refs (
src/routes.ts) - Exposing APIs from a plugin (
src/apis.ts) - Adding pages, sub-pages, or other extensions (
src/extensions.tsx) - Using NFS hooks (
useApi,useRouteRef)
Choose the right pattern
| Building... | Pattern | Reference |
|---|---|---|
| The plugin itself | createFrontendPlugin({ pluginId, ..., extensions }) | references/plugin-definition.md |
| Route refs | createRouteRef, createSubRouteRef, createExternalRouteRef from @backstage/frontend-plugin-api | references/route-refs.md |
| Calling a backend endpoint (use this) | A data hook wrapping useAsync / useAsyncFn around fetchApi.fetch — no client class, no extension | references/api-extensions.md |
| Exposing an extensible API (open-source plugins only) | ApiBlueprint.make({ params }) — only when adopters need swappable implementations | references/api-extensions.md |
| A page (single route) | PageBlueprint.make({ params: { path, routeRef, title, icon, loader } }) | references/page-extensions.md |
| A page with tabs | PageBlueprint (no loader) + SubPageBlueprints | references/sub-pages.md |
| Reading APIs in components | useApi(apiRef), useRouteRef(routeRef) from @backstage/frontend-plugin-api | references/hooks.md |
Two invocation modes
- Standalone: user is editing an existing NFS plugin. Pick a reference and apply.
- Post-scaffold (called by
creating-backstage-pluginforfrontend-plugin/frontend-plugin-moduletemplates): wire up the canonical NFS structure in the freshly scaffolded plugin —src/routes.ts,src/plugin.tsxusingcreateFrontendPlugin, and an examplePageBlueprintextension.
Common gotchas
- In NFS, plugin-system imports come from
@backstage/frontend-plugin-api, not@backstage/core-plugin-api. Hooks (useApi,useRouteRef), refs (identityApiRef,configApiRef,discoveryApiRef,fetchApiRef,storageApiRef,analyticsApiRef), and primitives (createApiRef) all live in the new package. createRouteRef()takes noidargument — the id is derived from the extension that owns the route.createExternalRouteRef({ defaultTarget: '<pluginId>.<routeName>' })— setdefaultTargetto the most common binding so apps don't need explicitbindRoutescalls.useRouteRef(externalRef)may returnundefinedif the external route isn't bound — always handle the undefined case.- Page components inside a
PageBlueprintloader should NOT includePage,Header, orPageWithHeaderfrom@backstage/core-components. The framework'sPageLayoutrendersPluginHeaderautomatically. UseContainerfrom@backstage/uias the outermost wrapper for page content. UseHeaderfrom@backstage/uionly when you need a subtitle or custom actions. SubPageBlueprintpaths are relative (no leading/). Sub-page components render content only — noPage, noHeader, noHeaderTabs. Wrap sub-page content inContainerfrom@backstage/uiif padding is needed.createApiRef<T>().with({ id, pluginId })— the builder form is preferred so ownership is explicit. Theidmust still be globally unique. Only the owning plugin (or a module targeting it) can override the API.- For any
fetchApi.fetchcall, 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 UI surfaces (e.g.<ResponseErrorPanel>) understand. Never justthrow new Error(\Failed: ${response.status}`)`.
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-frontend-system">View using-backstage-frontend-system on skillZs</a>