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.
diff --git a/docs/frontend-system/architecture/10-app.md b/docs/frontend-system/architecture/10-app.md
index 0303dd5e70..22457bcb30 100644
--- a/docs/frontend-system/architecture/10-app.md
+++ b/docs/frontend-system/architecture/10-app.md
@@ -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
diff --git a/docs/frontend-system/building-apps/01-index.md b/docs/frontend-system/building-apps/01-index.md
index 8610dfb7b5..bd9a0fbae5 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 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';
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..9007ce0eb1
--- /dev/null
+++ b/docs/frontend-system/building-apps/05-installing-plugins.md
@@ -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.
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 |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+|  |  |
+
+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!
+
+
+
+
+
+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 05e422610a..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.
@@ -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. */
- 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 |
-| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-|  |  |
-
-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!
-
-
-
-
-
-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/microsite/sidebars.ts b/microsite/sidebars.ts
index f4f18e69da..ec4585b407 100644
--- a/microsite/sidebars.ts
+++ b/microsite/sidebars.ts
@@ -560,15 +560,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/',
},
[
@@ -606,6 +606,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/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..f71b796ec4 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 feature 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 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:
+
+```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)
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..058fc28164 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 feature 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 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`:
+
+ ```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.
diff --git a/plugins/catalog-import/README.md b/plugins/catalog-import/README.md
index d4ede8af7b..efb7c84fa3 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 feature 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,22 @@ Following React components accept optional props for providing custom example en
/>
```
+## Old Frontend System
+
+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
+
+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.
diff --git a/plugins/catalog-unprocessed-entities/README.md b/plugins/catalog-unprocessed-entities/README.md
index b39a4a7ad4..fc20168b80 100644
--- a/plugins/catalog-unprocessed-entities/README.md
+++ b/plugins/catalog-unprocessed-entities/README.md
@@ -32,7 +32,26 @@ 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 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:
+
+```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, 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';
@@ -44,44 +63,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:
diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md
index e8de1118ac..af8c82b35c 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 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
+
+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`
Add the two pages that the catalog plugin provides to your app. You can choose
diff --git a/plugins/devtools/README.md b/plugins/devtools/README.md
index b23c35d4dd..3f9a3da747 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 feature 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 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:
+
+ ```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.
diff --git a/plugins/home/README.md b/plugins/home/README.md
index 04d1b8c2ec..2c46530c3d 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 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: ``. 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/kubernetes/README.md b/plugins/kubernetes/README.md
index e2c967902b..fe64aea257 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 installed in 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 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.
@@ -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.
diff --git a/plugins/mui-to-bui/README.md b/plugins/mui-to-bui/README.md
index d964b4827f..0b760c4ef2 100644
--- a/plugins/mui-to-bui/README.md
+++ b/plugins/mui-to-bui/README.md
@@ -6,17 +6,24 @@ 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 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 (legacy `App.tsx` with ``)
+## 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.
+
+## Old Frontend System
+
+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:
@@ -34,30 +41,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.
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..062f88fa98 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:
+## 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 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:
+
+```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 as outlined in this section. If you are on the new frontend system, you can skip this.
+
### MyGroupsSidebarItem
The MyGroupsSidebarItem provides quick access to the group(s) the logged in user is a member of directly in the sidebar.
diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md
index 0a79d8afc0..9c9ca15dfa 100644
--- a/plugins/scaffolder/README.md
+++ b/plugins/scaffolder/README.md
@@ -15,13 +15,72 @@ 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 feature 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 [issues with early closure of the `EventStream`](https://github.com/backstage/backstage/issues/5535)
+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 {
+ AnyApiFactory,
+ createApiFactory,
+ discoveryApiRef,
+ fetchApiRef,
+ identityApiRef,
+} from '@backstage/core-plugin-api';
+import { scmIntegrationsApiRef } from '@backstage/integration-react';
+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, start your Backstage backend there,
+and configure the template locations that you want to test.
+
+## Old Frontend System
+
+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`
Add the root page that the scaffolder plugin provides to your app. You can
@@ -78,57 +137,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)
diff --git a/plugins/user-settings/README.md b/plugins/user-settings/README.md
index a27e5ca524..8644001fe1 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 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
+
+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
Add the item to the Sidebar: