paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 45 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
docs/frontend-system/architecture/10-app.md
+1 -25
View File
@@ -46,31 +46,7 @@ App feature discovery lets you automatically discover and install features provi
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
docs/frontend-system/building-apps/01-index.md
+3 -7
View File
@@ -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 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
@@ -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 [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';
docs/frontend-system/building-apps/05-installing-plugins.md
+71
View File
@@ -0,0 +1,71 @@
---
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 [feature discovery](#feature-discovery), the plugin will be automatically detected and installed in the app. No additional code changes are needed.
## Feature discovery
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:
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'
```
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 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 [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';
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 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.
## 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.
docs/getting-started/homepage--old.md
+201
View File
@@ -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. */
<h1>Welcome to Backstage!</h1>
);
```
### 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 = (
<FlatRoutes>
<Navigate key="/" to="catalog" />
{/* ... */}
</FlatRoutes>
);
```
Let's replace the `<Navigate>` 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 = (
<FlatRoutes>
{/* highlight-remove-next-line */}
<Navigate key="/" to="catalog" />
{/* highlight-add-start */}
<Route path="/" element={<HomepageCompositionRoot />}>
<HomePage />
</Route>
{/* highlight-add-end */}
{/* ... */}
</FlatRoutes>
);
```
### 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<{}>) => (
<SidebarPage>
<Sidebar>
<SidebarLogo />
{/* ... */}
<SidebarGroup label="Menu" icon={<MenuIcon />}>
{/* Global nav, not org-specific */}
{/* highlight-remove-next-line */}
<SidebarItem icon={HomeIcon} to="catalog" text="Home" />
{/* highlight-add-start */}
<SidebarItem icon={HomeIcon} to="/" text="Home" />
<SidebarItem icon={CategoryIcon} to="catalog" text="Catalog" />
{/* highlight-add-end */}
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
<SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
<SidebarItem icon={LayersIcon} to="explore" text="Explore" />
<SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
{/* End global nav */}
<SidebarDivider />
{/* ... */}
</SidebarGroup>
</Sidebar>
</SidebarPage>
);
```
That's it! You should now have _(although slightly boring)_ a homepage!
<!-- todo: Needs zoomable plugin -->
![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.
<!-- TODO for later: detailed instructions for using one of these templates. -->
#### 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 = () => (
<Grid container spacing={3}>
<Grid item xs={12} md={4}>
<HomePageCompanyLogo />
</Grid>
</Grid>
);
```
docs/getting-started/homepage.md
+14 -173
View File
@@ -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.
@@ -24,39 +31,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 feature 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 +55,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,156 +73,12 @@ 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.
**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).
### Legacy Frontend System Setup
If your Backstage app uses the legacy frontend system, follow these steps:
#### 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. */
<h1>Welcome to Backstage!</h1>
);
```
#### 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 = (
<FlatRoutes>
<Navigate key="/" to="catalog" />
{/* ... */}
</FlatRoutes>
);
```
Let's replace the `<Navigate>` 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 = (
<FlatRoutes>
{/* highlight-remove-next-line */}
<Navigate key="/" to="catalog" />
{/* highlight-add-start */}
<Route path="/" element={<HomepageCompositionRoot />}>
<HomePage />
</Route>
{/* highlight-add-end */}
{/* ... */}
</FlatRoutes>
);
```
#### 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<{}>) => (
<SidebarPage>
<Sidebar>
<SidebarLogo />
{/* ... */}
<SidebarGroup label="Menu" icon={<MenuIcon />}>
{/* Global nav, not org-specific */}
{/* highlight-remove-next-line */}
<SidebarItem icon={HomeIcon} to="catalog" text="Home" />
{/* highlight-add-start */}
<SidebarItem icon={HomeIcon} to="/" text="Home" />
<SidebarItem icon={CategoryIcon} to="catalog" text="Catalog" />
{/* highlight-add-end */}
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
<SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
<SidebarItem icon={LayersIcon} to="explore" text="Explore" />
<SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
{/* End global nav */}
<SidebarDivider />
{/* ... */}
</SidebarGroup>
</Sidebar>
</SidebarPage>
);
```
That's it! You should now have _(although slightly boring)_ a homepage!
<!-- todo: Needs zoomable plugin -->
![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.
<!-- TODO for later: detailed instructions for using one of these templates. -->
### 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 = () => (
<Grid container spacing={3}>
<Grid item xs={12} md={4}>
<HomePageCompanyLogo />
</Grid>
</Grid>
);
```