From d031c9fe0f27bb955f01c56c4276828c557701e5 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 25 Mar 2026 10:52:48 +0100 Subject: [PATCH] docs: fix missing import and replace deprecated HeaderPage with Header Signed-off-by: Patrik Oldsberg Made-with: Cursor --- docs/.well-known/skills/index.json | 6 +++--- .../skills/mui-to-bui-migration/SKILL.md | 2 +- .../SKILL.md | 14 ++++++------- .../SKILL.md | 21 +++++++++++-------- 4 files changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/.well-known/skills/index.json b/docs/.well-known/skills/index.json index 8327a19692..e66c7ea791 100644 --- a/docs/.well-known/skills/index.json +++ b/docs/.well-known/skills/index.json @@ -7,17 +7,17 @@ }, { "name": "app-frontend-system-migration", - "description": "Migrate a Backstage app from the old frontend system to the new extension-based frontend system. Use this skill when migrating packages/app from createApp (app-defaults) to createApp (frontend-defaults), converting routes, sidebar, plugins, and other app-level configuration.", + "description": "Migrate a Backstage app from the old frontend system to the new one. Use this skill when converting an app to use the new extension-based frontend system, including the hybrid migration phase and the full migration of routes, sidebar, plugins, APIs, themes, and other app-level concerns.", "files": ["SKILL.md"] }, { "name": "plugin-new-frontend-system-support", - "description": "Add new frontend system support to an existing Backstage plugin while maintaining backward compatibility with the old system. Use this skill when adding an alpha entry point, creating PageBlueprint/SubPageBlueprint extensions, and implementing the dual-header pattern (old Header vs new HeaderPage/PluginHeader).", + "description": "Add new frontend system support to an existing Backstage plugin while keeping the old system working. Use this skill for published or shared plugins that need to work in both old and new frontend system apps.", "files": ["SKILL.md"] }, { "name": "plugin-full-frontend-system-migration", - "description": "Fully migrate an existing Backstage plugin to the new frontend system, removing all old system dependencies. Use this skill when converting a plugin to exclusively use @backstage/frontend-plugin-api, replacing internal routing with PageBlueprint/SubPageBlueprint, adopting Backstage UI headers and page layout, and removing @backstage/core-plugin-api usage.", + "description": "Fully migrate a Backstage plugin to the new frontend system, dropping all old system support. Use this skill for internal plugins that only need to run in a single app, or when you are ready to remove backward compatibility entirely.", "files": ["SKILL.md"] } ] diff --git a/docs/.well-known/skills/mui-to-bui-migration/SKILL.md b/docs/.well-known/skills/mui-to-bui-migration/SKILL.md index b621ce1045..cb2d037d4c 100644 --- a/docs/.well-known/skills/mui-to-bui-migration/SKILL.md +++ b/docs/.well-known/skills/mui-to-bui-migration/SKILL.md @@ -43,7 +43,7 @@ Before starting migration: - `Checkbox` - Checkbox input - `Dialog` - Modal dialogs (`DialogTrigger`, `Dialog`, `DialogHeader`, `DialogBody`, `DialogFooter`) - `Header` - Page headers -- `HeaderPage` - Full page header component +- `Header` - Full page header component - `Link` - Navigation links - `Menu` - Dropdown menus (`MenuTrigger`, `Menu`, `MenuItem`) - `PasswordField` - Password input field diff --git a/docs/.well-known/skills/plugin-full-frontend-system-migration/SKILL.md b/docs/.well-known/skills/plugin-full-frontend-system-migration/SKILL.md index 6afd950bfe..b8786211c3 100644 --- a/docs/.well-known/skills/plugin-full-frontend-system-migration/SKILL.md +++ b/docs/.well-known/skills/plugin-full-frontend-system-migration/SKILL.md @@ -226,19 +226,19 @@ The `MyPage` component should **not** include `Page`, `Header`, or `PageWithHead The `title` and `icon` params on `PageBlueprint` are only needed if they should differ from the plugin's own `title` and `icon` (set in `createFrontendPlugin`). If omitted, the plugin-level values are used. -### Page with `HeaderPage` for Custom Actions +### Page with `Header` for Custom Actions -If your page needs a subtitle or action buttons below the framework header, use `HeaderPage` from `@backstage/ui`: +If your page needs a subtitle or action buttons below the framework header, use `Header` from `@backstage/ui`: ```tsx // src/components/MyPage/MyPage.tsx -import { HeaderPage } from '@backstage/ui'; +import { Header } from '@backstage/ui'; import { Content } from '@backstage/core-components'; export function MyPage() { return ( <> - @@ -443,9 +443,9 @@ With the full migration, page components should use `@backstage/ui` components a Key page-level changes: - Replace `PageWithHeader` / `Page` + `Header` with framework-provided `PluginHeader` (automatic via `PageLayout`) -- Use `HeaderPage` from `@backstage/ui` for optional subtitle/custom actions +- Use `Header` from `@backstage/ui` for optional subtitle/custom actions - Use `Content` from `@backstage/core-components` for page body padding (this is still used even in NFS pages) -- Replace `ContentHeader` with `HeaderPage`'s `customActions` prop +- Replace `ContentHeader` with `Header`'s `customActions` prop - Replace `HeaderTabs` with `SubPageBlueprint` (tabs are rendered by the framework) ## Real Example: Auth Plugin (Fully Migrated) @@ -523,7 +523,7 @@ export const tasksSubPage = SubPageBlueprint.make({ 4. [ ] Convert pages to `PageBlueprint` 5. [ ] Replace internal tab routing with `SubPageBlueprint` where appropriate 6. [ ] Remove `Page`/`Header`/`PageWithHeader` from page components -7. [ ] Add `HeaderPage` from `@backstage/ui` where subtitle/custom actions are needed +7. [ ] Add `Header` from `@backstage/ui` where subtitle/custom actions are needed 8. [ ] Replace `HeaderTabs` with `SubPageBlueprint` tabs 9. [ ] Update all `@backstage/core-plugin-api` imports to `@backstage/frontend-plugin-api` 10. [ ] Handle `useRouteRef` possibly returning `undefined` diff --git a/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md b/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md index b980984ff8..2bb0bf4da3 100644 --- a/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md +++ b/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md @@ -22,7 +22,10 @@ Create `src/alpha.tsx` (or `src/alpha/index.ts` for larger plugins) with a `crea ```tsx // src/alpha.tsx -import { createFrontendPlugin } from '@backstage/frontend-plugin-api'; +import { + createFrontendPlugin, + PageBlueprint, +} from '@backstage/frontend-plugin-api'; import { RiToolsLine } from '@remixicon/react'; import { rootRouteRef } from './routes'; @@ -96,7 +99,7 @@ import { ContentHeader, SupportButton, } from '@backstage/core-components'; -import { HeaderPage } from '@backstage/ui'; +import { Header } from '@backstage/ui'; // Used by the OLD system — includes the full page shell export function MyPage() { @@ -117,7 +120,7 @@ export function MyPage() { export function NfsMyPage() { return ( <> - Some help text} /> @@ -132,8 +135,8 @@ export function NfsMyPage() { Key differences in the NFS variant: - **No `Page`/`PageWithHeader`** — the framework provides the outer page shell -- **`HeaderPage` from `@backstage/ui`** is optional — use it only if you need a subtitle or custom actions below the framework header -- **No `ContentHeader`** — actions move to `HeaderPage`'s `customActions` prop +- **`Header` from `@backstage/ui`** is optional — use it only if you need a subtitle or custom actions below the framework header +- **No `ContentHeader`** — actions move to `Header`'s `customActions` prop - The shared `` component contains the actual page body ### Forwarding Customization Props @@ -376,7 +379,7 @@ The same applies to other refs like API refs and route refs: keep them exported - New: `plugins/catalog/src/alpha/plugin.tsx` — `createFrontendPlugin` with `PageBlueprint` - Header split: `plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx` - `BaseCatalogPage` (old) uses `PageWithHeader` + `ContentHeader` - - `NfsBaseCatalogPage` (new) uses `HeaderPage` from `@backstage/ui` + `Content` + - `NfsBaseCatalogPage` (new) uses `Header` from `@backstage/ui` + `Content` ### Scaffolder Plugin (Sub-Pages) @@ -395,7 +398,7 @@ The same applies to other refs like API refs and route refs: keep them exported - `plugins/api-docs/src/components/ApiExplorerPage/DefaultApiExplorerPage.tsx` - `DefaultApiExplorerPage` (old) uses `PageWithHeader` + `ContentHeader` -- `NfsApiExplorerPage` (new) uses `HeaderPage` + `Content` +- `NfsApiExplorerPage` (new) uses `Header` + `Content` ## Migration Checklist @@ -405,11 +408,11 @@ The same applies to other refs like API refs and route refs: keep them exported 4. [ ] Create `SubPageBlueprint` for tabbed sub-pages (if applicable) 5. [ ] Convert API factories to `ApiBlueprint` extensions 6. [ ] Implement NFS page variants without page shell (`Page`/`Header`/`PageWithHeader`) -7. [ ] Use `HeaderPage` from `@backstage/ui` for subtitle/custom actions in NFS pages +7. [ ] Use `Header` from `@backstage/ui` for subtitle/custom actions in NFS pages 8. [ ] Wire route refs (existing `@backstage/core-plugin-api` refs work directly, no conversion needed) 9. [ ] Ensure translation refs and API refs are exported from the main entry point (not duplicated in `./alpha`) 10. [ ] Add `@backstage/frontend-plugin-api` to `package.json` dependencies -11. [ ] Add `@backstage/ui` to dependencies (if using `HeaderPage`) +11. [ ] Add `@backstage/ui` to dependencies (if using `Header`) 12. [ ] Run `yarn tsc` to check for type errors 13. [ ] Run `yarn lint` to check for missing dependencies 14. [ ] Test in both old app (`packages/app-legacy`) and new app (`packages/app`)