From 5a463b320cf2ec15a9d3a0a21dc5f11e929f68b3 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:24:35 +0100 Subject: [PATCH 01/17] docs: update frontend plugin docs to default to new frontend system Restructure plugin documentation so that the new frontend system is the default, unlabeled installation path. Old frontend system instructions are moved to a dedicated "Old Frontend System" section. Add a new "Installing Plugins" page to the frontend system docs covering package discovery, manual installation, and configuration. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- .../building-apps/05-installing-plugins.md | 67 ++++++++++ docs/getting-started/homepage.md | 52 +++----- microsite/sidebars.ts | 1 + plugins/home/README.md | 114 +++++++----------- plugins/mui-to-bui/README.md | 42 ++----- 5 files changed, 135 insertions(+), 141 deletions(-) create mode 100644 docs/frontend-system/building-apps/05-installing-plugins.md diff --git a/docs/frontend-system/building-apps/05-installing-plugins.md b/docs/frontend-system/building-apps/05-installing-plugins.md new file mode 100644 index 0000000000..bb78214382 --- /dev/null +++ b/docs/frontend-system/building-apps/05-installing-plugins.md @@ -0,0 +1,67 @@ +--- +id: installing-plugins +title: Installing Plugins +sidebar_label: Installing Plugins +description: How to install frontend plugins in a Backstage app +--- + +Frontend plugins are installed in your Backstage app by adding them as dependencies of your app package. Most of the time this is all you need to do, as the app will automatically discover and install the plugin. + +## Install a plugin package + +To install a plugin, add it as a dependency to your app package. For example, to install the catalog plugin: + +```bash title="From your Backstage root directory" +yarn --cwd packages/app add @backstage/plugin-catalog +``` + +If your app is set up with [package discovery](#package-discovery), the plugin will be automatically detected and installed in the app. No additional code changes are needed. + +## Package discovery + +Package discovery lets the app automatically discover and install plugins from the dependencies of your app package. This is enabled by setting `app.packages` to `all` in your `app-config.yaml`: + +```yaml title="app-config.yaml" +app: + packages: all +``` + +This is the recommended setup and is the default for all new Backstage apps. With this enabled, any plugin that is added as a dependency of your app package will be automatically discovered and installed. You can use include or exclude filters to control which packages are discovered: + +```yaml title="app-config.yaml" +app: + packages: + include: + - '@backstage/plugin-catalog' + - '@backstage/plugin-scaffolder' +``` + +```yaml title="app-config.yaml" +app: + packages: + exclude: + - '@backstage/plugin-catalog' +``` + +Package discovery requires that your app is built using the `@backstage/cli`, which is the default for all Backstage apps. + +## Manual installation + +If your app does not have [package discovery](#package-discovery) enabled, or if you need more control over the plugin installation, you can install plugins manually. This is done by importing the plugin and passing it to `createApp`: + +```tsx title="packages/app/src/App.tsx" +import { createApp } from '@backstage/frontend-defaults'; +import catalogPlugin from '@backstage/plugin-catalog/alpha'; + +const app = createApp({ + features: [catalogPlugin], +}); + +export default app.createRoot(); +``` + +Manual installation may also be necessary if you need to control the ordering of plugins, for example when customizing route priorities. Since manually installed plugins are deduplicated against automatically discovered ones, you can safely install a plugin both manually and through package discovery without causing conflicts. + +## Configuring installed plugins + +Once a plugin is installed, you can configure its extensions through the `app.extensions` section of your `app-config.yaml`. See [Configuring Extensions](./02-configuring-extensions.md) for details. diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 05e422610a..7085f9b082 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -24,39 +24,17 @@ Before we begin, make sure Now, let's get started by installing the home plugin and creating a simple homepage for your Backstage app. -## Setup Methods +## Setup -There are two ways to set up the home plugin, depending on which frontend system your Backstage app uses: - -1. **New Frontend System (Recommended)** - For apps using the new plugin system with extensions and blueprints -2. **Legacy Frontend System** - For existing apps using the legacy plugin architecture - -### New Frontend System Setup - -If your Backstage app uses the [new frontend system](../frontend-system/index.md), follow these steps: - -#### 1. Install the plugin +### 1. Install the plugin ```bash title="From your Backstage root directory" yarn --cwd packages/app add @backstage/plugin-home ``` -#### 2. Add the plugin to your app configuration +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](../frontend-system/building-apps/05-installing-plugins.md). -Update your `packages/app/src/app.tsx` to include the home plugin: - -```tsx title="packages/app/src/app.tsx" -import homePlugin from '@backstage/plugin-home/alpha'; - -const app = createApp({ - features: [ - // ... other plugins - homePlugin, - ], -}); -``` - -#### 3. Configure the homepage as your root route +### 2. Configure the homepage as your root route By default, the homepage will be available at `/home`. To make it your app's landing page at `/`, add this configuration to your `app-config.yaml`: @@ -70,7 +48,7 @@ app: The plugin will automatically add a "Home" navigation item to your sidebar and provide a basic homepage layout. -#### 4. Optional: Enable visit tracking +### 3. Optional: Enable visit tracking Visit tracking is an optional feature that allows users to see their recently visited and most visited pages on the homepage. This feature is **disabled by default** to give you control over what data is collected and stored. @@ -88,9 +66,9 @@ app: - app-root-element:home/visit-listener: true ``` -#### 5. Customizing your homepage +### 4. Customizing your homepage -The New Frontend System provides powerful customization options: +The home plugin provides powerful customization options: **Custom Homepage Layouts**: Use the `HomePageLayoutBlueprint` from `@backstage/plugin-home-react/alpha` to create custom homepage layouts with your own design and widget arrangements. A layout receives the installed widgets and is responsible for rendering them. If no custom layout is installed, the plugin provides a built-in default. @@ -98,17 +76,17 @@ The New Frontend System provides powerful customization options: For detailed instructions on creating custom layouts, registering widgets, and advanced configuration options, see the [Home plugin documentation](https://github.com/backstage/backstage/tree/master/plugins/home#readme). -### Legacy Frontend System Setup +## Old Frontend System -If your Backstage app uses the legacy frontend system, follow these steps: +This section covers how to set up the home plugin if your Backstage app still uses the old frontend system. -#### 1. Install the plugin +### 1. Install the plugin ```bash title="From your Backstage root directory" yarn --cwd packages/app add @backstage/plugin-home ``` -#### 2. Create a new HomePage component +### 2. Create a new HomePage component Inside your `packages/app` directory, create a new file where our new homepage component is going to live. Create `packages/app/src/components/home/HomePage.tsx` with the following initial code @@ -119,7 +97,7 @@ export const HomePage = () => ( ); ``` -#### 3. Update router for the root `/` route +### 3. Update router for the root `/` route If you don't have a homepage already, most likely you have a redirect setup to use the Catalog homepage as a homepage. @@ -156,7 +134,7 @@ const routes = ( ); ``` -#### 4. Update sidebar items +### 4. Update sidebar items Let's update the route for "Home" in the Backstage sidebar to point to the new homepage. We'll also add a Sidebar item to quickly open Catalog. @@ -206,13 +184,13 @@ That's it! You should now have _(although slightly boring)_ a homepage! In the next steps, we will make it interesting and useful! -### Use the default template +#### Use the default template There is a default homepage template ([storybook link](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template)) which we will use to set up our homepage. Checkout the [blog post announcement](https://backstage.io/blog/2022/01/25/backstage-homepage-templates) about the Backstage homepage templates for more information. -### Composing your homepage +#### Composing your homepage Composing a homepage is no different from creating a regular React Component, i.e. the App Integrator is free to include whatever content they like. However, diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts index 7e4e41591b..cf893d6895 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.ts @@ -597,6 +597,7 @@ export default { }, [ 'frontend-system/building-apps/index', + 'frontend-system/building-apps/installing-plugins', 'frontend-system/building-apps/configuring-extensions', 'frontend-system/building-apps/built-in-extensions', 'frontend-system/building-apps/plugin-conversion', diff --git a/plugins/home/README.md b/plugins/home/README.md index 04d1b8c2ec..e75f28e6ed 100644 --- a/plugins/home/README.md +++ b/plugins/home/README.md @@ -6,40 +6,19 @@ For App Integrators, the system is designed to be composable to give total freed ## Installation -If you have a standalone app (you didn't clone this repo), then do - ```bash # From your Backstage root directory yarn --cwd packages/app add @backstage/plugin-home ``` -## Getting started - -The home plugin supports both the new frontend system and the legacy system. - -### New Frontend System - -If you're using Backstage's new frontend system, add the plugin to your app: - -```ts -// packages/app/src/App.tsx -import homePlugin from '@backstage/plugin-home/alpha'; - -const app = createApp({ - features: [ - // ... other plugins - homePlugin, - // ... other plugins - ], -}); -``` +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). The plugin will automatically provide: - A homepage at `/home` with customizable widget grid - A "Home" navigation item in the sidebar -#### Creating Custom Homepage Layouts +## Creating Custom Homepage Layouts Use the `HomePageLayoutBlueprint` from `@backstage/plugin-home-react/alpha` to create custom homepage layouts. A layout receives the installed widgets and is @@ -86,7 +65,7 @@ const homeModule = createFrontendModule({ }); ``` -#### Visit Tracking (Optional) +## Visit Tracking (Optional) Visit tracking is an **optional feature** that must be explicitly enabled. When enabled, it provides intelligent storage fallbacks: @@ -112,12 +91,7 @@ app: ## Creating Homepage Widgets -Homepage widgets are React components that can be added to customizable home pages. The **key difference** between the new frontend system and legacy system is how these widget components are **registered and exported**: - -- **New Frontend System**: Use `HomePageWidgetBlueprint` to register widgets as extensions -- **Legacy System**: Use `createCardExtension` to export widgets as card components - -### New Frontend System +Homepage widgets are React components that can be added to customizable home pages. Create widgets using the `HomePageWidgetBlueprint`: @@ -156,26 +130,24 @@ const myWidget = HomePageWidgetBlueprint.make({ }); ``` -> **Example**: See [dev/index.tsx](dev/index.tsx) for a comprehensive example of creating multiple homepage widgets and layouts using the new frontend system. +> **Example**: See [dev/index.tsx](dev/index.tsx) for a comprehensive example of creating multiple homepage widgets and layouts. -### Legacy System - Widget Registration +## Contributing -In the legacy system, use the `createCardExtension` helper to create homepage widgets: +### Homepage Components -```tsx -import { createCardExtension } from '@backstage/plugin-home-react'; +We believe that people have great ideas for what makes a useful Home Page, and we want to make it easy for everyone to benefit from the effort you put in to create something cool for the Home Page. Therefore, a great way of contributing is by simply creating more Home Page Components that can then be used by everyone when composing their own Home Page. If they are tightly coupled to an existing plugin, it is recommended to allow them to live within that plugin, for convenience and to limit complex dependencies. On the other hand, if there's no clear plugin that the component is based on, it's also fine to contribute them into the [home plugin](/plugins/home/src/homePageComponents) -export const MyWidget = homePlugin.provide( - createCardExtension<{ defaultCategory?: 'programming' | 'any' }>({ - title: 'My Custom Widget', - components: () => import('./homePageComponents/MyWidget'), - }), -); -``` +Additionally, the API is at a very early state, so contributing additional use cases may expose weaknesses in the current solution that we may iterate on to provide more flexibility and ease of use for those who wish to develop components for the Home Page. -The `createCardExtension` provides error boundary and lazy loading, and accepts generics for custom props that App Integrators can configure. +### Homepage Templates -## Legacy System Setup +We are hoping that we together can build up a collection of Homepage templates. We therefore put together a place where we can collect all the templates for the Home Plugin in the [storybook](https://backstage.io/storybook/?path=/story/plugins-home-templates). +If you would like to contribute with a template, start by taking a look at the [DefaultTemplate storybook example](/packages/app-legacy/src/components/home/templates/DefaultTemplate.stories.tsx) or [CustomizableTemplate storybook example](/packages/app-legacy/src/components/home/templates/CustomizableTemplate.stories.tsx) to create your own, and then open a PR with your suggestion. + +## Old Frontend System + +This section covers the home plugin setup and usage for apps that still use the old frontend system. ### Setting up the Home Page @@ -204,13 +176,26 @@ import { homePage } from './components/home/HomePage'; // ... ``` -### Creating Components (Legacy) +### Creating Widgets (Old Frontend System) -In the legacy system, homepage components can be regular React components or wrapped with `createCardExtension` for additional features like error boundaries and lazy loading. Components created with `createCardExtension` are exported as card components that can be composed into homepage layouts. +In the old frontend system, use the `createCardExtension` helper to create homepage widgets: -### Composing a Home Page (Legacy) +```tsx +import { createCardExtension } from '@backstage/plugin-home-react'; -In the legacy system, composing a Home Page is done by creating regular React components. Components created with `createCardExtension` are rendered like so: +export const MyWidget = homePlugin.provide( + createCardExtension<{ defaultCategory?: 'programming' | 'any' }>({ + title: 'My Custom Widget', + components: () => import('./homePageComponents/MyWidget'), + }), +); +``` + +The `createCardExtension` provides error boundary and lazy loading, and accepts generics for custom props that App Integrators can configure. + +### Composing a Home Page (Old Frontend System) + +Composing a Home Page is done by creating regular React components. Components created with `createCardExtension` are rendered like so: ```tsx import Grid from '@material-ui/core/Grid'; @@ -227,7 +212,7 @@ export const homePage = ( Additionally, the App Integrator is provided an escape hatch in case the way the card is rendered does not fit their requirements. They may optionally pass the `Renderer`-prop, which will receive the `title`, `content` and optionally `actions`, `settings` and `contextProvider`, if they exist for the component. This allows the App Integrator to render the content in any way they want. -## Customizable home page +### Customizable Home Page (Old Frontend System) If you want to allow users to customize the components that are shown in the home page, you can use CustomHomePageGrid component. By adding the allowed components inside the grid, the user can add, configure, remove and move the components around in their @@ -259,7 +244,7 @@ export const homePage = ( > [!NOTE] > You can provide a title to the grid by passing it as a prop: ``. This will be displayed as a header above the grid layout. -### Creating Customizable Components +#### Creating Customizable Components (Old Frontend System) The custom home page can use the default components created by using the default `createCardExtension` method but if you want to add additional configuration like component size or settings, you can define those in the `layout` @@ -317,7 +302,7 @@ Available home page properties that are used for homepage widgets are: | `layout.height.maxRows` | integer | Maximum height of the widget (1-12) | | `settings.schema` | object | Customization settings of the widget, see below | -#### Widget Specific Settings +#### Widget Specific Settings (Old Frontend System) To define settings that the users can change for your component, you should define the `layout` and `settings` properties. The `settings.schema` object should follow @@ -369,7 +354,7 @@ Each widget has its own settings and the setting values are passed to the underl In case your `CardExtension` had `Settings` component defined, it will automatically disappear when you add the `settingsSchema` to the component data structure. -### Adding Default Layout +#### Adding Default Layout (Old Frontend System) You can set the default layout of the customizable home page by passing configuration to the `CustomHomepageGrid` component: @@ -391,7 +376,7 @@ const defaultConfig = [ ``` -## Page visit homepage component (HomePageTopVisited / HomePageRecentlyVisited) +### Page Visit Homepage Component (Old Frontend System) This component shows the homepage user a view for "Recently visited" or "Top visited". Being provided by the `` and `` component, see it in use on a homepage example below: @@ -505,11 +490,11 @@ home: In order to validate the config you can use `backstage/cli config:check` -### Customizing the VisitList +#### Customizing the VisitList (Old Frontend System) If you want more control over the recent and top visited lists, you can write your own functions to transform the path names and determine which visits to save. You can also enrich each visit with other fields and customize the chip colors/labels in the visit lists. -#### Transform Pathname Function +##### Transform Pathname Function Provide a `transformPathname` function to transform the pathname before it's processed for visit tracking. This can be used for transforming the pathname for the visit (before any other consideration). As an example, you can treat multiple sub-path visits to be counted as a singular path, e.g. `/entity-path/sub1` , `/entity-path/sub-2`, `/entity-path/sub-2/sub-sub-2` can all be mapped to `/entity-path` so visits to any of those routes are all counted as the same. @@ -548,7 +533,7 @@ export const apis: AnyApiFactory[] = [ ]; ``` -#### Can Save Function +##### Can Save Function Provide a `canSave` function to determine which visits should be tracked and saved. This allows you to conditionally save visits to the list: @@ -586,7 +571,7 @@ export const apis: AnyApiFactory[] = [ ]; ``` -#### Enrich Visit Function +##### Enrich Visit Function You can also add the `enrichVisit` function to put additional values on each `Visit`. The values could later be used to customize the chips in the `VisitList`. For example, you could add the entity `type` on the `Visit` so that `type` is used for labels instead of `kind`. @@ -637,7 +622,7 @@ export const apis: AnyApiFactory[] = [ ]; ``` -#### Custom Chip Colors and Labels +##### Custom Chip Colors and Labels To provide your own chip colors and/or labels for the recent and top visited lists, wrap the components in `VisitDisplayProvider` with `getChipColor` and `getChipLabel` functions. The colors provided will be used instead of the hard coded [`colorVariants`](https://github.com/backstage/backstage/blob/2da352043425bcab4c4422e4d2820c26c0a83382/packages/theme/src/base/pageTheme.ts#L46) provided via `@backstage/theme`. @@ -680,16 +665,3 @@ export default function HomePage() { ); } ``` - -## Contributing - -### Homepage Components - -We believe that people have great ideas for what makes a useful Home Page, and we want to make it easy for everyone to benefit from the effort you put in to create something cool for the Home Page. Therefore, a great way of contributing is by simply creating more Home Page Components that can then be used by everyone when composing their own Home Page. If they are tightly coupled to an existing plugin, it is recommended to allow them to live within that plugin, for convenience and to limit complex dependencies. On the other hand, if there's no clear plugin that the component is based on, it's also fine to contribute them into the [home plugin](/plugins/home/src/homePageComponents) - -Additionally, the API is at a very early state, so contributing additional use cases may expose weaknesses in the current solution that we may iterate on to provide more flexibility and ease of use for those who wish to develop components for the Home Page. - -### Homepage Templates - -We are hoping that we together can build up a collection of Homepage templates. We therefore put together a place where we can collect all the templates for the Home Plugin in the [storybook](https://backstage.io/storybook/?path=/story/plugins-home-templates). -If you would like to contribute with a template, start by taking a look at the [DefaultTemplate storybook example](/packages/app-legacy/src/components/home/templates/DefaultTemplate.stories.tsx) or [CustomizableTemplate storybook example](/packages/app-legacy/src/components/home/templates/CustomizableTemplate.stories.tsx) to create your own, and then open a PR with your suggestion. diff --git a/plugins/mui-to-bui/README.md b/plugins/mui-to-bui/README.md index d964b4827f..d5f08e6d03 100644 --- a/plugins/mui-to-bui/README.md +++ b/plugins/mui-to-bui/README.md @@ -6,19 +6,22 @@ The Backstage UI Themer helps you convert an existing MUI v5 theme into Backstag ## Installation -### 1) Add the dependency to your app - -Run this from your Backstage repo root: +Add the dependency to your app: ```bash yarn --cwd packages/app add @backstage/plugin-mui-to-bui ``` -### 2) Wire it up depending on your frontend system +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). -#### Old frontend system (legacy `App.tsx` with ``) +## Accessing the Themer page -Add a route for the page in your app: +- Navigate to `/mui-to-bui` in your Backstage app (for example `http://localhost:3000/mui-to-bui`). +- Optional: Add a sidebar/link in your app that points to `/mui-to-bui` if you want a permanent navigation entry. + +## Old Frontend System + +If your Backstage app uses the old frontend system, add a route for the page in your app: ```tsx // packages/app/src/App.tsx @@ -34,30 +37,3 @@ export const App = () => ( ); ``` - -#### New frontend system - -If package discovery is enabled in your app, this plugin is picked up automatically after installation — no code changes required. Just navigate to `/mui-to-bui`. - -If you prefer explicit registration (or don't use discovery), register the plugin as a feature. The page route (`/mui-to-bui`) is provided by the plugin. - -```tsx -// packages/app/src/App.tsx (or your app entry where you call createApp) -import React from 'react'; -import { createApp } from '@backstage/frontend-defaults'; -import buiThemerPlugin from '@backstage/plugin-mui-to-bui'; - -const app = createApp({ - features: [ - // ...other features - buiThemerPlugin, - ], -}); - -export default app.createRoot(); -``` - -## Accessing the Themer page - -- Navigate to `/mui-to-bui` in your Backstage app (for example `http://localhost:3000/mui-to-bui`). -- Optional: Add a sidebar/link in your app that points to `/mui-to-bui` if you want a permanent navigation entry. From c202cd698ae4bc3899e1c4ca130c07ecb323d347 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:35:12 +0100 Subject: [PATCH 02/17] docs(catalog): update README for new frontend system as default Move old frontend system wiring instructions to an "Old Frontend System" section. The default installation path now uses package discovery with no manual wiring needed. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/catalog/README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index e8de1118ac..993f0e34f2 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -15,13 +15,17 @@ To check if you already have the package, look under `@backstage/plugin-catalog`. The instructions below walk through restoring the plugin, if you previously removed it. -### Install the package - ```bash # From your Backstage root directory yarn --cwd packages/app add @backstage/plugin-catalog ``` +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). + +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + ### Add the plugin to your `packages/app` Add the two pages that the catalog plugin provides to your app. You can choose From 5f80ce482d249c614ff6c43082cd350fe9012fd1 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:35:40 +0100 Subject: [PATCH 03/17] docs(catalog-import): update README for new frontend system as default Move old frontend system wiring instructions to an "Old Frontend System" section. The default installation path now uses package discovery with no manual wiring needed. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/catalog-import/README.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/plugins/catalog-import/README.md b/plugins/catalog-import/README.md index d4ede8af7b..f8174b63ff 100644 --- a/plugins/catalog-import/README.md +++ b/plugins/catalog-import/README.md @@ -15,22 +15,14 @@ Some features are not yet available for all supported Git providers. ## Getting Started -1. Install the Catalog Import Plugin: +Install the Catalog Import Plugin: ```bash # From your Backstage root directory yarn --cwd packages/app add @backstage/plugin-catalog-import ``` -2. Add the `CatalogImportPage` extension to the app: - -```tsx -// packages/app/src/App.tsx - -import { CatalogImportPage } from '@backstage/plugin-catalog-import'; - -} />; -``` +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Customizations @@ -104,6 +96,18 @@ Following React components accept optional props for providing custom example en /> ``` +## Old Frontend System + +If your Backstage app uses the old frontend system, add the `CatalogImportPage` extension to the app: + +```tsx +// packages/app/src/App.tsx + +import { CatalogImportPage } from '@backstage/plugin-catalog-import'; + +} />; +``` + ## Development Use `yarn start` to run a [development version](./dev/index.tsx) of the plugin that can be used to validate each flow with mocked data. From 2082c44b4539806ed2b4f8850f7e8e3651cf50b0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:36:12 +0100 Subject: [PATCH 04/17] docs(scaffolder): update README for new frontend system as default Move old frontend system wiring instructions to an "Old Frontend System" section. The default installation path now uses package discovery with no manual wiring needed. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/scaffolder/README.md | 110 ++++++++++++++++++----------------- 1 file changed, 57 insertions(+), 53 deletions(-) diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index 0a79d8afc0..ff09796033 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -15,13 +15,68 @@ To check if you already have the package, look under `@backstage/plugin-scaffolder`. The instructions below walk through restoring the plugin, if you previously removed it. -### Install the package - ```bash # From your Backstage root directory yarn --cwd packages/app add @backstage/plugin-scaffolder ``` +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). + +### Troubleshooting + +If you encounter the [issue of closing EventStream](https://github.com/backstage/backstage/issues/5535) +which auto-updates logs during task execution, you can enable long polling. To do so, +update your `packages/app/src/apis.ts` file to register a `ScaffolderClient` with the +`useLongPollingLogs` set to `true`. By default, it is `false`. + +```typescript +import { + createApiFactory, + discoveryApiRef, + fetchApiRef, + identityApiRef, +} from '@backstage/core-plugin-api'; +import { + scaffolderApiRef, + ScaffolderClient, +} from '@backstage/plugin-scaffolder'; + +export const apis: AnyApiFactory[] = [ + createApiFactory({ + api: scaffolderApiRef, + deps: { + discoveryApi: discoveryApiRef, + identityApi: identityApiRef, + scmIntegrationsApi: scmIntegrationsApiRef, + fetchApi: fetchApiRef, + }, + factory: ({ scmIntegrationsApi, discoveryApi, identityApi, fetchApi }) => + new ScaffolderClient({ + discoveryApi, + identityApi, + scmIntegrationsApi, + fetchApi, + useLongPollingLogs: true, + }), + }), + // ... other factories +``` + +This replaces the default implementation of the `scaffolderApiRef`. + +### Local development + +When you develop a new template, action or new ``, then we recommend +to launch the plugin locally using the `createDevApp` of the `./dev/index.tsx` file for testing/Debugging purposes + +To play with it, open a terminal and run the command: `yarn start` within the `./plugins/scaffolder` folder + +**NOTE:** Don't forget to open a second terminal and to launch the backend or [backend-next](../../docs/backend-system/index.md) there, using `yarn start` and to specify the locations of the templates to play with ! + +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + ### Add the plugin to your `packages/app` Add the root page that the scaffolder plugin provides to your app. You can @@ -78,57 +133,6 @@ export const Root = ({ children }: PropsWithChildren<{}>) => ( ``` -### Troubleshooting - -If you encounter the [issue of closing EventStream](https://github.com/backstage/backstage/issues/5535) -which auto-updates logs during task execution, you can enable long polling. To do so, -update your `packages/app/src/apis.ts` file to register a `ScaffolderClient` with the -`useLongPollingLogs` set to `true`. By default, it is `false`. - -```typescript -import { - createApiFactory, - discoveryApiRef, - fetchApiRef, - identityApiRef, -} from '@backstage/core-plugin-api'; -import { - scaffolderApiRef, - ScaffolderClient, -} from '@backstage/plugin-scaffolder'; - -export const apis: AnyApiFactory[] = [ - createApiFactory({ - api: scaffolderApiRef, - deps: { - discoveryApi: discoveryApiRef, - identityApi: identityApiRef, - scmIntegrationsApi: scmIntegrationsApiRef, - fetchApi: fetchApiRef, - }, - factory: ({ scmIntegrationsApi, discoveryApi, identityApi, fetchApi }) => - new ScaffolderClient({ - discoveryApi, - identityApi, - scmIntegrationsApi, - fetchApi, - useLongPollingLogs: true, - }), - }), - // ... other factories -``` - -This replaces the default implementation of the `scaffolderApiRef`. - -### Local development - -When you develop a new template, action or new ``, then we recommend -to launch the plugin locally using the `createDevApp` of the `./dev/index.tsx` file for testing/Debugging purposes - -To play with it, open a terminal and run the command: `yarn start` within the `./plugins/scaffolder` folder - -**NOTE:** Don't forget to open a second terminal and to launch the backend or [backend-next](../../docs/backend-system/index.md) there, using `yarn start` and to specify the locations of the templates to play with ! - ## Links - [scaffolder-backend](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend) From 348141b8ee8e587bf44ceee4236ee7e0a3a88b1d Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:36:50 +0100 Subject: [PATCH 05/17] docs(user-settings): update README for new frontend system as default Move old frontend system wiring instructions to an "Old Frontend System" section. The default installation path now uses package discovery with no manual wiring needed. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/user-settings/README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/plugins/user-settings/README.md b/plugins/user-settings/README.md index a27e5ca524..b4c283d275 100644 --- a/plugins/user-settings/README.md +++ b/plugins/user-settings/README.md @@ -11,7 +11,20 @@ be used in the frontend as a persistent alternative to the builtin `WebStorage`. Please see [the backend README](https://github.com/backstage/backstage/tree/master/plugins/user-settings-backend) for installation instructions. -## Components Usage +## Installation + +```bash +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-user-settings +``` + +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). + +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + +### Components Usage Add the item to the Sidebar: From 96662b763ef492ea0e5c3ff2e86e13fff477306e Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:37:33 +0100 Subject: [PATCH 06/17] docs(devtools): update README for new frontend system as default Move old frontend system wiring instructions to an "Old Frontend System" section. The default installation path now uses package discovery with no manual wiring needed. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/devtools/README.md | 76 +++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 37 deletions(-) diff --git a/plugins/devtools/README.md b/plugins/devtools/README.md index b23c35d4dd..54aa1f492d 100644 --- a/plugins/devtools/README.md +++ b/plugins/devtools/README.md @@ -66,42 +66,14 @@ You need to setup the [DevTools backend plugin](../devtools-backend/README.md) b ### Frontend -To setup the DevTools frontend you'll need to do the following steps: +Install the `@backstage/plugin-devtools` package in your frontend app: -1. First we need to add the `@backstage/plugin-devtools` package to your frontend app: +```sh +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-devtools +``` - ```sh - # From your Backstage root directory - yarn --cwd packages/app add @backstage/plugin-devtools - ``` - -2. Now open the `packages/app/src/App.tsx` file -3. Then after all the import statements add the following line: - - ```ts - import { DevToolsPage } from '@backstage/plugin-devtools'; - ``` - -4. In this same file just before the closing ``, this will be near the bottom of the file, add this line: - - ```ts - } /> - ``` - -5. Next open the `packages/app/src/components/Root/Root.tsx` file -6. We want to add this icon import after all the existing import statements: - - ```ts - import BuildIcon from '@material-ui/icons/Build'; - ``` - -7. Then add this line just after the `` line: - - ```ts - - ``` - -8. Now run `yarn start` from the root of your project and you should see the DevTools option show up just below Settings in your sidebar and clicking on it will get you to the [Info tab](#info) +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Customizing @@ -166,8 +138,6 @@ You can also add tabs to show content from other plugins that fit well with the #### Catalog Unprocessed Entities Tab -##### New Frontend System - Create an extension and/or load a 3rd party extension to add additional tabs. ```shell @@ -197,7 +167,7 @@ const appFeature = createFrontendModule({ }); ``` -##### Old System +##### Old Frontend System Here's how to add the Catalog Unprocessed Entities tab: @@ -230,6 +200,38 @@ Here's how to add the Catalog Unprocessed Entities tab: 4. Now run `yarn start` and navigate to the DevTools you'll see a new tab for Unprocessed Entities +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + +1. Open the `packages/app/src/App.tsx` file +2. Then after all the import statements add the following line: + + ```ts + import { DevToolsPage } from '@backstage/plugin-devtools'; + ``` + +3. In this same file just before the closing ``, this will be near the bottom of the file, add this line: + + ```ts + } /> + ``` + +4. Next open the `packages/app/src/components/Root/Root.tsx` file +5. We want to add this icon import after all the existing import statements: + + ```ts + import BuildIcon from '@material-ui/icons/Build'; + ``` + +6. Then add this line just after the `` line: + + ```ts + + ``` + +7. Now run `yarn start` from the root of your project and you should see the DevTools option show up just below Settings in your sidebar and clicking on it will get you to the [Info tab](#info) + ## Permissions The DevTools plugin supports the [permissions framework](https://backstage.io/docs/permissions/overview), the following sections outline how you can use them with the assumption that you have the permissions framework setup and working. From ae71853b45b393cc104e0fba5f7ecc60acb3131c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:38:40 +0100 Subject: [PATCH 07/17] docs(api-docs): update README for new frontend system as default Add new frontend system installation as the default path with package discovery. Move old frontend system wiring to an "Old Frontend System" section. Update README-alpha.md to be an extension reference rather than experimental documentation. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/api-docs/README-alpha.md | 6 +- plugins/api-docs/README.md | 151 ++++++++++++++++++------------- 2 files changed, 88 insertions(+), 69 deletions(-) diff --git a/plugins/api-docs/README-alpha.md b/plugins/api-docs/README-alpha.md index 0f19f51b23..a4c3979787 100644 --- a/plugins/api-docs/README-alpha.md +++ b/plugins/api-docs/README-alpha.md @@ -1,8 +1,6 @@ -# Api Docs +# Api Docs - Extension Reference -> [!WARNING] -> This documentation is made for those using the experimental new Frontend system. -> If you are not using the new frontend system, please go [here](./README.md). +This page contains detailed documentation for all extensions provided by the `@backstage/plugin-api-docs` plugin. For general information about the plugin, see the [README](./README.md). This is an extension for the catalog plugin that provides components to discover and display API entities. APIs define the interface between components, see the [system model](https://backstage.io/docs/features/software-catalog/system-model) for details. diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index 139a97d4c8..f6f52cbcae 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -1,8 +1,5 @@ # API Documentation -> Disclaimer: -> If you are looking for documentation on the experimental new frontend system support, please go [here](./README-alpha.md). - This is an extension for the catalog plugin that provides components to discover and display API entities. APIs define the interface between components, see the [system model](https://backstage.io/docs/features/software-catalog/system-model) for details. They are defined in machine readable formats and provide a human readable documentation. @@ -28,77 +25,32 @@ To link that a component provides or consumes an API, see the [`providesApis`](h > The plugin is already added when using `npx @backstage/create-app` so you can skip these steps. -1. Install the API docs plugin - ```bash # From your Backstage root directory yarn --cwd packages/app add @backstage/plugin-api-docs ``` -2. Add the `ApiExplorerPage` extension to the app: +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). -```tsx -// In packages/app/src/App.tsx +You can enable entity cards and tabs on the catalog entity page through configuration: -import { ApiExplorerPage } from '@backstage/plugin-api-docs'; - -} />; +```yaml +# app-config.yaml +app: + extensions: + - entity-card:api-docs/providing-components: + config: + filter: + kind: api + - entity-card:api-docs/consuming-components: + config: + filter: + kind: api + - entity-content:api-docs/definition + - entity-content:api-docs/apis ``` -3. Add one of the provided widgets to the EntityPage: - -```tsx -// packages/app/src/components/catalog/EntityPage.tsx - -import { - EntityAboutCard, - EntityApiDefinitionCard, - EntityConsumingComponentsCard, - EntityProvidingComponentsCard, -} from '@backstage/plugin-api-docs'; - -const apiPage = ( - - - - - - - - - - - - - - - - - - - - - - - - - - - -); - -// ... - -export const entityPage = ( - - // ... - - // ... - -); -``` - -There are other components to discover in [`./src/components`](./src/components) that are also added by the default app. +For the full list of available extensions and their configuration options, see the [README-alpha.md](./README-alpha.md). ## Customizations @@ -388,6 +340,75 @@ import { ApiExplorerPage } from '@backstage/plugin-api-docs'; />; ``` +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + +1. Add the `ApiExplorerPage` extension to the app: + +```tsx +// In packages/app/src/App.tsx + +import { ApiExplorerPage } from '@backstage/plugin-api-docs'; + +} />; +``` + +2. Add one of the provided widgets to the EntityPage: + +```tsx +// packages/app/src/components/catalog/EntityPage.tsx + +import { + EntityAboutCard, + EntityApiDefinitionCard, + EntityConsumingComponentsCard, + EntityProvidingComponentsCard, +} from '@backstage/plugin-api-docs'; + +const apiPage = ( + + + + + + + + + + + + + + + + + + + + + + + + + + + +); + +// ... + +export const entityPage = ( + + // ... + + // ... + +); +``` + +There are other components to discover in [`./src/components`](./src/components) that are also added by the default app. + ## Links - [The Backstage homepage](https://backstage.io) From 7a2761b7ce262a6105a11b7e756056facd789cdd Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:39:29 +0100 Subject: [PATCH 08/17] docs(catalog-graph): update README for new frontend system as default Add new frontend system installation as the default path with package discovery. Move old frontend system wiring to an "Old Frontend System" section. Update README-alpha.md to be an extension reference rather than experimental documentation. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/catalog-graph/README-alpha.md | 6 +- plugins/catalog-graph/README.md | 112 ++++++++++++++------------ 2 files changed, 64 insertions(+), 54 deletions(-) diff --git a/plugins/catalog-graph/README-alpha.md b/plugins/catalog-graph/README-alpha.md index 6242e9cc39..90481caca6 100644 --- a/plugins/catalog-graph/README-alpha.md +++ b/plugins/catalog-graph/README-alpha.md @@ -1,8 +1,6 @@ -# Catalog Graph +# Catalog Graph - Extension Reference -> [!WARNING] -> This documentation is made for those using the experimental new Frontend system. -> If you are not using the new frontend system, please go [here](./README.md). +This page contains detailed documentation for all extensions provided by the `@backstage/plugin-catalog-graph` plugin. For general information about the plugin, see the [README](./README.md). The Catalog graph plugin helps you to visualize the relations between entities, like ownership, grouping or API relationships. It comes with these features: diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md index b411d4d868..38ea902271 100644 --- a/plugins/catalog-graph/README.md +++ b/plugins/catalog-graph/README.md @@ -1,8 +1,5 @@ # catalog-graph -> Disclaimer: -> If you are looking for documentation on the experimental new frontend system support, please go [here](./README-alpha.md). - Welcome to the catalog graph plugin! The catalog graph visualizes the relations between entities, like ownership, grouping or API relationships. @@ -23,58 +20,25 @@ The plugin comes with these features: - `EntityRelationsGraph`: A react component that can be used to build own customized entity relation graphs. -## Usage +## Installation -To use the catalog graph plugin, you have to add some things to your Backstage app: +```sh +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-catalog-graph +``` -1. Add a dependency to your `packages/app/package.json`: - ```sh - # From your Backstage root directory - yarn --cwd packages/app add @backstage/plugin-catalog-graph - ``` -2. Add the `CatalogGraphPage` to your `packages/app/src/App.tsx`: +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). - ```typescript - - … - } />… - - ``` +To enable the entity relations graph card on the catalog entity page, add the following configuration: - You can configure the page to open with some initial filters: +```yaml +# app-config.yaml +app: + extensions: + - entity-card:catalog-graph/relations +``` - ```typescript - - } - /> - ``` - -3. Bind the external routes of the `catalogGraphPlugin` in your `packages/app/src/App.tsx`: - - ```typescript - bindRoutes({ bind }) { - … - bind(catalogGraphPlugin.externalRoutes, { - catalogEntity: catalogPlugin.routes.catalogEntity, - }); - … - } - ``` - -4. Add `EntityCatalogGraphCard` to any entity page that you want in your `packages/app/src/components/catalog/EntityPage.tsx`: - - ```typescript - - - - ``` +For the full list of available extensions and their configuration options, see the [README-alpha.md](./README-alpha.md). ### Customizing the UI @@ -177,6 +141,54 @@ import { }), ``` +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + +1. Add the `CatalogGraphPage` to your `packages/app/src/App.tsx`: + + ```typescript + + … + } />… + + ``` + + You can configure the page to open with some initial filters: + + ```typescript + + } + /> + ``` + +2. Bind the external routes of the `catalogGraphPlugin` in your `packages/app/src/App.tsx`: + + ```typescript + bindRoutes({ bind }) { + … + bind(catalogGraphPlugin.externalRoutes, { + catalogEntity: catalogPlugin.routes.catalogEntity, + }); + … + } + ``` + +3. Add `EntityCatalogGraphCard` to any entity page that you want in your `packages/app/src/components/catalog/EntityPage.tsx`: + + ```typescript + + + + ``` + ## Development Run `yarn` in the root of this plugin to install all dependencies and then `yarn start` to run a [development version](./dev/index.tsx) of this plugin. From 8c4a718067de3a50ba9d68f2f4a7850d358f1d0b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:40:04 +0100 Subject: [PATCH 09/17] docs(org): update README for new frontend system as default Add new frontend system installation as the default path with package discovery and extension configuration. Move old frontend system wiring to an "Old Frontend System" section. Update README-alpha.md to be an extension reference rather than experimental documentation. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/org/README-alpha.md | 6 ++---- plugins/org/README.md | 30 +++++++++++++++++++++++++++--- 2 files changed, 29 insertions(+), 7 deletions(-) diff --git a/plugins/org/README-alpha.md b/plugins/org/README-alpha.md index 28e274b58c..db8a84f35c 100644 --- a/plugins/org/README-alpha.md +++ b/plugins/org/README-alpha.md @@ -1,8 +1,6 @@ -# Org Plugin +# Org Plugin - Extension Reference -> [!WARNING] -> This documentation is made for those using the experimental new Frontend system. -> If you are not using the new frontend system, please go [here](./README.md). +This page contains detailed documentation for all extensions provided by the `@backstage/plugin-org` plugin. For general information about the plugin, see the [README](./README.md). This is a plugin that extends the Catalog entity page with some users and groups overview cards: diff --git a/plugins/org/README.md b/plugins/org/README.md index 9cf165f06d..edf7cc4a89 100644 --- a/plugins/org/README.md +++ b/plugins/org/README.md @@ -1,8 +1,5 @@ # Org Plugin for Backstage -> Disclaimer: -> If you are looking for documentation on the experimental new frontend system support, please go [here](./README-alpha.md). - ## Features - Show Group Page @@ -21,6 +18,33 @@ Here's an example of what the User Profile looks like: ![Group Page example](./docs/user-profile-example.png) +## Installation + +```bash +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-org +``` + +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). + +You can enable entity cards on the catalog entity page through configuration: + +```yaml +# app-config.yaml +app: + extensions: + - entity-card:org/group-profile + - entity-card:org/members-list + - entity-card:org/ownership + - entity-card:org/user-profile +``` + +For the full list of available extensions and their configuration options, see the [README-alpha.md](./README-alpha.md). + +## Old Frontend System + +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. + ### MyGroupsSidebarItem The MyGroupsSidebarItem provides quick access to the group(s) the logged in user is a member of directly in the sidebar. From db7d147d175dba9df7429a8f83a9977c0707c573 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 11:40:38 +0100 Subject: [PATCH 10/17] docs(catalog-unprocessed-entities): update README for new frontend system as default Make package discovery the default installation path. Move old frontend system wiring to an "Old Frontend System" section and remove the separate "Integrating with the New Frontend System" section. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- .../catalog-unprocessed-entities/README.md | 55 ++++++------------- 1 file changed, 16 insertions(+), 39 deletions(-) diff --git a/plugins/catalog-unprocessed-entities/README.md b/plugins/catalog-unprocessed-entities/README.md index b39a4a7ad4..13bca8b04f 100644 --- a/plugins/catalog-unprocessed-entities/README.md +++ b/plugins/catalog-unprocessed-entities/README.md @@ -32,7 +32,22 @@ Requires the `@backstage/plugin-catalog-backend-module-unprocessed` module to be yarn --cwd packages/app add @backstage/plugin-catalog-unprocessed-entities ``` -Import into your `App.tsx` and include into the `` component: +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). + +You can optionally add unprocessed entities as a tab in DevTools through configuration: + +```yaml +app: + extensions: + # Enable the catalog-unprocessed-entities tab in devtools + - devtools-content:catalog-unprocessed-entities: true + # Disable the catalog-unprocessed-entities element outside devtools including the sidebar + - page:catalog-unprocessed-entities: false +``` + +## Old Frontend System + +If your Backstage app uses the old frontend system, import into your `App.tsx` and include into the `` component: ```tsx title="packages/app/src/App.tsx" import { CatalogUnprocessedEntitiesPage } from '@backstage/plugin-catalog-unprocessed-entities'; @@ -44,44 +59,6 @@ import { CatalogUnprocessedEntitiesPage } from '@backstage/plugin-catalog-unproc />; ``` -### Integrating with the New Frontend System - -Follow this section if you are using Backstage's [new frontend system](https://backstage.io/docs/frontend-system/). - -Import `catalogUnprocessedEntitiesPlugin` in your `App.tsx` and add it to your app's `features` array: - -```typescript -import catalogUnprocessedEntitiesPlugin from '@backstage/plugin-catalog-unprocessed-entities'; -import { unprocessedEntitiesDevToolsContent } from '@backstage/plugin-catalog-unprocessed-entities/alpha'; - -// Optionally add unprocessed entities route to devtools -const devtoolsPluginUnprocessed = createFrontendModule({ - pluginId: 'catalog-unprocessed-entities', - extensions: [unprocessedEntitiesDevToolsContent], -}); - -export const app = createApp({ - features: [ - // ... - catalogUnprocessedEntitiesPlugin, - - // Optionally add unprocessed entities route to devtools - devtoolsPluginUnprocessed, - devtoolsPlugin, // devtools plugin needs to be added too, if autodiscover is disabled - // ... - ], -}); -``` - -```yaml -app: - extensions: - # Enable the catalog-unprocessed-entities tab in devtools - - devtools-content:catalog-unprocessed-entities: true - # Disable the catalog-unprocessed-entities element outside devtools including the sidebar - - page:catalog-unprocessed-entities: false -``` - ## Customization If you want to use the provided endpoints in a different way, you can use the ApiRef doing the following: From adc075f55739bc478451fcb2604b7fc079dd3a0b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 12:07:40 +0100 Subject: [PATCH 11/17] docs(kubernetes): update README for new frontend system as default Add install command and package discovery blurb. Restructure so the extension configuration is the default setup path, removing the explicit "New Frontend System" labeling. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/kubernetes/README.md | 49 +++++++++++++----------------------- 1 file changed, 18 insertions(+), 31 deletions(-) diff --git a/plugins/kubernetes/README.md b/plugins/kubernetes/README.md index e2c967902b..42410ca92d 100644 --- a/plugins/kubernetes/README.md +++ b/plugins/kubernetes/README.md @@ -8,15 +8,20 @@ It will elevate the visibility of errors where identified, and provide drill dow It directly interfaces with the [Kubernetes Backend Plugin (`@backstage-plugin-kubernetes-backend`)](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend). -_This plugin was created through the Backstage CLI_ - ## Introduction See our announcement blog post [New Backstage feature: Kubernetes for Service Owners](https://backstage.io/blog/2021/01/12/new-backstage-feature-kubernetes-for-service-owners) to learn more about the motivation behind developing the plugin. ## Setup & Configuration -This plugin must be explicitly added to a Backstage app, along with it's peer backend plugin. +This plugin must be explicitly added to a Backstage app, along with its peer backend plugin. + +```bash +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-kubernetes +``` + +Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). It requires configuration in the Backstage `app-config.yaml` to connect to a Kubernetes API control plane. @@ -24,35 +29,9 @@ In addition, configuration of an entity's `catalog-info.yaml` helps identify whi For more information, see the [formal documentation about the Kubernetes feature in Backstage](https://backstage.io/docs/features/kubernetes/overview). -## Getting started +### Enabling the entity content tab -Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/kubernetes](http://localhost:3000/catalog/default/component/:component-name/kubernetes). - -You can also serve the plugin in isolation by running `yarn start` in the plugin directory. -This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. -It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. - -### Integrating with `EntityPage` (New Frontend System) - -Follow this section if you are using Backstage's [new frontend system](https://backstage.io/docs/frontend-system/). - -1. Import `kubernetesPlugin` in your `App.tsx` and add it to your app's `features` array: - -```typescript -import kubernetesPlugin from '@backstage/plugin-kubernetes/alpha'; - -// ... - -export const app = createApp({ - features: [ - // ... - kubernetesPlugin, - // ... - ], -}); -``` - -2. Next, enable your desired extensions in `app-config.yaml`. +Enable the Kubernetes entity content extension in your `app-config.yaml`: ```yaml app: @@ -77,3 +56,11 @@ app: - resource - system ``` + +## Getting started + +Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/kubernetes](http://localhost:3000/catalog/default/component/:component-name/kubernetes). + +You can also serve the plugin in isolation by running `yarn start` in the plugin directory. +This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. +It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. From 67723818b5d01eacd980bc661801a12185491e5d Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 12:14:48 +0100 Subject: [PATCH 12/17] docs: improve cross-references for installing plugins page Update the Building Apps overview to reference the new installing plugins page instead of duplicating feature discovery content. Add cross-references between the installing plugins page, the architecture feature discovery docs, the plugin conversion page, and the extension configuration page. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- docs/frontend-system/architecture/10-app.md | 2 ++ docs/frontend-system/building-apps/01-index.md | 10 +++------- .../building-apps/05-installing-plugins.md | 6 +++++- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/frontend-system/architecture/10-app.md b/docs/frontend-system/architecture/10-app.md index 0303dd5e70..b9cbedc025 100644 --- a/docs/frontend-system/architecture/10-app.md +++ b/docs/frontend-system/architecture/10-app.md @@ -42,6 +42,8 @@ A common type of data that is shared between extensions is React elements and co ## Feature Discovery +For a practical guide on how to install plugins in your app, see [Installing Plugins](../building-apps/05-installing-plugins.md). + App feature discovery lets you automatically discover and install features provided by dependencies in your app. In practice, it means that you don't need to manually `import` features in code, but they are instead installed as soon as you add them as a dependency in your `package.json`. Because feature discovery needs to interact with the compilation process, it is only available when using the `@backstage/cli` to build your app. It is hooked into the WebPack compilation process by scanning your app package for compatible dependencies, which are then made part of the app compilation bundle. diff --git a/docs/frontend-system/building-apps/01-index.md b/docs/frontend-system/building-apps/01-index.md index 8610dfb7b5..7a9f792f45 100644 --- a/docs/frontend-system/building-apps/01-index.md +++ b/docs/frontend-system/building-apps/01-index.md @@ -63,13 +63,9 @@ Visit the [built-in extensions](#customize-or-override-built-in-extensions) sect Linking routes from different plugins requires this configuration. You can do this either through a configuration file or by coding, visit [this](https://backstage.io/docs/frontend-system/architecture/routes#binding-external-route-references) page for instructions. -### Enable feature discovery +### Install plugins -Use this setting to enable experimental feature discovery when building your app with `@backstage/cli`. With this configuration your application tries to discover and install package extensions automatically, check [here](../architecture/10-app.md#feature-discovery) for more details. - -:::warning -Remember that package extensions that are not auto-discovered must be manually added to the application when creating an app. See [features](#install-features-manually) for more details. -::: +Plugins are typically installed by adding them as dependencies of your app package and relying on package discovery to automatically detect them. For details on how this works, including how to manually install plugins or control which packages are discovered, see [Installing Plugins](./05-installing-plugins.md). ### Configure extensions individually @@ -83,7 +79,7 @@ Previously you would customize the application routes, components, apis, sidebar ### Install features manually -A manual installation is required if your packages are not discovered automatically, either because you are not using `@backstage/cli` to build your application or because the features are defined in local modules in the app package. In order to manually install a feature, you must import it and pass it to the `createApp` function: +Most plugins are installed automatically through [package discovery](./05-installing-plugins.md#package-discovery). Manual installation is needed if your packages are not discovered automatically, either because you are not using `@backstage/cli` to build your application or because the features are defined in local modules in the app package. In order to manually install a feature, you must import it and pass it to the `createApp` function: ```tsx title="packages/app/src/App.tsx" import { createApp } from '@backstage/frontend-defaults'; diff --git a/docs/frontend-system/building-apps/05-installing-plugins.md b/docs/frontend-system/building-apps/05-installing-plugins.md index bb78214382..72eeb465b0 100644 --- a/docs/frontend-system/building-apps/05-installing-plugins.md +++ b/docs/frontend-system/building-apps/05-installing-plugins.md @@ -43,7 +43,9 @@ app: - '@backstage/plugin-catalog' ``` -Package discovery requires that your app is built using the `@backstage/cli`, which is the default for all Backstage apps. +Package discovery requires that your app is built using the `@backstage/cli`, which is the default for all Backstage apps. Note that you do not need to exclude packages that you also install manually in code, since plugin instances are deduplicated by the app. + +For more details on how package discovery works under the hood, see the [Feature Discovery](../architecture/10-app.md#feature-discovery) architecture documentation. ## Manual installation @@ -62,6 +64,8 @@ export default app.createRoot(); Manual installation may also be necessary if you need to control the ordering of plugins, for example when customizing route priorities. Since manually installed plugins are deduplicated against automatically discovered ones, you can safely install a plugin both manually and through package discovery without causing conflicts. +If you need to use a 3rd-party plugin that does not yet support the new frontend system, you can use the conversion utilities from `@backstage/core-compat-api` to wrap it. See [Converting 3rd-party Plugins](./06-plugin-conversion.md) for details. + ## Configuring installed plugins Once a plugin is installed, you can configure its extensions through the `app.extensions` section of your `app-config.yaml`. See [Configuring Extensions](./02-configuring-extensions.md) for details. From 17dff0ba255c009c32cc6d85140f4fc3c7ef8f22 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 12:43:03 +0100 Subject: [PATCH 13/17] docs: rename package discovery to feature discovery and reduce duplication Rename "package discovery" to "feature discovery" across all plugin READMEs and docs to match the established terminology. Slim down the Feature Discovery section in the architecture docs to avoid duplicating the configuration details now covered in the installing plugins page. Signed-off-by: Patrik Oldsberg Made-with: Cursor Signed-off-by: Patrik Oldsberg Made-with: Cursor --- docs/frontend-system/architecture/10-app.md | 28 +------------------ .../frontend-system/building-apps/01-index.md | 4 +-- .../building-apps/05-installing-plugins.md | 14 +++++----- docs/getting-started/homepage.md | 2 +- plugins/api-docs/README.md | 2 +- plugins/catalog-graph/README.md | 2 +- plugins/catalog-import/README.md | 2 +- .../catalog-unprocessed-entities/README.md | 2 +- plugins/catalog/README.md | 2 +- plugins/devtools/README.md | 2 +- plugins/home/README.md | 2 +- plugins/kubernetes/README.md | 2 +- plugins/mui-to-bui/README.md | 2 +- plugins/org/README.md | 2 +- plugins/scaffolder/README.md | 2 +- plugins/user-settings/README.md | 2 +- 16 files changed, 23 insertions(+), 49 deletions(-) diff --git a/docs/frontend-system/architecture/10-app.md b/docs/frontend-system/architecture/10-app.md index b9cbedc025..22457bcb30 100644 --- a/docs/frontend-system/architecture/10-app.md +++ b/docs/frontend-system/architecture/10-app.md @@ -42,37 +42,11 @@ A common type of data that is shared between extensions is React elements and co ## Feature Discovery -For a practical guide on how to install plugins in your app, see [Installing Plugins](../building-apps/05-installing-plugins.md). - App feature discovery lets you automatically discover and install features provided by dependencies in your app. In practice, it means that you don't need to manually `import` features in code, but they are instead installed as soon as you add them as a dependency in your `package.json`. Because feature discovery needs to interact with the compilation process, it is only available when using the `@backstage/cli` to build your app. It is hooked into the WebPack compilation process by scanning your app package for compatible dependencies, which are then made part of the app compilation bundle. -To enable frontend feature discovery, add the following configuration to your `app-config.yaml`: - -```yaml -app: - packages: all -``` - -This will cause all dependencies in your app package to be installed automatically. If this is not desired, you can use include or exclude filters to narrow down the set of packages: - -```yaml -app: - packages: - # Only the following packages will be included - include: - - '@backstage/plugin-catalog' - - '@backstage/plugin-scaffolder' ---- -app: - packages: - # All but the following package will be included - exclude: - - '@backstage/plugin-catalog' -``` - -Note that you do not need to manually exclude packages that you also import explicitly in code, since plugin instances are deduplicated by the app. You will never end up with duplicate plugin installations except if they are in fact two different plugin instances with different IDs. +For information on how to configure feature discovery and other installation options, see [Installing Plugins](../building-apps/05-installing-plugins.md). ## Plugin Info Resolution diff --git a/docs/frontend-system/building-apps/01-index.md b/docs/frontend-system/building-apps/01-index.md index 7a9f792f45..bd9a0fbae5 100644 --- a/docs/frontend-system/building-apps/01-index.md +++ b/docs/frontend-system/building-apps/01-index.md @@ -65,7 +65,7 @@ Linking routes from different plugins requires this configuration. You can do th ### Install plugins -Plugins are typically installed by adding them as dependencies of your app package and relying on package discovery to automatically detect them. For details on how this works, including how to manually install plugins or control which packages are discovered, see [Installing Plugins](./05-installing-plugins.md). +Plugins are typically installed by adding them as dependencies of your app package and relying on feature discovery to automatically detect them. For details on how this works, including how to manually install plugins or control which packages are discovered, see [Installing Plugins](./05-installing-plugins.md). ### Configure extensions individually @@ -79,7 +79,7 @@ Previously you would customize the application routes, components, apis, sidebar ### Install features manually -Most plugins are installed automatically through [package discovery](./05-installing-plugins.md#package-discovery). Manual installation is needed if your packages are not discovered automatically, either because you are not using `@backstage/cli` to build your application or because the features are defined in local modules in the app package. In order to manually install a feature, you must import it and pass it to the `createApp` function: +Most plugins are installed automatically through [feature discovery](./05-installing-plugins.md#feature-discovery). Manual installation is needed if your packages are not discovered automatically, either because you are not using `@backstage/cli` to build your application or because the features are defined in local modules in the app package. In order to manually install a feature, you must import it and pass it to the `createApp` function: ```tsx title="packages/app/src/App.tsx" import { createApp } from '@backstage/frontend-defaults'; diff --git a/docs/frontend-system/building-apps/05-installing-plugins.md b/docs/frontend-system/building-apps/05-installing-plugins.md index 72eeb465b0..9007ce0eb1 100644 --- a/docs/frontend-system/building-apps/05-installing-plugins.md +++ b/docs/frontend-system/building-apps/05-installing-plugins.md @@ -15,11 +15,11 @@ To install a plugin, add it as a dependency to your app package. For example, to yarn --cwd packages/app add @backstage/plugin-catalog ``` -If your app is set up with [package discovery](#package-discovery), the plugin will be automatically detected and installed in the app. No additional code changes are needed. +If your app is set up with [feature discovery](#feature-discovery), the plugin will be automatically detected and installed in the app. No additional code changes are needed. -## Package discovery +## Feature discovery -Package discovery lets the app automatically discover and install plugins from the dependencies of your app package. This is enabled by setting `app.packages` to `all` in your `app-config.yaml`: +Feature discovery lets the app automatically discover and install plugins from the dependencies of your app package. This is enabled by setting `app.packages` to `all` in your `app-config.yaml`: ```yaml title="app-config.yaml" app: @@ -43,13 +43,13 @@ app: - '@backstage/plugin-catalog' ``` -Package discovery requires that your app is built using the `@backstage/cli`, which is the default for all Backstage apps. Note that you do not need to exclude packages that you also install manually in code, since plugin instances are deduplicated by the app. +Feature discovery requires that your app is built using the `@backstage/cli`, which is the default for all Backstage apps. Note that you do not need to exclude packages that you also install manually in code, since plugin instances are deduplicated by the app. -For more details on how package discovery works under the hood, see the [Feature Discovery](../architecture/10-app.md#feature-discovery) architecture documentation. +For more details on how feature discovery works under the hood, see the [Feature Discovery](../architecture/10-app.md#feature-discovery) architecture documentation. ## Manual installation -If your app does not have [package discovery](#package-discovery) enabled, or if you need more control over the plugin installation, you can install plugins manually. This is done by importing the plugin and passing it to `createApp`: +If your app does not have [feature discovery](#feature-discovery) enabled, or if you need more control over the plugin installation, you can install plugins manually. This is done by importing the plugin and passing it to `createApp`: ```tsx title="packages/app/src/App.tsx" import { createApp } from '@backstage/frontend-defaults'; @@ -62,7 +62,7 @@ const app = createApp({ export default app.createRoot(); ``` -Manual installation may also be necessary if you need to control the ordering of plugins, for example when customizing route priorities. Since manually installed plugins are deduplicated against automatically discovered ones, you can safely install a plugin both manually and through package discovery without causing conflicts. +Manual installation may also be necessary if you need to control the ordering of plugins, for example when customizing route priorities. Since manually installed plugins are deduplicated against automatically discovered ones, you can safely install a plugin both manually and through feature discovery without causing conflicts. If you need to use a 3rd-party plugin that does not yet support the new frontend system, you can use the conversion utilities from `@backstage/core-compat-api` to wrap it. See [Converting 3rd-party Plugins](./06-plugin-conversion.md) for details. diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 7085f9b082..af39a825d8 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -32,7 +32,7 @@ Now, let's get started by installing the home plugin and creating a simple homep yarn --cwd packages/app add @backstage/plugin-home ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](../frontend-system/building-apps/05-installing-plugins.md). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](../frontend-system/building-apps/05-installing-plugins.md). ### 2. Configure the homepage as your root route diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index f6f52cbcae..5650b378f5 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -30,7 +30,7 @@ To link that a component provides or consumes an API, see the [`providesApis`](h yarn --cwd packages/app add @backstage/plugin-api-docs ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). You can enable entity cards and tabs on the catalog entity page through configuration: diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md index 38ea902271..b1af843190 100644 --- a/plugins/catalog-graph/README.md +++ b/plugins/catalog-graph/README.md @@ -27,7 +27,7 @@ The plugin comes with these features: yarn --cwd packages/app add @backstage/plugin-catalog-graph ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). To enable the entity relations graph card on the catalog entity page, add the following configuration: diff --git a/plugins/catalog-import/README.md b/plugins/catalog-import/README.md index f8174b63ff..ba98d19f0b 100644 --- a/plugins/catalog-import/README.md +++ b/plugins/catalog-import/README.md @@ -22,7 +22,7 @@ Install the Catalog Import Plugin: yarn --cwd packages/app add @backstage/plugin-catalog-import ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Customizations diff --git a/plugins/catalog-unprocessed-entities/README.md b/plugins/catalog-unprocessed-entities/README.md index 13bca8b04f..8cdf275851 100644 --- a/plugins/catalog-unprocessed-entities/README.md +++ b/plugins/catalog-unprocessed-entities/README.md @@ -32,7 +32,7 @@ Requires the `@backstage/plugin-catalog-backend-module-unprocessed` module to be yarn --cwd packages/app add @backstage/plugin-catalog-unprocessed-entities ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). You can optionally add unprocessed entities as a tab in DevTools through configuration: diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index 993f0e34f2..ae8ddd1033 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -20,7 +20,7 @@ plugin, if you previously removed it. yarn --cwd packages/app add @backstage/plugin-catalog ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Old Frontend System diff --git a/plugins/devtools/README.md b/plugins/devtools/README.md index 54aa1f492d..b049839861 100644 --- a/plugins/devtools/README.md +++ b/plugins/devtools/README.md @@ -73,7 +73,7 @@ Install the `@backstage/plugin-devtools` package in your frontend app: yarn --cwd packages/app add @backstage/plugin-devtools ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Customizing diff --git a/plugins/home/README.md b/plugins/home/README.md index e75f28e6ed..2c46530c3d 100644 --- a/plugins/home/README.md +++ b/plugins/home/README.md @@ -11,7 +11,7 @@ For App Integrators, the system is designed to be composable to give total freed yarn --cwd packages/app add @backstage/plugin-home ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). The plugin will automatically provide: diff --git a/plugins/kubernetes/README.md b/plugins/kubernetes/README.md index 42410ca92d..baf0ab42a3 100644 --- a/plugins/kubernetes/README.md +++ b/plugins/kubernetes/README.md @@ -21,7 +21,7 @@ This plugin must be explicitly added to a Backstage app, along with its peer bac yarn --cwd packages/app add @backstage/plugin-kubernetes ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). It requires configuration in the Backstage `app-config.yaml` to connect to a Kubernetes API control plane. diff --git a/plugins/mui-to-bui/README.md b/plugins/mui-to-bui/README.md index d5f08e6d03..4217f103a8 100644 --- a/plugins/mui-to-bui/README.md +++ b/plugins/mui-to-bui/README.md @@ -12,7 +12,7 @@ Add the dependency to your app: yarn --cwd packages/app add @backstage/plugin-mui-to-bui ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Accessing the Themer page diff --git a/plugins/org/README.md b/plugins/org/README.md index edf7cc4a89..9c8050e940 100644 --- a/plugins/org/README.md +++ b/plugins/org/README.md @@ -25,7 +25,7 @@ Here's an example of what the User Profile looks like: yarn --cwd packages/app add @backstage/plugin-org ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). You can enable entity cards on the catalog entity page through configuration: diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index ff09796033..6a2ad697b5 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -20,7 +20,7 @@ the plugin, if you previously removed it. yarn --cwd packages/app add @backstage/plugin-scaffolder ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ### Troubleshooting diff --git a/plugins/user-settings/README.md b/plugins/user-settings/README.md index b4c283d275..2fa5e5db39 100644 --- a/plugins/user-settings/README.md +++ b/plugins/user-settings/README.md @@ -18,7 +18,7 @@ for installation instructions. yarn --cwd packages/app add @backstage/plugin-user-settings ``` -Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). +Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins). ## Old Frontend System From 538c985672b77133dfcfecce0fbdc434242856b0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 4 Mar 2026 13:43:47 +0100 Subject: [PATCH 14/17] Add changesets for plugin README updates Signed-off-by: Patrik Oldsberg Made-with: Cursor --- .changeset/docs-frontend-plugin-installation.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .changeset/docs-frontend-plugin-installation.md diff --git a/.changeset/docs-frontend-plugin-installation.md b/.changeset/docs-frontend-plugin-installation.md new file mode 100644 index 0000000000..8a13f5c12d --- /dev/null +++ b/.changeset/docs-frontend-plugin-installation.md @@ -0,0 +1,16 @@ +--- +'@backstage/plugin-api-docs': patch +'@backstage/plugin-catalog': patch +'@backstage/plugin-catalog-graph': patch +'@backstage/plugin-catalog-import': patch +'@backstage/plugin-catalog-unprocessed-entities': patch +'@backstage/plugin-devtools': patch +'@backstage/plugin-home': patch +'@backstage/plugin-kubernetes': patch +'@backstage/plugin-mui-to-bui': patch +'@backstage/plugin-org': patch +'@backstage/plugin-scaffolder': patch +'@backstage/plugin-user-settings': patch +--- + +Updated installation documentation to use feature discovery as the default. From 98b6b9701b6891b8c8d9e3ba9d498fdcfb5a5ba6 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 16 Mar 2026 13:20:01 +0100 Subject: [PATCH 15/17] Address review feedback on plugin README updates - Apply freben's suggested wording for old frontend system sections to clarify they can be skipped on the new frontend system - Fix scaffolder README: add missing imports (AnyApiFactory, scmIntegrationsApiRef), closing bracket, and update link text - Fix devtools README: correct closing tag from `` to `` - Fix kubernetes README: reword "must be explicitly added" to avoid conflicting with feature discovery paragraph Signed-off-by: Patrik Oldsberg Made-with: Cursor --- plugins/api-docs/README.md | 2 +- plugins/catalog-graph/README.md | 2 +- plugins/catalog/README.md | 2 +- plugins/devtools/README.md | 4 ++-- plugins/kubernetes/README.md | 2 +- plugins/org/README.md | 2 +- plugins/scaffolder/README.md | 9 ++++++--- plugins/user-settings/README.md | 2 +- 8 files changed, 14 insertions(+), 11 deletions(-) diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index 5650b378f5..f71b796ec4 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -342,7 +342,7 @@ import { ApiExplorerPage } from '@backstage/plugin-api-docs'; ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. 1. Add the `ApiExplorerPage` extension to the app: diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md index b1af843190..058fc28164 100644 --- a/plugins/catalog-graph/README.md +++ b/plugins/catalog-graph/README.md @@ -143,7 +143,7 @@ import { ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. 1. Add the `CatalogGraphPage` to your `packages/app/src/App.tsx`: diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index ae8ddd1033..af8c82b35c 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -24,7 +24,7 @@ Once installed, the plugin is automatically available in your app through the de ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. ### Add the plugin to your `packages/app` diff --git a/plugins/devtools/README.md b/plugins/devtools/README.md index b049839861..3f9a3da747 100644 --- a/plugins/devtools/README.md +++ b/plugins/devtools/README.md @@ -202,7 +202,7 @@ Here's how to add the Catalog Unprocessed Entities tab: ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. 1. Open the `packages/app/src/App.tsx` file 2. Then after all the import statements add the following line: @@ -211,7 +211,7 @@ If your Backstage app uses the old frontend system, you need to manually wire th import { DevToolsPage } from '@backstage/plugin-devtools'; ``` -3. In this same file just before the closing ``, this will be near the bottom of the file, add this line: +3. In this same file just before the closing ``, this will be near the bottom of the file, add this line: ```ts } /> diff --git a/plugins/kubernetes/README.md b/plugins/kubernetes/README.md index baf0ab42a3..fe64aea257 100644 --- a/plugins/kubernetes/README.md +++ b/plugins/kubernetes/README.md @@ -14,7 +14,7 @@ See our announcement blog post [New Backstage feature: Kubernetes for Service Ow ## Setup & Configuration -This plugin must be explicitly added to a Backstage app, along with its peer backend plugin. +This plugin must be installed in a Backstage app, along with its peer backend plugin. ```bash # From your Backstage root directory diff --git a/plugins/org/README.md b/plugins/org/README.md index 9c8050e940..062f88fa98 100644 --- a/plugins/org/README.md +++ b/plugins/org/README.md @@ -43,7 +43,7 @@ For the full list of available extensions and their configuration options, see t ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. ### MyGroupsSidebarItem diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index 6a2ad697b5..bc3f0f8ed6 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -24,18 +24,20 @@ Once installed, the plugin is automatically available in your app through the de ### Troubleshooting -If you encounter the [issue of closing EventStream](https://github.com/backstage/backstage/issues/5535) +If you encounter [issues with early closure of the `EventStream`](https://github.com/backstage/backstage/issues/5535) which auto-updates logs during task execution, you can enable long polling. To do so, update your `packages/app/src/apis.ts` file to register a `ScaffolderClient` with the `useLongPollingLogs` set to `true`. By default, it is `false`. ```typescript import { + AnyApiFactory, createApiFactory, discoveryApiRef, fetchApiRef, identityApiRef, } from '@backstage/core-plugin-api'; +import { scmIntegrationsApiRef } from '@backstage/integration-react'; import { scaffolderApiRef, ScaffolderClient, @@ -60,6 +62,7 @@ export const apis: AnyApiFactory[] = [ }), }), // ... other factories +]; ``` This replaces the default implementation of the `scaffolderApiRef`. @@ -71,11 +74,11 @@ to launch the plugin locally using the `createDevApp` of the `./dev/index.tsx` f To play with it, open a terminal and run the command: `yarn start` within the `./plugins/scaffolder` folder -**NOTE:** Don't forget to open a second terminal and to launch the backend or [backend-next](../../docs/backend-system/index.md) there, using `yarn start` and to specify the locations of the templates to play with ! +**NOTE:** Don't forget to open a second terminal and to launch the backend there, using `yarn start backend` and to specify the locations of the templates to play with! ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. ### Add the plugin to your `packages/app` diff --git a/plugins/user-settings/README.md b/plugins/user-settings/README.md index 2fa5e5db39..8644001fe1 100644 --- a/plugins/user-settings/README.md +++ b/plugins/user-settings/README.md @@ -22,7 +22,7 @@ Once installed, the plugin is automatically available in your app through the de ## Old Frontend System -If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app. +If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. ### Components Usage From 90a02779fa268dd5543ccc47e261d24a391c6c88 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 16 Mar 2026 19:44:44 +0100 Subject: [PATCH 16/17] Address remaining docs review feedback Clarify the remaining old frontend system sections, tighten the scaffolder follow-up wording, and rename the docs sidebar entry to match the frontend system terminology used elsewhere. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- microsite/sidebars.ts | 6 +++--- plugins/catalog-import/README.md | 6 +++++- plugins/catalog-unprocessed-entities/README.md | 6 +++++- plugins/mui-to-bui/README.md | 6 +++++- plugins/scaffolder/README.md | 9 +++++---- 5 files changed, 23 insertions(+), 10 deletions(-) diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts index cf893d6895..3cffa45747 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.ts @@ -551,15 +551,15 @@ export default { ), sidebarElementWithIndex( { - label: 'New Frontend System', - description: 'New frontend system components and architecture.', + label: 'Frontend System', + description: 'Frontend system components and architecture.', }, [ 'frontend-system/index', sidebarElementWithIndex( { label: 'Architecture', - description: 'Architecture of the new frontend system.', + description: 'Architecture of the frontend system.', differentiator: 'frontend-system/', }, [ diff --git a/plugins/catalog-import/README.md b/plugins/catalog-import/README.md index ba98d19f0b..efb7c84fa3 100644 --- a/plugins/catalog-import/README.md +++ b/plugins/catalog-import/README.md @@ -98,7 +98,11 @@ Following React components accept optional props for providing custom example en ## Old Frontend System -If your Backstage app uses the old frontend system, add the `CatalogImportPage` extension to the app: +If your Backstage app uses the old frontend system, you need to manually wire the +plugin into your app as outlined in this section. If you are on the new frontend +system, you can skip this. + +Add the `CatalogImportPage` extension to the app: ```tsx // packages/app/src/App.tsx diff --git a/plugins/catalog-unprocessed-entities/README.md b/plugins/catalog-unprocessed-entities/README.md index 8cdf275851..fc20168b80 100644 --- a/plugins/catalog-unprocessed-entities/README.md +++ b/plugins/catalog-unprocessed-entities/README.md @@ -47,7 +47,11 @@ app: ## Old Frontend System -If your Backstage app uses the old frontend system, import into your `App.tsx` and include into the `` component: +If your Backstage app uses the old frontend system, you need to manually wire the +plugin into your app as outlined in this section. If you are on the new frontend +system, you can skip this. + +Import it into your `App.tsx` and include it in the `` component: ```tsx title="packages/app/src/App.tsx" import { CatalogUnprocessedEntitiesPage } from '@backstage/plugin-catalog-unprocessed-entities'; diff --git a/plugins/mui-to-bui/README.md b/plugins/mui-to-bui/README.md index 4217f103a8..0b760c4ef2 100644 --- a/plugins/mui-to-bui/README.md +++ b/plugins/mui-to-bui/README.md @@ -21,7 +21,11 @@ Once installed, the plugin is automatically available in your app through the de ## Old Frontend System -If your Backstage app uses the old frontend system, add a route for the page in your app: +If your Backstage app uses the old frontend system, you need to manually wire the +plugin into your app as outlined in this section. If you are on the new frontend +system, you can skip this. + +Add a route for the page in your app: ```tsx // packages/app/src/App.tsx diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index bc3f0f8ed6..9c9ca15dfa 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -25,9 +25,9 @@ Once installed, the plugin is automatically available in your app through the de ### Troubleshooting If you encounter [issues with early closure of the `EventStream`](https://github.com/backstage/backstage/issues/5535) -which auto-updates logs during task execution, you can enable long polling. To do so, -update your `packages/app/src/apis.ts` file to register a `ScaffolderClient` with the -`useLongPollingLogs` set to `true`. By default, it is `false`. +used to auto-update logs during task execution, you can work around them by enabling +long polling. To do so, update your `packages/app/src/apis.ts` file to register a +`ScaffolderClient` with `useLongPollingLogs` set to `true`. By default, it is `false`. ```typescript import { @@ -74,7 +74,8 @@ to launch the plugin locally using the `createDevApp` of the `./dev/index.tsx` f To play with it, open a terminal and run the command: `yarn start` within the `./plugins/scaffolder` folder -**NOTE:** Don't forget to open a second terminal and to launch the backend there, using `yarn start backend` and to specify the locations of the templates to play with! +**NOTE:** Don't forget to open a second terminal, start your Backstage backend there, +and configure the template locations that you want to test. ## Old Frontend System From 1decc6f9949899caad75519def629eb246403a01 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 16 Mar 2026 20:04:16 +0100 Subject: [PATCH 17/17] Split legacy homepage getting started docs Move the old frontend system homepage guide to its own companion page and add a banner to the main homepage guide that directs legacy users to the split-out documentation. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- docs/getting-started/homepage--old.md | 201 ++++++++++++++++++++++++++ docs/getting-started/homepage.md | 151 +------------------ 2 files changed, 208 insertions(+), 144 deletions(-) create mode 100644 docs/getting-started/homepage--old.md diff --git a/docs/getting-started/homepage--old.md b/docs/getting-started/homepage--old.md new file mode 100644 index 0000000000..98021d76a2 --- /dev/null +++ b/docs/getting-started/homepage--old.md @@ -0,0 +1,201 @@ +--- +id: homepage--old +title: Backstage homepage - Setup and Customization (Old Frontend System) +description: Documentation on setting up and customizing Backstage homepage +--- + +::::info +This documentation is for Backstage apps that still use the old frontend +system. If your app uses the new frontend system, read the +[current homepage guide](./homepage.md) instead. +:::: + +## Homepage + +Having a good Backstage homepage can significantly improve the discoverability +of the platform. You want your users to find all the things they need right +from the homepage and never have to remember direct URLs in Backstage. The +[Home plugin](https://github.com/backstage/backstage/tree/master/plugins/home) +introduces a system for composing a homepage for Backstage in order to surface +relevant info and provide convenient shortcuts for common tasks. It's designed +with composability in mind with an open ecosystem that allows anyone to +contribute with any component, to be included in any homepage. + +For App Integrators, the system is designed to be composable to give total +freedom in designing a Homepage that suits the needs of the organization. From +the perspective of a Component Developer who wishes to contribute with building +blocks to be included in Homepages, there's a convenient interface for bundling +the different parts and exporting them with both error boundary and lazy +loading handled under the surface. + +At the end of this tutorial, you can expect: + +- Your Backstage app to have a dedicated homepage instead of Software Catalog. +- Understand the composability of homepage and how to start customizing it for + your own organization. + +### Prerequisites + +Before we begin, make sure + +- You have created your own standalone Backstage app using + [`@backstage/create-app`](./index.md#1-create-your-backstage-app) and not + using a fork of the [backstage](https://github.com/backstage/backstage) + repository. +- You do not have an existing homepage, and by default you are redirected to + Software Catalog when you open Backstage. + +Now, let's get started by installing the home plugin and creating a simple +homepage for your Backstage app. + +## Setup + +### 1. Install the plugin + +```bash title="From your Backstage root directory" +yarn --cwd packages/app add @backstage/plugin-home +``` + +### 2. Create a new HomePage component + +Inside your `packages/app` directory, create a new file where our new homepage +component is going to live. Create `packages/app/src/components/home/HomePage.tsx` +with the following initial code + +```tsx +export const HomePage = () => ( + /* We will shortly compose a pretty homepage here. */ +

