paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 48 Packages Projects Releases Wiki Activity

chore: added some more help

Browse Source 
Signed-off-by: benjdlambert <ben@blam.sh>
This commit is contained in:
benjdlambert
2025-08-18 15:01:40 +02:00
parent c986c9c51b
commit d848226f63
1 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/frontend-system/building-apps/08-migrating.md
+16
View File
@@ -652,6 +652,8 @@ At this point you should be able to run the app and see that you're not using th
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.
Migrating across the tabs for the Entity Pages should be as simple as removing the `EntityLayout.Route` for each of the plugins that provide tab content, and then this tab should be sourced from the `EntityContent` extensions created by the plugins themselves which will be automatically detected and added to the App.
### Sidebar
New apps feature a built-in sidebar extension which is created by using the `NavContentBlueprint` in `src/modules/nav/Sidebar.tsx`. The default implementation of the sidebar in this blueprint will render some items explicitly in different groups, and then render the rest of the items which are the other `NavItem` extensions provided by the system.
@@ -792,3 +794,17 @@ createApp({
// ...
});
```
## Troubleshooting
We'd recommend that you install the `app-visualizer` plugin to help your troubleshooting. If you run `yarn add @backstage/plugin-app-visualizer` in `packages/app` it should be automatically added to the sidebar, and available on `/visualizer`.
There is a `tree` mode that can be very helpful in understanding which plugins are being automatically detected and the extensions that they are providing to the system. You should also be able to see any legacy extensions which are being converted and added to the app.
This can be really useful output when raising any issue to the main repository too, so we can dig in to see what's happening with the system.
### I'm seeing duplicate cards for Entity Pages
This is due to using the `entityPage` option with `convertLegacyAppRoot`. Our helper will try to parse out the different cards that are available in your existing page, and add them to the new Entity Pages for you automatically, but the new Entity Pages will automatically include also any of ones that are provided by plugins that are installed into your `packages/app` package.
This means you'll get two copies of the same card. You can remove the card definition from your old Entity Page component safely, as this is now going to be provided by the new system for you.