skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
vinzscam/backstage-skills50 installs

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-system
view source ↗

Is 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/useAsyncFn around fetchApi.fetch directly in a hook. No client class, no createApiRef, no ApiBlueprint, 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 via createFrontendModule. If the plugin is internal or the API surface doesn't need to be overridable, do not use ApiBlueprint.

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...PatternReference
The plugin itselfcreateFrontendPlugin({ pluginId, ..., extensions })references/plugin-definition.md
Route refscreateRouteRef, createSubRouteRef, createExternalRouteRef from @backstage/frontend-plugin-apireferences/route-refs.md
Calling a backend endpoint (use this)A data hook wrapping useAsync / useAsyncFn around fetchApi.fetch — no client class, no extensionreferences/api-extensions.md
Exposing an extensible API (open-source plugins only)ApiBlueprint.make({ params }) — only when adopters need swappable implementationsreferences/api-extensions.md
A page (single route)PageBlueprint.make({ params: { path, routeRef, title, icon, loader } })references/page-extensions.md
A page with tabsPageBlueprint (no loader) + SubPageBlueprintsreferences/sub-pages.md
Reading APIs in componentsuseApi(apiRef), useRouteRef(routeRef) from @backstage/frontend-plugin-apireferences/hooks.md

Two invocation modes

  • Standalone: user is editing an existing NFS plugin. Pick a reference and apply.
  • Post-scaffold (called by creating-backstage-plugin for frontend-plugin / frontend-plugin-module templates): wire up the canonical NFS structure in the freshly scaffolded plugin — src/routes.ts, src/plugin.tsx using createFrontendPlugin, and an example PageBlueprint extension.

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 no id argument — the id is derived from the extension that owns the route.
  • createExternalRouteRef({ defaultTarget: '<pluginId>.<routeName>' }) — set defaultTarget to the most common binding so apps don't need explicit bindRoutes calls.
  • useRouteRef(externalRef) may return undefined if the external route isn't bound — always handle the undefined case.
  • Page components inside a PageBlueprint loader should NOT include Page, Header, or PageWithHeader from @backstage/core-components. The framework's PageLayout renders PluginHeader automatically. Use Container from @backstage/ui as the outermost wrapper for page content. Use Header from @backstage/ui only when you need a subtitle or custom actions.
  • SubPageBlueprint paths are relative (no leading /). Sub-page components render content only — no Page, no Header, no HeaderTabs. Wrap sub-page content in Container from @backstage/ui if padding is needed.
  • createApiRef<T>().with({ id, pluginId }) — the builder form is preferred so ownership is explicit. The id must still be globally unique. Only the owning plugin (or a module targeting it) can override the API.
  • For any fetchApi.fetch call, handle non-OK responses with throw 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 just throw new Error(\Failed: ${response.status}`)`.

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>