Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: 03-built-in-extensions.md

id: built-in-extensions title: App Built-in Extensions sidebar_label: Built-in extensions description: Configuring or overriding built-in extensions Built-in extensions are default app extensions that are always installed when you create a Backstage app. All built-in extensions can be disabled in the same way as you disable any other extension: ```yaml title="app-config.yaml" extensions: 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 and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`. ::: 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 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. ::: 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. | Name | Description | Type | Optional | Default | Extension creator | | | -- | | -- | | - | | root | The app root element. | | false | The extension output. | No creator available, configure or override the extension. | | apis | The app apis factories. | | false | See . | | | themes | The app themes list. | | false | See . | | | components | The app components list. | | false | See . | | | translations | The app translations list. | | false | - | | Extensions that provides default theme inputs for the `App` extension. | kind | namespace | name | id | | :: | :-: | :: | :: | | theme | app | light | `theme:app/light` | | theme | app | dark | `theme:app/dark` | Extensions that provides default components inputs for the `App` extension. | kind | namespace | name | id | | :--: | :-: | :--: | :-: | | components | app | core.components.progress | `components:app/core.components.progress` | | components | app | core.components.notFoundErrorPage | `components:app/core.components.notFoundErrorPage` | | components | app | core.components.errorBoundaryFallback | `components:app/core.components.errorBoundaryFallback` | Extensions that provides default apis inputs for the `App` extension. | kind | namespace | name | id | | :--: | :: | :--: | :: | | api | core.discovery | - | `api:core.discovery` | | api | core.alert | - | `api:core.alert` | | api | core.analytics | - | `api:core.analytics` | | api | core.error | - | `api:core.error` | | api | core.storage | - | `api:core.storage` | | api |

| - | `api:core.fetch` | | api | core.oauthrequest | - | `api:core.oauthrequest` | | api | core.auth.google | - | `api:core.auth.google` | | api | core.auth.microsoft | - | `api:core.auth.microsoft` | | api | core.auth.github | - | `api:core.auth.github` | | api | core.auth.okta | - | `api:core.auth.okta` | | api | core.auth.gitlab | - | `api:core.auth.gitlab` | | api | core.auth.onelogin | - | `api:core.auth.onelogin` | | api | core.auth.bitbucket | - | `api:core.auth.bitbucket` | | api | core.auth.bitbucket-server | - | `api:core.auth.bitbucket-server` | | api | core.auth.atlassian | - | `api:core.auth.atlassian` | | api | plugin.permission.api | - | `api:plugin.permission.api` | This is the extension that creates the app root element, so it renders root level components such as app router and layout. | Name | Description | Requirements | Optional | Default | Extension creator | | - | | -- | -- | -- | -- | | router | A React component that should manager the app routes context. | It must be one component or a custom component compatible with the 'react-router' library. | true | | | | signInPage | A 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. | true | The 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. | | | children | A React component that renders the app sidebar and main content in a particular layout. | - | false | The extension output. | No creator available, configure or override the extension. | | elements | React elements to be rendered outside of the app layout, such as shared popups. | - | false | See . | | | wrappers | React components that should wrap the root element. | - | true | - | | An app root element extension that displays messages posted via the . | kind | namespace | name | id | | :--: | :-: | :--: | :-: | | app-root-element | app | alert-display | `app-root-element:app/alert-display` | | Key | Type | Default value | Description | | -- | -- | -- | -- | | `transientTimeoutMs` | number | 5000 | Time in milliseconds to wait before displaying messages. | | `anchorOrigin` | { vertical: 'top' \| 'bottom', horizontal: 'left' \| 'center' \| 'right' } | { vertical: 'top', horizontal: 'center' } | Position on the screen where the message alert will be displayed. | If you do not want to display alerts, disable this extension or if the available settings do not meet your needs, override this

:::warning The built-in "alert display" extension displays messages retrieved via and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`. ::: An app root element extension that renders the oauth request dialog, it is based on the . | kind | namespace | name | id | | :--: | :-: | :: | :--: | | app-root-element | app | oauth-request-dialog | `app-root-element:app/oauth-request-dialog` | Renders the app's sidebar and content in a specific layout. | kind | namespace | name | id | | :--: | :-: | :-: | :-: | | - | app | layout | `app/layout` | | Name | Description | Type | Optional | Default | Extension creator | | - | | -- | -- | - | | | nav | A React element that renders the app sidebar. | | false | - | Override the `App/Nav` extension. | | content | A React element that renders the app content. | | false | - | Override the `App/Routes` extension. | Extension responsible for rendering the logo and items in the app's sidebar. | kind | namespace | name | id | | :--: | :-: | :--: | :-: | | - | app | nav | `app/nav` | | Name | Description | Type | Optional | Default | Extension creator | | -- | - | | -- | - | -- | | logos | A nav logos object. | | true | - | | | items | Nav items target objects. | | true | - | | Renders a route element for each route received as input and a `NotFoundErrorPage` component. | kind | namespace | name | id | | :--: | :-: | :-: | :-: | | - | app | routes | `app/routes` | Be careful when overriding this extension, as to do so correctly you must consider these implementation requirements: The routing system is managed by more than one extension, and they all use `react-router` behind the scenes. There are also some utilities that are based on the same `routing` library like `useRouteRefParams`. Therefore, you cannot use a different library without causing side effects in these other extensions and helper utilities; Don't remove configs or inputs, just extend these things yourself with optional new options, otherwise it will cause breaking changes for extensions like `createPageExtension` that depend on this type of inputs; Remember to user 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. | Name | Description | Type | Optional | Default | Extension creator | | | -- | - | -- | - | -- | | routes | The route objects list. | `{ path: coreExtensionData.routePath, ref: coreExtensionData.routeRef.optional(), element: coreExtensionData.reactElement }` | false | - | |