From 1e6d69265404ef76754e17eb22a3cc8a94bc8b99 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 14:11:18 +0200 Subject: [PATCH 1/7] docs/frontend-system: new title for architecture migrations section to avoid confusion Signed-off-by: Patrik Oldsberg --- docs/frontend-system/architecture/60-migrations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/frontend-system/architecture/60-migrations.md b/docs/frontend-system/architecture/60-migrations.md index 9e84899dc2..3a33e663f4 100644 --- a/docs/frontend-system/architecture/60-migrations.md +++ b/docs/frontend-system/architecture/60-migrations.md @@ -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.** From 005a88da9606ca079b68b2c16f13474f34967e9e Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 16:07:05 +0200 Subject: [PATCH 2/7] docs/frontend-system: tweaks to the plugin migration guide Signed-off-by: Patrik Oldsberg --- .../building-plugins/05-migrating.md | 27 +++++++++++++------ 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/frontend-system/building-plugins/05-migrating.md b/docs/frontend-system/building-plugins/05-migrating.md index cf4d82002a..b0bd1fd16f 100644 --- a/docs/frontend-system/building-plugins/05-migrating.md +++ b/docs/frontend-system/building-plugins/05-migrating.md @@ -19,7 +19,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: { ... }, @@ -34,12 +34,13 @@ The new `createFrontendPlugin` function doesn't accept apis anymore as apis are ```ts title="my-plugin/src/alpha.ts" 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({ @@ -79,6 +80,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 are responsible 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,9 +94,16 @@ export const FooPage = fooPlugin.provide( ); ``` -it can be migrated as the following: +and the following instruction in the plugin README: ```tsx +} /> +``` + +it can be migrated as the following, keeping in mind that you may need to switch from `.ts` to `.tsx` and import React: + +```tsx +import React from 'react'; import { PageBlueprint } from '@backstage/frontend-plugin-api'; import { compatWrapper, @@ -102,15 +112,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 into the 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(), ), }, From cbd276ebf37dda9a02984de6aefcb0e8c1405981 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 16:21:53 +0200 Subject: [PATCH 3/7] docs/frontend-system: polish common extension blueprint docs Signed-off-by: Patrik Oldsberg --- .../03-common-extension-blueprints.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/frontend-system/building-plugins/03-common-extension-blueprints.md b/docs/frontend-system/building-plugins/03-common-extension-blueprints.md index d08de7012d..b437a44552 100644 --- a/docs/frontend-system/building-plugins/03-common-extension-blueprints.md +++ b/docs/frontend-system/building-plugins/03-common-extension-blueprints.md @@ -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`. From 08b11ad513872797261abf63bacd4591dc9a89ce Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 16:40:29 +0200 Subject: [PATCH 4/7] docs/frontend-system: highlight and fix new alpha entry point in migration docs Signed-off-by: Patrik Oldsberg --- .../building-plugins/05-migrating.md | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/frontend-system/building-plugins/05-migrating.md b/docs/frontend-system/building-plugins/05-migrating.md index b0bd1fd16f..169fcacafc 100644 --- a/docs/frontend-system/building-plugins/05-migrating.md +++ b/docs/frontend-system/building-plugins/05-migrating.md @@ -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" @@ -29,10 +35,9 @@ 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'; @@ -53,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": [ @@ -130,7 +135,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({ @@ -221,7 +226,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({ From cbd9b98805296b048aebe43811b829ccab53ca22 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 18:39:29 +0200 Subject: [PATCH 5/7] Update docs/frontend-system/building-plugins/05-migrating.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Patrik Oldsberg --- docs/frontend-system/building-plugins/05-migrating.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/frontend-system/building-plugins/05-migrating.md b/docs/frontend-system/building-plugins/05-migrating.md index 169fcacafc..442fc1d5c6 100644 --- a/docs/frontend-system/building-plugins/05-migrating.md +++ b/docs/frontend-system/building-plugins/05-migrating.md @@ -120,7 +120,7 @@ const fooPage = PageBlueprint.make({ // 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: () => From d3f90ed3eb3b865920b27ce92d927c603057c353 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 18:39:43 +0200 Subject: [PATCH 6/7] Update docs/frontend-system/building-plugins/05-migrating.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Patrik Oldsberg --- docs/frontend-system/building-plugins/05-migrating.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/frontend-system/building-plugins/05-migrating.md b/docs/frontend-system/building-plugins/05-migrating.md index 442fc1d5c6..00316df2eb 100644 --- a/docs/frontend-system/building-plugins/05-migrating.md +++ b/docs/frontend-system/building-plugins/05-migrating.md @@ -85,7 +85,7 @@ 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 are responsible 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. +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: From 65dd7b53be8ee62afda54929f8965a5aad1e7a61 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Apr 2025 19:05:55 +0200 Subject: [PATCH 7/7] docs/frontend-system: remove instruction to add React import Signed-off-by: Patrik Oldsberg --- docs/frontend-system/building-plugins/05-migrating.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/frontend-system/building-plugins/05-migrating.md b/docs/frontend-system/building-plugins/05-migrating.md index 00316df2eb..846e2c944b 100644 --- a/docs/frontend-system/building-plugins/05-migrating.md +++ b/docs/frontend-system/building-plugins/05-migrating.md @@ -105,10 +105,9 @@ and the following instruction in the plugin README: } /> ``` -it can be migrated as the following, keeping in mind that you may need to switch from `.ts` to `.tsx` and import React: +it can be migrated as the following, keeping in mind that you may need to switch from `.ts` to `.tsx`: ```tsx -import React from 'react'; import { PageBlueprint } from '@backstage/frontend-plugin-api'; import { compatWrapper,