Welcome to Backstage!

+); +``` + +### 3. Update router for the root `/` route + +If you don't have a homepage already, most likely you have a redirect setup to +use the Catalog homepage as a homepage. + +Inside your `packages/app/src/App.tsx`, look for + +```tsx title="packages/app/src/App.tsx" +const routes = ( + + + {/* ... */} + +); +``` + +Let's replace the `` line and use the new component we created in the +previous step as the new homepage. + +```tsx title="packages/app/src/App.tsx" +/* highlight-add-start */ +import { HomepageCompositionRoot } from '@backstage/plugin-home'; +import { HomePage } from './components/home/HomePage'; +/* highlight-add-end */ + +const routes = ( + + {/* highlight-remove-next-line */} + + {/* highlight-add-start */} + }> + + + {/* highlight-add-end */} + {/* ... */} + +); +``` + +### 4. Update sidebar items + +Let's update the route for "Home" in the Backstage sidebar to point to the new +homepage. We'll also add a Sidebar item to quickly open Catalog. + +| Before | After | +| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| ![Sidebar without Catalog](../assets/getting-started/sidebar-without-catalog.png) | ![Sidebar with Catalog](../assets/getting-started/sidebar-with-catalog.png) | + +The code for the Backstage sidebar is most likely inside your +[`packages/app-legacy/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app-legacy/src/components/Root/Root.tsx). + +Let's make the following changes + +```tsx title="packages/app/src/components/Root/Root.tsx" +/* highlight-add-next-line */ +import CategoryIcon from '@material-ui/icons/Category'; + +export const Root = ({ children }: PropsWithChildren<{}>) => ( + + + + {/* ... */} + }> + {/* Global nav, not org-specific */} + {/* highlight-remove-next-line */} + + {/* highlight-add-start */} + + + {/* highlight-add-end */} + + + + + {/* End global nav */} + + {/* ... */} + + + +); +``` + +That's it! You should now have _(although slightly boring)_ a homepage! + + + +![Screenshot of a blank homepage](../assets/getting-started/simple-homepage.png) + +In the next steps, we will make it interesting and useful! + +#### Use the default template + +There is a default homepage template +([storybook link](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template)) +which we will use to set up our homepage. Checkout the +[blog post announcement](https://backstage.io/blog/2022/01/25/backstage-homepage-templates) +about the Backstage homepage templates for more information. + + + +#### Composing your homepage + +Composing a homepage is no different from creating a regular React Component, +i.e. the App Integrator is free to include whatever content they like. However, +there are components developed with the homepage in mind. If you are looking +for components to use when composing your homepage, you can take a look at the +[collection of Homepage components](https://backstage.io/storybook?path=/story/plugins-home-components) +in storybook. If you don't find a component that suits your needs but want to +contribute, check the +[Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing). + +> If you want to use one of the available homepage templates you can find the +> [templates](https://backstage.io/storybook/?path=/story/plugins-home-templates) +> in the storybook under the "Home" plugin. And if you would like to contribute +> a template, please see the +> [Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing) + +```tsx +import Grid from '@material-ui/core/Grid'; +import { HomePageCompanyLogo } from '@backstage/plugin-home'; + +export const HomePage = () => ( + + + + + +); +``` diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index af39a825d8..22761eb6ed 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -4,6 +4,13 @@ title: Backstage homepage - Setup and Customization description: Documentation on setting up and customizing Backstage homepage --- +::::info +This documentation is written for the new frontend system, which is the default +in new Backstage apps. If your Backstage app still uses the old frontend system, +read the [old frontend system version of this guide](./homepage--old.md) +instead. +:::: + ## Homepage Having a good Backstage homepage can significantly improve the discoverability of the platform. You want your users to find all the things they need right from the homepage and never have to remember direct URLs in Backstage. The [Home plugin](https://github.com/backstage/backstage/tree/master/plugins/home) introduces a system for composing a homepage for Backstage in order to surface relevant info and provide convenient shortcuts for common tasks. It's designed with composability in mind with an open ecosystem that allows anyone to contribute with any component, to be included in any homepage. @@ -75,147 +82,3 @@ The home plugin provides powerful customization options: **Adding Homepage Widgets**: Register custom widgets using the `HomePageWidgetBlueprint` from the `@backstage/plugin-home-react/alpha` package. For detailed instructions on creating custom layouts, registering widgets, and advanced configuration options, see the [Home plugin documentation](https://github.com/backstage/backstage/tree/master/plugins/home#readme). - -## Old Frontend System - -This section covers how to set up the home plugin if your Backstage app still uses the old frontend system. - -### 1. Install the plugin - -```bash title="From your Backstage root directory" -yarn --cwd packages/app add @backstage/plugin-home -``` - -### 2. Create a new HomePage component - -Inside your `packages/app` directory, create a new file where our new homepage component is going to live. Create `packages/app/src/components/home/HomePage.tsx` with the following initial code - -```tsx -export const HomePage = () => ( - /* We will shortly compose a pretty homepage here. */ -

