Common Extension Blueprints
This section covers many of the extension blueprints available at your disposal when building Backstage frontend plugins.
Extension blueprints in @backstage/frontend-plugin-api
These are the extension blueprints provided by the Backstage frontend framework itself.
Api - Reference
An API extension is used to add or override Utility API factories in the app. They are commonly used by plugins for both internal and shared APIs. There are also many built-in Api extensions provided by the framework that you are able to override.
Page - Reference
Page extensions provide content for a particular route in the app. By default pages are attached to the app routes extensions, which renders the root routes. Pages automatically inherit the plugin's title and icon as defaults, which can be overridden per-page via PageBlueprint params.
To enable sub-pages on a page, you can either omit the loader param to use the built-in default implementation that renders sub-pages as tabs, or provide a custom loader that explicitly handles the sub-page inputs.
Existing pages retain implicit React Router v6 matches. To migrate a page or select another routing library, render its adapter inside the page's lazily loaded component — see Choose a router for a page.
SubPage - Reference
Sub-page extensions create tabbed content within a parent page. They are attached to a page extension's pages input and rendered as tabs in the page header. Each sub-page has a path (relative to the parent page), a title for the tab, and an optional icon. Content is lazy-loaded via a loader function.
A sub-page declares its own router adapter in its lazily loaded component, which scopes the adapter to that sub-page. Sibling tabs may pick different libraries, or none.
PluginHeaderAction - Reference
Plugin header action extensions provide plugin-scoped actions that appear in the page header. They are automatically scoped to the plugin that provides them and will appear in the header of all pages belonging to that plugin. Actions are lazy-loaded via a loader function that returns a React element.
Plugin Wrapper - Reference
Plugin wrappers allow you to install components that will wrap all elements rendered as part of a plugin. This can be useful if you need to add a global provider, for example for a query client. The provided wrapper will be rendered as separate elements for each wrapped plugin element, so be sure to use a central store like a Utility API if you want to share state between wrapper instances.
Extension blueprints in @backstage/plugin-app-react
SignInPage - Reference
Sign-in page extension have a single purpose - to implement a custom sign-in page. They are always attached to the app root extension and are rendered before the rest of the app until the user is signed in.
SwappableComponent - Reference
Swappable Components are extensions that are used to replace the implementations of components in the app and plugins.
Theme - Reference
Theme extensions provide custom themes for the app. They are always attached to the app extension and you can have any number of themes extensions installed in an app at once, letting the user choose which theme to use.
Icons - Reference
Icon bundle extensions provide the ability to replace or provide new icons to the app. You can use the above blueprint to make new extension instances which can be installed into the app.
Translation - Reference
Translation extension provide custom translation messages for the app. They can be used both to override the default english messages to custom ones, as well as provide translations for additional languages.
NavContent - Reference
Nav content extensions allow you to replace the entire navbar with your own component. They are always attached to the app nav extension.
Your custom component receives a navItems prop—a collection with take(id) and rest() methods for placing specific items in custom positions. Nav items are auto-discovered from page extensions, and metadata (title, icon) comes from page config, nav item extensions, or plugin defaults. Use navItems.take('page:home') to take a specific item by extension ID, and navItems.rest() to get all remaining items.
AppRootWrapper - Reference
App root wrapper extensions install React components that wrap the entire app root. Use them for global providers, such as a query client, that every plugin in the app needs. They are the replacement for providers that used to be bundled into a custom root router component.
Extension blueprints in @backstage/plugin-catalog-react/alpha
These are the extension blueprints provided by the Catalog plugin.
EntityCard - Example
Creates entity cards to be displayed on the entity pages of the catalog plugin. Exported as EntityCardBlueprint.
Avoid using convertLegacyEntityCardExtension from @backstage/core-compat-api to convert legacy entity card extensions to the new system. Instead, use the EntityCardBlueprint directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.
EntityContent - Example
Creates entity content to be displayed on the entity pages of the catalog plugin. Exported as EntityContentBlueprint.
Entity content is page content, not a page, so it never declares a page router adapter of its own. It already renders inside the adapter the entity page declared, one route match deeper. A second adapter here re-scopes to the entity page's mount and drops the tab's match. The same holds for EntityCardBlueprint.
Supports optional params such as group and icon to:
- group: string | false — associates the content with a tab group on the entity page (for example "overview", "quality", "deployment", or any custom id). You can override or disable this per-installation via app-config using
app.extensions[...].config.group, wherefalseremoves the grouping. - icon: string — sets the tab icon. Note: when providing a string, the icon is looked up via the app's IconsApi; make sure icon bundles are enabled/installed in your app (see the Icons blueprint reference above) so that the icon id you use is available.
To render icons in the entity page tabs, the page must also have icons enabled via app configuration. Set showNavItemIcons: true on the catalog entity page config (created via page:catalog/entity). Example:
app:
extensions:
# Entity page
- page:catalog/entity:
config:
# Enable tab- and group-icons
showNavItemIcons: true
# Optionally override default groups and their icons
groups:
- overview:
title: Overview
icon: dashboard
- documentation:
title: Docs
icon: description
Avoid using convertLegacyEntityContentExtension from @backstage/core-compat-api to convert legacy entity content extensions to the new system. Instead, use the EntityContentBlueprint directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.
EntityContextMenuItem - Example
Creates menu items inside the entity context menu. Exported as EntityContextMenuItemBlueprint.
See the API reference.
Extension blueprints in @backstage/plugin-search-react/alpha
These are the extension blueprints provided by the Search plugin.
SearchResultListItem - Example
Creates search result list items for different types of search results, to be displayed in search result lists. Exported as SearchResultListItemBlueprint.