Merge pull request #29514 from backstage/rugvip/polish
docs/frontend-system: polish plugin migration docs
This commit is contained in:
Patrik Oldsberg
@@ -1,9 +1,9 @@
|
||||
---
|
||||
id: migrations
|
||||
title: Frontend System Migrations
|
||||
sidebar_label: Migrations
|
||||
title: Frontend System Changelog
|
||||
sidebar_label: Changelog
|
||||
# prettier-ignore
|
||||
description: Migration documentation for different versions of the frontend system core APIs.
|
||||
description: Changelog documentation for different versions of the frontend system core APIs.
|
||||
---
|
||||
|
||||
> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
|
||||
|
||||
@@ -10,7 +10,7 @@ description: Extension blueprints provided by the frontend system and core featu
|
||||
|
||||
This section covers many of the [extension blueprints](../architecture/23-extension-blueprints.md) available at your disposal when building Backstage frontend plugins.
|
||||
|
||||
## Built-in extension blueprints
|
||||
## Extension blueprints in `@backstage/frontend-plugin-api`
|
||||
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Backstage frontend framework itself.
|
||||
|
||||
@@ -46,18 +46,26 @@ Icon bundle extensions provide the ability to replace or provide new icons to th
|
||||
|
||||
Translation extension provide custom translation messages for the app. They can be used both to override the default english messages to custom ones, as well as provide translations for additional languages.
|
||||
|
||||
## Core feature extension blueprints
|
||||
## Extension blueprints in `@backstage/plugin-catalog-react/alpha`
|
||||
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Backstage core feature plugins.
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Catalog plugin.
|
||||
|
||||
### EntityCard - [Reference](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/report-alpha.api.md)
|
||||
### EntityCard - [Example](https://github.com/backstage/backstage/blob/75e79518eafc6e6eb55585f166667418419662de/plugins/org/src/alpha.tsx#L27-L36)
|
||||
|
||||
Creates entity cards to be displayed on the entity pages of the catalog plugin. Exported as `EntityCardBlueprint`.
|
||||
|
||||
### EntityContent - [Reference](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/report-alpha.api.md)
|
||||
Avoid using `convertLegacyEntityCardExtension` from `@backstage/core-compat-api` to convert legacy entity card extensions to the new system. Instead, use the `EntityCardBlueprint` directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.
|
||||
|
||||
### EntityContent - [Example](https://github.com/backstage/backstage/blob/cd71065a02bed740011daee96a865108a785dff6/plugins/kubernetes/src/alpha/entityContents.tsx#L22-L34)
|
||||
|
||||
Creates entity content to be displayed on the entity pages of the catalog plugin. Exported as `EntityContentBlueprint`.
|
||||
|
||||
### SearchResultListItem - [Reference](https://github.com/backstage/backstage/blob/master/plugins/search-react/report-alpha.api.md)
|
||||
Avoid using `convertLegacyEntityContentExtension` from `@backstage/core-compat-api` to convert legacy entity content extensions to the new system. Instead, use the `EntityContentBlueprint` directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.
|
||||
|
||||
## Extension blueprints in `@backstage/plugin-search-react/alpha`
|
||||
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Search plugin.
|
||||
|
||||
### SearchResultListItem - [Example](https://github.com/backstage/backstage/blob/8cb9a85596a5417a004811ffa429527b17ce9b72/plugins/catalog/src/alpha/searchResultItems.tsx#L19-L27)
|
||||
|
||||
Creates search result list items for different types of search results, to be displayed in search result lists. Exported as `SearchResultListItemBlueprint`.
|
||||
|
||||
@@ -12,6 +12,12 @@ The main concept is that routes, components, apis are now extensions. You can us
|
||||
|
||||
## Migrating the plugin
|
||||
|
||||
:::note Note
|
||||
|
||||
Unless you are migrating a plugin that is only used within your own project, we recommend all plugins to keep support for the old system intact. The code added in these examples should be added to a new `src/alpha.tsx` entry point of your plugin.
|
||||
|
||||
:::
|
||||
|
||||
In the legacy frontend system a plugin was defined in its own `plugin.ts` file as following:
|
||||
|
||||
```ts title="my-plugin/src/plugin.ts"
|
||||
@@ -19,7 +25,7 @@ In the legacy frontend system a plugin was defined in its own `plugin.ts` file a
|
||||
|
||||
export const myPlugin = createPlugin({
|
||||
id: 'my-plugin',
|
||||
apis: [],
|
||||
apis: [ ... ],
|
||||
routes: {
|
||||
...
|
||||
},
|
||||
@@ -29,17 +35,17 @@ In the legacy frontend system a plugin was defined in its own `plugin.ts` file a
|
||||
});
|
||||
```
|
||||
|
||||
In order to migrate the actual definition of the plugin you need to recreate the plugin using the new `createFrontendPlugin` utility exported by `@backstage/frontend-plugin-api`.
|
||||
The new `createFrontendPlugin` function doesn't accept apis anymore as apis are now extensions.
|
||||
In order to migrate the actual definition of the plugin you need to recreate the plugin using the new `createFrontendPlugin` utility exported by `@backstage/frontend-plugin-api`. The new `createFrontendPlugin` function doesn't accept apis anymore as apis are now extensions.
|
||||
|
||||
```ts title="my-plugin/src/alpha.ts"
|
||||
```ts title="my-plugin/src/alpha.tsx"
|
||||
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
||||
import { convertLegacyRouteRefs } from '@backstage/core-compat-api';
|
||||
|
||||
export default createFrontendPlugin({
|
||||
id: 'my-plugin',
|
||||
// bind all the extensions to the plugin
|
||||
/* highlight-next-line */
|
||||
extensions: [],
|
||||
extensions: [/* APIs will go here, but don't worry about those yet */],
|
||||
// convert old route refs to the new system
|
||||
/* highlight-next-line */
|
||||
routes: convertLegacyRouteRefs({
|
||||
@@ -52,20 +58,20 @@ The new `createFrontendPlugin` function doesn't accept apis anymore as apis are
|
||||
});
|
||||
```
|
||||
|
||||
The code above binds all the extensions to the plugin. _Important_: Make sure to export the plugin as default export of your package as a separate entrypoint, preferably `/alpha`, as suggested by the code snippet above. Make sure `src/alpha.ts` is exported in your `package.json`:
|
||||
The code above binds all the extensions to the plugin. _Important_: Make sure to export the plugin as default export of your package as a separate entrypoint, preferably `/alpha`, as suggested by the code snippet above. Make sure `src/alpha.tsx` is exported in your `package.json`:
|
||||
|
||||
```ts title="my-plugin/package.json"
|
||||
"exports": {
|
||||
".": "./src/index.ts",
|
||||
/* highlight-add-next-line */
|
||||
"./alpha": "./src/alpha.ts",
|
||||
"./alpha": "./src/alpha.tsx",
|
||||
"./package.json": "./package.json"
|
||||
},
|
||||
"typesVersions": {
|
||||
"*": {
|
||||
/* highlight-add-start */
|
||||
"alpha": [
|
||||
"src/alpha.ts"
|
||||
"src/alpha.tsx"
|
||||
],
|
||||
/* highlight-add-end */
|
||||
"package.json": [
|
||||
@@ -79,6 +85,8 @@ The code above binds all the extensions to the plugin. _Important_: Make sure to
|
||||
|
||||
Pages that were previously created using the `createRoutableExtension` extension function can be migrated to the new Frontend System using the `PageBlueprint` [extension blueprint](../architecture/23-extension-blueprints.md), exported by `@backstage/frontend-plugin-api`.
|
||||
|
||||
In the new system plugins provide more information than they used to. For example, the plugin is now responsible for providing the path for the page, rather than it being part of the app code.
|
||||
|
||||
For example, given the following page:
|
||||
|
||||
```ts
|
||||
@@ -91,7 +99,13 @@ export const FooPage = fooPlugin.provide(
|
||||
);
|
||||
```
|
||||
|
||||
it can be migrated as the following:
|
||||
and the following instruction in the plugin README:
|
||||
|
||||
```tsx
|
||||
<Route path="/foo" element={<FooPage />} />
|
||||
```
|
||||
|
||||
it can be migrated as the following, keeping in mind that you may need to switch from `.ts` to `.tsx`:
|
||||
|
||||
```tsx
|
||||
import { PageBlueprint } from '@backstage/frontend-plugin-api';
|
||||
@@ -102,15 +116,16 @@ import {
|
||||
|
||||
const fooPage = PageBlueprint.make({
|
||||
params: {
|
||||
// This is the path that was previously defined in the app code.
|
||||
// It's labelled as the default one because it can be changed via configuration.
|
||||
defaultPath: '/foo',
|
||||
// you can reuse the existing routeRef
|
||||
// by wrapping into the convertLegacyRouteRef.
|
||||
// You can reuse the existing routeRef by wrapping it with convertLegacyRouteRef.
|
||||
routeRef: convertLegacyRouteRef(rootRouteRef),
|
||||
// these inputs usually match the props required by the component.
|
||||
loader: ({ inputs }) =>
|
||||
loader: () =>
|
||||
import('./components/').then(m =>
|
||||
// The compatWrapper utility allows you to use the existing
|
||||
// legacy frontend utilities used internally by the components.
|
||||
// The compatWrapper utility allows you to keep using @backstage/core-plugin-api in the
|
||||
// implementation of the component and switch to @backstage/frontend-plugin-api later.
|
||||
compatWrapper(<m.FooPage />),
|
||||
),
|
||||
},
|
||||
@@ -119,7 +134,7 @@ const fooPage = PageBlueprint.make({
|
||||
|
||||
Then add the `fooPage` extension to the plugin:
|
||||
|
||||
```ts title="my-plugin/src/alpha.ts"
|
||||
```ts title="my-plugin/src/alpha.tsx"
|
||||
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
||||
|
||||
export default createFrontendPlugin({
|
||||
@@ -210,7 +225,7 @@ const exampleWorkApi = ApiBlueprint.make({
|
||||
|
||||
Finally, let's add the `exampleWorkApi` extension to the plugin:
|
||||
|
||||
```ts title="my-plugin/src/alpha.ts"
|
||||
```ts title="my-plugin/src/alpha.tsx"
|
||||
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
||||
|
||||
export default createFrontendPlugin({
|
||||
|
||||
Reference in New Issue
Block a user