paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 40 Packages Projects Releases Wiki Activity

Merge pull request #33113 from backstage/rugvip/docs-frontend-plugin-installation

Browse Source 
docs: default frontend plugin docs to the new frontend system
This commit is contained in:
Patrik Oldsberg
2026-03-16 22:08:47 +01:00
committed by GitHub
parent 22f101e208 1decc6f994
commit 55b18a3c2e
22 changed files with 722 additions and 614 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/home/README.md
+43 -71
View File
@@ -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 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:
- 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: `<CustomHomepageGrid title="Your Dashboard" />`. 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 = [
<CustomHomepageGrid config={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 `<HomePageTopVisited/>` and `<HomePageRecentlyVisited/>` 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.