docs/frontend-system: document plugin info system
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
@@ -77,3 +77,98 @@ app:
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Plugin Info Resolution
|
||||
|
||||
When a plugin is installed in an app it may provide sources of information about the plugin that can be useful to end users and admins. This includes things like what version of a plugin is running, what team owns the plugin, and who to contact for support. You can read more about how the plugins provide this information in the [plugins `info` option section](./15-plugins.md#info).
|
||||
|
||||
By default the app will pick a few common fields from `package.json` files, and assume that the opaque manifests are `catalog-info.yaml` files that some information can be gathered from too. This information will then be available via the `info()` method on plugin instances, returning a structure of the `FrontendPluginInfo` type.
|
||||
|
||||
### Extending Plugin Info
|
||||
|
||||
The default plugin info is intended as a base to build upon. As part of setting up an app you can both customize the way that the plugin info is resolved, as well as extend the `FrontendPluginInfo` type to include more information.
|
||||
|
||||
In order to extend the `FrontendPluginInfo` type you use [TypeScript module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation). This makes it possible to extend the `FrontendPluginInfo` inferface with additional fields, which you can then add custom resolution logic for as well as access within the app. For example, you might add a `slackChannel` field as follows:
|
||||
|
||||
```ts
|
||||
declare module '@backstage/frontend-plugin-api' {
|
||||
interface FrontendPluginInfo {
|
||||
/**
|
||||
* The slack channel to use for support requests for this plugin.
|
||||
*/
|
||||
slackChannel?: string;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Customizing Plugin Info Resolution
|
||||
|
||||
With the new `slackChannel` field in place, we now need to provide a custom resolver that knows how to extract this information from the plugin information sources. This is done by passing a custom `pluginInfoResolver` to `createApp`, which in our example is declared like this:
|
||||
|
||||
```ts title="pluginInfoResolver.ts"
|
||||
import { createPluginInfoResolver } from '@backstage/frontend-plugin-api';
|
||||
|
||||
// It is recommended to keep the above module augmentation in this file too
|
||||
|
||||
export const pluginInfoResolver: FrontendPluginInfoResolver = async ctx => {
|
||||
// In our particular example app we assume that all plugin manifests are catalog-info.yaml files
|
||||
const manifest = (await ctx.manifest?.()) as Entity | undefined;
|
||||
|
||||
// Call the default resolver to populate common fields
|
||||
const { info } = await ctx.defaultResolver({
|
||||
packageJson: await ctx.packageJson(),
|
||||
manifest: manifest,
|
||||
});
|
||||
|
||||
// In this example the catalog model has been extended with a metadata.slackChannel field
|
||||
const slackChannel = manifest?.metadata?.slackChannel?.toString();
|
||||
|
||||
if (slackChannel) {
|
||||
info.slackChannel = slackChannel;
|
||||
info.links = [
|
||||
...(info.links ?? []),
|
||||
{
|
||||
title: 'Slack Channel',
|
||||
url: `https://our-workspace.enterprise.slack.com/archives/${slackChannel}`,
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
return { info };
|
||||
};
|
||||
```
|
||||
|
||||
And included in the app as follows:
|
||||
|
||||
```ts title="App.tsx"
|
||||
import { pluginInfoResolver } from './pluginInfoResolver';
|
||||
|
||||
const app = createApp({
|
||||
pluginInfoResolver,
|
||||
// ... other options
|
||||
});
|
||||
```
|
||||
|
||||
### Overriding Plugin Info
|
||||
|
||||
Another way to customize the plugin info is to use the `app.pluginOverrides` static configuration key. These overrides are applied after the plugin info has been resolved as a final step before making it available to users. These overrides are particularly useful to override information in third-party plugins. For example, if your organization has an individual team that is responsible for the maintenance of the Software Catalog, you might configure the following override:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
pluginOverrides:
|
||||
- match:
|
||||
pluginId: catalog
|
||||
info:
|
||||
ownerEntityRefs: [catalog-owners]
|
||||
```
|
||||
|
||||
You can match on both the `pluginId` and/or `packageName` of the plugin, although the `packageName` will only be supported if the plugin provides an loader for the `package.json` file. Using `/<pattern>/` you are also able to use a regex pattern for this matching. For example, if you wanted to override the owner for all plugins from the `@acme` namespace, you could do the following:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
pluginOverrides:
|
||||
- match:
|
||||
packageName: /@acme/.*/
|
||||
info:
|
||||
ownerEntityRefs: [acme-owners]
|
||||
```
|
||||
|
||||
@@ -53,6 +53,35 @@ These are the routes that the plugin exposes to the app. The `routes` option dec
|
||||
|
||||
This is a list of feature flag declarations that your plugin provides to the app. This makes sure that the feature flags are correctly registered and can be toggled in the app. To read a feature flag you can use the feature flags [Utility API](../architecture/33-utility-apis.md), accessible via `featureFlagsApiRef`.
|
||||
|
||||
### `info` option
|
||||
|
||||
This options is used to provide loaders for different sources of information about the plugin that may be useful to users and admins. The two available loaders are `packageJson` and `manifest`, and a plugin can use either or both as needed. The resulting information is available via the `info()` method on the plugin instance once it is installed in an app, but it is up to each app to decide how to derive the information from the provided sources.
|
||||
|
||||
The `info.packageJson` loader **MUST** be used by all plugins that are implemented within their own package, and it should load the `package.json` file for the plugin package. Typical usage looks like this:
|
||||
|
||||
```ts
|
||||
export default createFrontendPlugin({
|
||||
pluginId: 'my-plugin',
|
||||
info: {
|
||||
packageJson: () => import('../package.json'),
|
||||
},
|
||||
extensions: [...],
|
||||
});
|
||||
```
|
||||
|
||||
The `info.manifest` loader is used to point to an opaque plugin manifest. This **MUST ONLY** be used by plugins that are intended for use within a single organization. Plugins that are published to an open package registry should **NOT** use this loader. The loader is useful for adding additional internal metadata associated with the plugin, and it is up to the Backstage app to decide how these manifests are parsed and used. The default manifest parser in an app created with `createApp` from `@backstage/frontend-defaults` is able to parse the default `catalog-info.yaml` format and built-in fields such as `metadata.links` and `spec.owner`.
|
||||
|
||||
Typical usage looks like this:
|
||||
|
||||
```ts
|
||||
export default createFrontendPlugin({
|
||||
pluginId: '...',
|
||||
info: {
|
||||
manifest: () => import('../catalog-info.yaml'),
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Installing a Plugin in an App
|
||||
|
||||
A plugin instance is considered a frontend feature and can be installed directly in any Backstage frontend app. See the [app documentation](./10-app.md) for more information about the different ways in which you can install new features in an app.
|
||||
|
||||
Reference in New Issue
Block a user