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

docs: update frontend plugin docs to default to new frontend system

Browse Source 
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 <poldsberg@gmail.com>
Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
2026-03-04 11:24:35 +01:00
parent a5ff77fcbe
commit 5a463b320c
5 changed files with 135 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/frontend-system/building-apps/05-installing-plugins.md
+67
View File
@@ -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.
docs/getting-started/homepage.md
+15 -37
View File
@@ -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.
<!-- TODO for later: detailed instructions for using one of these templates. -->
### 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,