From 26da51fbeb478b3f18e7cdd91f94baefaac37e69 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 20 Jan 2024 10:02:21 +0100 Subject: [PATCH] docs/frontend-system: app migration review fixes Signed-off-by: Patrik Oldsberg --- docs/frontend-system/building-apps/08-migrating.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md index a4e75f5390..f6804f6bb8 100644 --- a/docs/frontend-system/building-apps/08-migrating.md +++ b/docs/frontend-system/building-apps/08-migrating.md @@ -21,9 +21,9 @@ import { createApp } from '@backstage/app-defaults'; import { createApp } from '@backstage/frontend-app-api'; ``` -This immediate switch will lead to a lot of breakages that we need to fix. Let's start by addressing `app.createRoot(...)`, which no longer accepts any arguments. +This immediate switch will lead to a lot of breakages that we need to fix. -Let's start by addressing the change to `app.createRoot(...)`, which no longer accepts any arguments. This represents a fundamental change that the new frontend system introduces. In the old system the app element tree that you passed to `app.createRoot(...)` was the primary way that you installed and configured plugins and features in your app. In the new system this is instead replaced by extensions that are wired together to an extension tree in the new system. Much more responsibility has been shifted to plugins in the new system, for example you no longer have to manually provide the route path for each plugin page, but instead only configure it if you want to override the default. For more information on how the new system works, see the [architecture](../architecture/01-index.md) section. +Let's start by addressing the change to `app.createRoot(...)`, which no longer accepts any arguments. This represents a fundamental change that the new frontend system introduces. In the old system the app element tree that you passed to `app.createRoot(...)` was the primary way that you installed and configured plugins and features in your app. In the new system this is instead replaced by extensions that are wired together into an extension tree. Much more responsibility has now been shifted to plugins, for example you no longer have to manually provide the route path for each plugin page, but instead only configure it if you want to override the default. For more information on how the new system works, see the [architecture](../architecture/01-index.md) section. Given that the app element tree is most of what builds up the app, it's likely also going to be the majority of the migration effort. In order to make the migration as smooth as possible we have provided a helper that lets you convert an existing app element tree into plugins that you can install in a new app. This in turn allows for a gradual migration of individual plugins, rather than needing to migrate the entire app structure at once. @@ -102,13 +102,17 @@ For example, assuming you have a `lightTheme` extension that you want to add to ```ts const app = createApp({ features: [ + // highlight-add-start createExtensionOverrides({ extensions: [lightTheme], }), + // highlight-add-end ], }); ``` +You can then also add any additional extensions that you may need to create as part of this migration to the `extensions` array as well. + ### `apis` [Utility API](../utility-apis/01-index.md) factories are now installed as extensions instead. Pass the existing factory to `createApiExtension` and install it in the app. For more information, see the section on [configuring Utility APIs](../utility-apis/04-configuring.md). @@ -260,8 +264,8 @@ For example, if both the `catalogPlugin` and `scaffolderPlugin` are legacy plugi const app = createApp({ features: convertLegacyApp(...), bindRoutes({ bind }) { - bind(convertLegacyRouteRefs(catalogPlugin.createComponent), { - registerApi: convertLegacyRouteRef(scaffolderPlugin.routes.root), + bind(convertLegacyRouteRefs(catalogPlugin.externalRoutes), { + createComponent: convertLegacyRouteRef(scaffolderPlugin.routes.root), }); }, });