docs/frontend-system: add docs for gradually migrating entity pages

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2025-03-10 15:26:19 +01:00
parent c89cb14766
commit e21bed7ad3
1 changed files with 78 additions and 1 deletions
@@ -500,7 +500,84 @@ Continue this process for each of your legacy routes until you have migrated all

 ### Entity Pages

-The entity pages are typically defined in `packages/app/src/components/catalog` and rendered as a child of the `/catalog/:namespace/:kind/:name` route. The entity pages are typically quite large and bringing in content from quite a lot of different plugins. At the moment we do not provide a way to gradually migrate entity pages to the new system, although that is planned as a future improvement. This means that the entire entity page and all of its plugins need to be migrated at once, including any other usages of those plugins.
+The entity pages are typically defined in `packages/app/src/components/catalog` and rendered as a child of the `/catalog/:namespace/:kind/:name` route. The entity pages are typically quite large and bringing in content from quite a lot of different plugins. To help gradually migrate entity pages we provide the `entityPage` option in the `convertLegacyApp` helper. This option lets you pass in an entity page app element tree that will be converted to extensions that are added to the features returned from `convertLegacyApp`.
+
+To start the gradual migration of entity pages, add your `entityPages` to the `convertLegacyApp` call:
+
+```tsx title="in packages/app/src/App.tsx"
+/* highlight-remove-next-line */
+const legacyFeatures = convertLegacyApp(routes);
+/* highlight-add-next-line */
+const legacyFeatures = convertLegacyApp(routes, { entityPage });
+```
+
+Next, you will need to fully migrate the catalog plugin itself. This is because only a single version of a plugin can be installed in the app at a time, so in order to start using the new version of the catalog plugin you need to remove all usage of the old one. This includes both the routes and entity pages. You will need to keep the structural helpers for the entity pages, such as `EntityLayout` and `EntitySwitch`, but remove any extensions like the `<CatalogIndexPage/>` and entity cards and content like `<EntityAboutCard/>` and `<EntityOrphanWarning/>`.
+
+Remove the following routes:
+
+```tsx title="in packages/app/src/App.tsx"
+const routes = (
+  <FlatRoutes>
+    ...
+    {/* highlight-remove-start */}
+    <Route path="/catalog" element={<CatalogIndexPage />} />
+    <Route
+      path="/catalog/:namespace/:kind/:name"
+      element={<CatalogEntityPage />}
+    >
+      {entityPage}
+    </Route>
+    {/* highlight-remove-end */}
+    ...
+  </FlatRoutes>
+);
+```
+
+And explicitly install the catalog plugin before the converted legacy features:
+
+```tsx title="in packages/app/src/App.tsx"
+/* highlight-add-next-line */
+import { default as catalogPlugin } from '@backstage/plugin-catalog/alpha';
+
+const app = createApp({
+  /* highlight-remove-next-line */
+  features: [optionsModule, ...legacyFeatures],
+  /* highlight-add-next-line */
+  features: [catalogPlugin, optionsModule, ...legacyFeatures],
+});
+```
+
+If you are not using the default `<CatalogIndexPage />` you can install your custom catalog page as an override for now instead, and fully migrate it to the new system later.
+
+```tsx title="in packages/app/src/App.tsx"
+/* highlight-remove-start */
+const catalogPluginOverride = catalogPlugin.withOverrides({
+  extensions: [
+    catalogPlugin.getExtension('page:catalog').override({
+      params: {
+        loader: async () => (
+          <CatalogIndexPage
+            pagination={{ mode: 'offset', limit: 20 }}
+            filters={<>{/* ... */}</>}
+          />
+        ),
+      },
+    }),
+  ],
+});
+/* highlight-remove-end */
+
+const app = createApp({
+  /* highlight-remove-next-line */
+  features: [catalogPlugin, optionsModule, ...legacyFeatures],
+  /* highlight-add-next-line */
+  features: [catalogPluginOverride, optionsModule, ...legacyFeatures],
+});
+```
+
+At this point you should be able to run the app and see that you're not using the new version of the catalog plugin. If you navigate to the entity pages you will likely see a lot of duplicate content at the bottom of the page. These are the duplicates of the entity cards provided by the catalog plugin itself that we mentioned earlier that you need to remove. Clean up the entity pages by removing cards and content from the catalog plugin such as `<EntityAboutCard/>` and `<EntityOrphanWarning/>`.
+
+Once the cleanup is complete you should be left with clean entity pages that are built using a mix of the old and new frontend system. From this point you can continue to gradually migrate plugins that provide content for the entity pages, until all plugins have been fully moved to the new system and the `entityPage` option can be removed.

 ### Sidebar