Merge pull request #33113 from backstage/rugvip/docs-frontend-plugin-installation
docs: default frontend plugin docs to the new frontend system
This commit is contained in:
Patrik Oldsberg
@@ -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
|
||||
|
||||
|
||||
@@ -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';
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user