| name | nfs-migration |
| description | Migrate Backstage frontend plugins from the legacy system to the New Frontend System (NFS). Use when asked to "migrate to NFS", "new frontend system", "convert plugin to NFS", "createFrontendPlugin", "PageBlueprint", "ApiBlueprint", "SubPageBlueprint", "alpha to GA", "legacy to NFS", "frontend migration", "extension blueprints", "migrate frontend plugin", "NFS support", "graduate alpha", or mentions migrating a Backstage plugin to the new frontend system for RHDH.
|
<essential_principles>
Always read the plugin's `package.json`, `src/plugin.ts` (or `src/plugin.tsx`), route refs, API factories, and exported components before making any changes. Understand what exists before migrating.
NFS is not GA yet. The default approach is to add NFS at `./alpha` while keeping legacy at the root export (`.`). This avoids breaking existing consumers.
Use `@backstage/frontend-plugin-api` for core blueprints. RHDH-specific blueprints (`AppDrawerContentBlueprint`, `GlobalHeaderMenuItemBlueprint`) come from `@red-hat-developer-hub/*` packages. Don't mix them up.
Entity content and cards can go directly in the plugin's `extensions` array — the blueprint declares its own attach point. Use `createFrontendModule` only for extensions that target a different plugin (translations → `pluginId: 'app'`, homepage widgets → `pluginId: 'home'`) or when injecting content from outside a plugin you don't own.
Keep component imports (`useApi`, `useRouteRef`, etc.) on `@backstage/core-plugin-api` — they work in both legacy and NFS contexts. This lets the same components serve both export paths. Only use `compatWrapper()` when a component depends on legacy context providers (e.g. old `SidebarContext`) that aren't available in NFS. Don't migrate component imports to `@backstage/frontend-plugin-api` if you need to support legacy consumers.
Legacy exports must remain available since NFS is not GA. With the alpha approach, legacy stays at root unchanged. With the colocated approach, legacy source moves to `legacy.ts` but is re-exported from `index.ts` so existing consumers don't break.
</essential_principles>
What would you like to do?
- Migrate a plugin to NFS — Analyze your existing plugin and convert it to the New Frontend System
- Test a migrated plugin in RHDH — Deploy and verify in a local or cluster RHDH instance
- Learn about NFS migration — Read the migration guide
Wait for response before proceeding.
| Response | Action |
|---|
| 1, "migrate", "convert", "NFS" | Follow the migration workflow below |
| 2, "test", "verify", "deploy" | Read workflows/test-nfs-plugin.md |
| 3, "learn", "guide", "overview" | Read references/overview.md and present key sections to the user |
<migration_workflow>
Step 1: Discover
Read package.json and src/plugin.ts (or src/plugin.tsx). Identify:
- Plugin ID
- Routes and route refs
- API factories
- Routable extensions (pages)
- Component extensions (entity cards, tabs)
- Sidebar/nav items
- Translations
- RHDH-specific extensions (drawers, header items, homepage widgets)
- RHDH dynamic plugin mount points (
app-config.dynamic.yaml — see references/mount-point-mapping.md)
List all findings to the user before proceeding.
If the plugin's @backstage/* dependencies are outdated, upgrade them first using the backstage-upgrade skill (../backstage-upgrade/SKILL.md) before proceeding with migration.
Step 2: Choose Approach
NFS is not GA yet. Use the Alpha approach by default: NFS at ./alpha, legacy stays at root (.).
The Colocated approach is the alternative: NFS as default export in index.ts, legacy source in legacy.ts but re-exported from index.ts for backward compatibility. Use this when the user wants NFS and legacy APIs available from the same import path.
Step 3: Migrate Extensions
For each extension type found in Step 1, load the appropriate reference:
| Extension type | Reference to load |
|---|
| Pages, API factories | references/migrate-page.md |
| Entity content tabs or cards | references/migrate-entity-content.md |
| Translations / i18n | references/migrate-translations.md |
| RHDH drawers, header items, homepage widgets | references/migrate-rhdh-extensions.md |
| App-level wrappers or root elements | references/migrate-app-level.md |
Apply each reference's patterns to the discovered extensions. For page plugins, create NFS variants of page components without the page shell (dual header pattern in migrate-page.md).
Step 4: Update package.json
Load references/package-json.md and apply the export configuration matching the chosen approach (alpha or colocated).
Step 5: Update App Wiring
Load references/app-setup.md and:
- Add an NFS dev app at
dev/index.tsx (or dev/nfs.tsx) using createApp from @backstage/frontend-defaults
- Keep the existing legacy dev app working
- Verify consumer imports still resolve (alpha approach: no changes needed; colocated approach: legacy re-exports from
index.ts maintain compatibility)
Step 6: Verify
Load references/verification.md and run all checks. Run yarn tsc from the workspace root (not just the plugin directory) to catch consumer import issues.
</migration_workflow>
<reference_index>
| Reference | Load when... |
|---|
references/migrate-page.md | Plugin has pages or API factories |
references/api-changes.md | Updating a plugin migrated against an older NFS version |
references/migrate-entity-content.md | Plugin has entity tabs or cards |
references/migrate-translations.md | Plugin has i18n/translations |
references/migrate-rhdh-extensions.md | Plugin uses RHDH drawer, header, or homepage widgets |
references/mount-point-mapping.md | Plugin uses RHDH dynamic plugin mount points (legacy config) |
references/migrate-app-level.md | Plugin has app-level wrappers or root elements |
references/package-json.md | Updating package.json exports |
references/app-setup.md | Setting up or updating the NFS dev app |
references/verification.md | Verifying the migration |
references/testing-rhdh.md | Testing with a real RHDH instance |
references/gotchas.md | Troubleshooting migration issues |
references/reference-prs.md | Looking for real migration examples |
references/operator-config.md | Plugin uses RHDH operator config or needs app.extensions / app.routes.bindings reference |
references/overview.md | User wants to learn about NFS before migrating |
references/support.md | User needs help beyond what the skill covers |
</reference_index>
<success_criteria>
./alpha (or root, for colocated) default-exports a createFrontendPlugin result- All legacy extensions have NFS Blueprint equivalents
- Pages that need nav entries have
title and icon set (on PageBlueprint or createFrontendPlugin)
package.json exports NFS at ./alpha (alpha approach) or . (colocated approach)- Translations are in a
createFrontendModule with pluginId: 'app'
- Entity content extensions are in the plugin's
extensions array (or a catalog module if injecting from outside)
yarn tsc and yarn build pass- Legacy exports remain available (unchanged at root for alpha; re-exported from
index.ts for colocated)
</success_criteria>
