Skip to main content
Version: Next

App Built-in Extensions

Built-in extensions are default app extensions that are always installed when you create a Backstage app.

Disable built-in extensions​

All built-in extensions can be disabled in the same way as you disable any other extension:

app-config.yaml
extensions:
# Disabling the built-in app root alert element
- app-root-element:app/alert-display: false
warning

Be careful when disabling built-in extensions, as there may be other extensions depending on their existence. For example, the built-in "alert display" extension displays messages retrieved via AlertApi and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from AlertApi.

Override built-in extensions​

You can override any built-in extension whenever their customizations, whether through configuration or input, do not meet a use case for your Backstage instance. Check out this documentation on how to override application extensions.

warning

Be aware there could be some implementation requirements to properly override an built-in extension, such as using same apis and do not remove inputs or configurations otherwise you can cause a side effect in other parts of the system that expects same minimal behavior.

Default built-in extensions​

App​

This extension is the first extension attached to the extension tree. It is responsible for receiving the application's root element and other Frontend framework inputs.

Inputs​

NameDescriptionTypeOptionalDefaultBlueprint
rootThe app root element.coreExtensionData.reactElementfalseThe App/Root extension output.No blueprint available, configure or override the App/Root extension.
apisThe app apis factories.ApiBlueprint.dataRefs.factoryfalseSee default apis.ApiBlueprint
themesThe app themes list.ThemeBlueprint.dataRefs.themefalseSee default themes.ThemeBlueprint
componentsThe app components list.SwappableComponentBlueprint.dataRefs.componentfalseSee default components.SwappableComponentBlueprint
translationsThe app translations list.TranslationBlueprint.dataRefs.translationfalse-TranslationBlueprint
iconsThe app icons list.IconBundleBlueprint.dataRefs.iconstrue-IconBundleBlueprint

Default theme extensions​

Extensions that provides default theme inputs for the App extension.

kindnamespacenameid
themeapplighttheme:app/light
themeappdarktheme:app/dark

Default components extensions​

Extensions that provides default components inputs for the App extension.

kindnamespacenameid
componentsappcore-progresscomponents:app/core-progress
componentsappcore-not-found-error-pagecomponents:app/core-not-found-error-page
componentsappcore-error-displaycomponents:app/core-error-display

Default apis extensions​

Extensions that provides default apis inputs for the App extension.

kindnamespacenameid
apicore.discovery-api:core.discovery
apicore.alert-api:core.alert
apicore.analytics-api:core.analytics
apicore.error-api:core.error
apicore.storage-api:core.storage
apicore.fetch-api:core.fetch
apicore.oauthrequest-api:core.oauthrequest
apicore.auth.google-api:core.auth.google
apicore.auth.microsoft-api:core.auth.microsoft
apicore.auth.github-api:core.auth.github
apicore.auth.okta-api:core.auth.okta
apicore.auth.gitlab-api:core.auth.gitlab
apicore.auth.onelogin-api:core.auth.onelogin
apicore.auth.bitbucket-api:core.auth.bitbucket
apicore.auth.bitbucket-server-api:core.auth.bitbucket-server
apicore.auth.atlassian-api:core.auth.atlassian
apiplugin.permission.api-api:plugin.permission.api

App root​

This is the extension that creates the app root element, so it renders root level components such as the sign-in page and layout.

Inputs​

NameDescriptionRequirementsOptionalDefaultBlueprint
signInPageA React component that should render the app sign-in page.Should call the onSignInSuccess prop when the user has been successfully authorized, otherwise the user will not be correctly redirected to the application home page.trueThe default AppRoot extension does not use a default component for this input, it bypasses the user authentication check and always renders all routes when a login page is not installed.SignInPageBlueprint
childrenA React component that renders the app sidebar and main content in a particular layout.-trueThe App/Layout extension output.No blueprint available, configure or override the App/Layout extension.
elementsReact elements to be rendered outside of the app layout, such as shared popups.-falseSee default elements.AppRootElementBlueprint
wrappersReact components that should wrap the root element.-true-AppRootWrapperBlueprint
note

The app root takes no router input. The app owns browser history and exposes it as AppHistoryApi. Existing pages retain implicit React Router v6 routing while they migrate. Development warnings identify use of this fallback. A page can render a page router adapter inside its lazily loaded component. See Scoped plugin routing.

Default app root elements extensions​

Alert Display​

An app root element extension that displays messages posted via the AlertApi.

kindnamespacenameid
app-root-elementappalert-displayapp-root-element:app/alert-display
Configurations​
KeyTypeDefault valueDescription
transientTimeoutMsnumber5000Time in milliseconds that a transient alert remains visible.

Messages appear as toasts at the bottom center of the screen. Remove the anchorOrigin setting from this extension's configuration if present; it is no longer supported and had no effect on toast positioning.

Override or disable the extension​

If you do not want to display alerts, disable this extension or if the available settings do not meet your needs, override this extension.

warning

The built-in "alert display" extension displays messages retrieved via AlertApi and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from AlertApi.

OAuth Request Dialog​

An app root element extension that renders the oauth request dialog, it is based on the oauthRequestApi.

kindnamespacenameid
app-root-elementappoauth-request-dialogapp-root-element:app/oauth-request-dialog

App layout​

Renders the app's sidebar and content in a specific layout.

kindnamespacenameid
-applayoutapp/layout

Inputs​

NameDescriptionTypeOptionalDefaultBlueprint
navA React element that renders the app sidebar.coreExtensionData.reactElementfalse-Override the App/Nav extension.
contentA React element that renders the app content.coreExtensionData.reactElementfalse-Override the App/Routes extension.

App nav​

Extension responsible for rendering the logo and items in the app's sidebar.

kindnamespacenameid
-appnavapp/nav

Inputs​

NameDescriptionTypeOptionalDefaultBlueprint
contentOverrides the default content of the navbar.NavContentBlueprint.dataRefs.componenttrue-NavContentBlueprint

App routes​

Renders a route element for each route received as input and a NotFoundErrorPage component.

kindnamespacenameid
-approutesapp/routes

Caveats​

Be careful when overriding this extension, as to do so correctly you must consider these implementation requirements:

  • This extension matches the app's top-level routes and resolves route refs to paths. It does not render page content, so replacing it does not let you change the router library used by a page or sub-page. A page picks its own routing library by rendering a page router adapter inside its loader — there is no extension input to attach one to;
  • Don't remove configs or inputs, just extend these things yourself with optional new options, otherwise it will cause breaking changes for extensions like PageBlueprint that depend on this type of inputs;
  • Remember to use the route refs for getting paths dynamically, otherwise if an adopter modifies a path through configuration, the route is not going to point to the configured path;
  • Adopters expect to be able to customize the NotFoundErrorPage component via Components API, you should render this component for routes not configured.

Configurations​

KeyTypeDefault valueDescription
redirects{ from: string, to: string }[]-A list of URL redirects. Navigation to from will redirect to to.
Configuring redirects​

You can configure redirects for the app/routes extension to automatically redirect users from one path to another. This is useful when restructuring your app's routes, for example after moving or renaming plugin pages.

app-config.yaml
app:
extensions:
- app/routes:
config:
redirects:
- from: /old-path
to: /new-path
- from: /legacy/page
to: /updated/page

Redirects are matched before any regular routes and use the replace strategy, so the old path will not appear in the browser history.

Inputs​

NameDescriptionTypeOptionalDefaultBlueprint
routesThe route objects list.{ path: coreExtensionData.routePath, ref: coreExtensionData.routeRef.optional(), element: coreExtensionData.reactElement }false-PageBlueprint