diff --git a/docs/frontend-system/architecture/10-app.md b/docs/frontend-system/architecture/10-app.md index b9cbedc025..22457bcb30 100644 --- a/docs/frontend-system/architecture/10-app.md +++ b/docs/frontend-system/architecture/10-app.md @@ -42,37 +42,11 @@ A common type of data that is shared between extensions is React elements and co ## Feature Discovery -For a practical guide on how to install plugins in your app, see [Installing Plugins](../building-apps/05-installing-plugins.md). - App feature discovery lets you automatically discover and install features provided by dependencies in your app. In practice, it means that you don't need to manually `import` features in code, but they are instead installed as soon as you add them as a dependency in your `package.json`. 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 7a9f792f45..bd9a0fbae5 100644 --- a/docs/frontend-system/building-apps/01-index.md +++ b/docs/frontend-system/building-apps/01-index.md @@ -65,7 +65,7 @@ Linking routes from different plugins requires this configuration. You can do th ### Install plugins -Plugins are typically installed by adding them as dependencies of your app package and relying on package 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). +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 @@ -79,7 +79,7 @@ Previously you would customize the application routes, components, apis, sidebar ### Install features manually -Most plugins are installed automatically through [package discovery](./05-installing-plugins.md#package-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: +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 index 72eeb465b0..9007ce0eb1 100644 --- a/docs/frontend-system/building-apps/05-installing-plugins.md +++ b/docs/frontend-system/building-apps/05-installing-plugins.md @@ -15,11 +15,11 @@ To install a plugin, add it as a dependency to your app package. For example, to 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. +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. -## Package discovery +## Feature 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`: +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: @@ -43,13 +43,13 @@ app: - '@backstage/plugin-catalog' ``` -Package 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. +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 package discovery works under the hood, see the [Feature Discovery](../architecture/10-app.md#feature-discovery) architecture documentation. +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 [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`: +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'; @@ -62,7 +62,7 @@ const app = createApp({ 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. +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. diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 7085f9b082..af39a825d8 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -32,7 +32,7 @@ Now, let's get started by installing the home plugin and creating a simple homep yarn --cwd packages/app add @backstage/plugin-home ``` -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). +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). ### 2. Configure the homepage as your root route diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index f6f52cbcae..5650b378f5 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -30,7 +30,7 @@ To link that a component provides or consumes an API, see the [`providesApis`](h yarn --cwd packages/app add @backstage/plugin-api-docs ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). You can enable entity cards and tabs on the catalog entity page through configuration: diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md index 38ea902271..b1af843190 100644 --- a/plugins/catalog-graph/README.md +++ b/plugins/catalog-graph/README.md @@ -27,7 +27,7 @@ The plugin comes with these features: yarn --cwd packages/app add @backstage/plugin-catalog-graph ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). To enable the entity relations graph card on the catalog entity page, add the following configuration: diff --git a/plugins/catalog-import/README.md b/plugins/catalog-import/README.md index f8174b63ff..ba98d19f0b 100644 --- a/plugins/catalog-import/README.md +++ b/plugins/catalog-import/README.md @@ -22,7 +22,7 @@ Install the Catalog Import Plugin: yarn --cwd packages/app add @backstage/plugin-catalog-import ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). ## Customizations diff --git a/plugins/catalog-unprocessed-entities/README.md b/plugins/catalog-unprocessed-entities/README.md index 13bca8b04f..8cdf275851 100644 --- a/plugins/catalog-unprocessed-entities/README.md +++ b/plugins/catalog-unprocessed-entities/README.md @@ -32,7 +32,7 @@ Requires the `@backstage/plugin-catalog-backend-module-unprocessed` module to be yarn --cwd packages/app add @backstage/plugin-catalog-unprocessed-entities ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). You can optionally add unprocessed entities as a tab in DevTools through configuration: diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index 993f0e34f2..ae8ddd1033 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -20,7 +20,7 @@ plugin, if you previously removed it. yarn --cwd packages/app add @backstage/plugin-catalog ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). ## Old Frontend System diff --git a/plugins/devtools/README.md b/plugins/devtools/README.md index 54aa1f492d..b049839861 100644 --- a/plugins/devtools/README.md +++ b/plugins/devtools/README.md @@ -73,7 +73,7 @@ Install the `@backstage/plugin-devtools` package in your frontend app: yarn --cwd packages/app add @backstage/plugin-devtools ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). ## Customizing diff --git a/plugins/home/README.md b/plugins/home/README.md index e75f28e6ed..2c46530c3d 100644 --- a/plugins/home/README.md +++ b/plugins/home/README.md @@ -11,7 +11,7 @@ For App Integrators, the system is designed to be composable to give total freed yarn --cwd packages/app add @backstage/plugin-home ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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: diff --git a/plugins/kubernetes/README.md b/plugins/kubernetes/README.md index 42410ca92d..baf0ab42a3 100644 --- a/plugins/kubernetes/README.md +++ b/plugins/kubernetes/README.md @@ -21,7 +21,7 @@ This plugin must be explicitly added to a Backstage app, along with its peer bac yarn --cwd packages/app add @backstage/plugin-kubernetes ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). It requires configuration in the Backstage `app-config.yaml` to connect to a Kubernetes API control plane. diff --git a/plugins/mui-to-bui/README.md b/plugins/mui-to-bui/README.md index d5f08e6d03..4217f103a8 100644 --- a/plugins/mui-to-bui/README.md +++ b/plugins/mui-to-bui/README.md @@ -12,7 +12,7 @@ Add the dependency to your app: yarn --cwd packages/app add @backstage/plugin-mui-to-bui ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). ## Accessing the Themer page diff --git a/plugins/org/README.md b/plugins/org/README.md index edf7cc4a89..9c8050e940 100644 --- a/plugins/org/README.md +++ b/plugins/org/README.md @@ -25,7 +25,7 @@ Here's an example of what the User Profile looks like: yarn --cwd packages/app add @backstage/plugin-org ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). You can enable entity cards on the catalog entity page through configuration: diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index ff09796033..6a2ad697b5 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -20,7 +20,7 @@ the plugin, if you previously removed it. yarn --cwd packages/app add @backstage/plugin-scaffolder ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). ### Troubleshooting diff --git a/plugins/user-settings/README.md b/plugins/user-settings/README.md index b4c283d275..2fa5e5db39 100644 --- a/plugins/user-settings/README.md +++ b/plugins/user-settings/README.md @@ -18,7 +18,7 @@ for installation instructions. yarn --cwd packages/app add @backstage/plugin-user-settings ``` -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](https://backstage.io/docs/frontend-system/building-apps/installing-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). ## Old Frontend System