Welcome to Backstage!

-); -``` - -### 3. Update router for the root `/` route - -If you don't have a homepage already, most likely you have a redirect setup to use the Catalog homepage as a homepage. - -Inside your `packages/app/src/App.tsx`, look for - -```tsx title="packages/app/src/App.tsx" -const routes = ( - - - {/* ... */} - -); -``` - -Let's replace the `` line and use the new component we created in the previous step as the new homepage. - -```tsx title="packages/app/src/App.tsx" -/* highlight-add-start */ -import { HomepageCompositionRoot } from '@backstage/plugin-home'; -import { HomePage } from './components/home/HomePage'; -/* highlight-add-end */ - -const routes = ( - - {/* highlight-remove-next-line */} - - {/* highlight-add-start */} - }> - - - {/* highlight-add-end */} - {/* ... */} - -); -``` - -### 4. Update sidebar items - -Let's update the route for "Home" in the Backstage sidebar to point to the new homepage. We'll also add a Sidebar item to quickly open Catalog. - -| Before | After | -| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| ![Sidebar without Catalog](../assets/getting-started/sidebar-without-catalog.png) | ![Sidebar with Catalog](../assets/getting-started/sidebar-with-catalog.png) | - -The code for the Backstage sidebar is most likely inside your [`packages/app-legacy/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app-legacy/src/components/Root/Root.tsx). - -Let's make the following changes - -```tsx title="packages/app/src/components/Root/Root.tsx" -/* highlight-add-next-line */ -import CategoryIcon from '@material-ui/icons/Category'; - -export const Root = ({ children }: PropsWithChildren<{}>) => ( - - - - {/* ... */} - }> - {/* Global nav, not org-specific */} - {/* highlight-remove-next-line */} - - {/* highlight-add-start */} - - - {/* highlight-add-end */} - - - - - {/* End global nav */} - - {/* ... */} - - - -); -``` - -That's it! You should now have _(although slightly boring)_ a homepage! - - - -![Screenshot of a blank homepage](../assets/getting-started/simple-homepage.png) - -In the next steps, we will make it interesting and useful! - -#### Use the default template - -There is a default homepage template ([storybook link](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template)) which we will use to set up our homepage. Checkout the [blog post announcement](https://backstage.io/blog/2022/01/25/backstage-homepage-templates) about the Backstage homepage templates for more information. - - - -#### Composing your homepage - -Composing a homepage is no different from creating a regular React Component, -i.e. the App Integrator is free to include whatever content they like. However, -there are components developed with the homepage in mind. If you are looking -for components to use when composing your homepage, you can take a look at the -[collection of Homepage components](https://backstage.io/storybook?path=/story/plugins-home-components) -in storybook. If you don't find a component that suits your needs but want to -contribute, check the -[Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing). - -> If you want to use one of the available homepage templates you can find the -> [templates](https://backstage.io/storybook/?path=/story/plugins-home-templates) -> in the storybook under the "Home" plugin. And if you would like to contribute -> a template, please see the -> [Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing) - -```tsx -import Grid from '@material-ui/core/Grid'; -import { HomePageCompanyLogo } from '@backstage/plugin-home'; - -export const HomePage = () => ( - - - - - -); -```