RHDH Plugin NFS Migration
Own the shape of a frontend plugin's extensions as it moves from the legacy
frontend system to NFS. Discover what the plugin exports before changing
anything, migrate one extension type at a time, and keep legacy consumers
compiling until the user explicitly approves a breaking change.
Start here
- Read the plugin's
package.json, src/plugin.ts or src/plugin.tsx, route
refs, API factories, exported components, and app-config.dynamic.yaml.
- Read the workspace's own
AGENTS.md or CLAUDE.md; repository rules beat
anything written here.
- List every discovered extension to the user before editing.
- Inspect branch and status before modifying files, and protect uncommitted
work.
Route by outcome
| Outcome |
Load and follow |
| Migrate a plugin to NFS |
workflows/migrate-nfs.md |
| Test a migrated plugin in RHDH |
workflows/test-nfs-plugin.md |
| Explain NFS before migrating |
references/overview.md |
| Migrate pages or API factories |
references/migrate-page.md |
| Migrate entity tabs or cards |
references/migrate-entity-content.md |
| Migrate translations |
references/migrate-translations.md |
| Migrate RHDH drawers, header items, homepage widgets |
references/migrate-rhdh-extensions.md |
| Migrate app-level wrappers or root elements |
references/migrate-app-level.md |
| Translate a legacy dynamic mount point into an extension |
references/mount-point-mapping.md |
| Update package exports |
references/package-json.md |
| Set up or update the NFS dev app |
references/app-setup.md |
| Verify the migration |
references/verification.md |
Reach RHDH operator app.extensions or app.routes.bindings |
references/operator-config.md |
| Troubleshoot a failed migration |
references/gotchas.md, then references/support.md |
| Find a real migrated plugin to copy |
references/reference-prs.md |
Boundaries
- This skill owns extension shape: which Blueprint replaces which legacy
extension, where it attaches, and what the package exports. It does not
choose
@backstage/* version numbers.
/rhdh-backstage-upgrade owns version numbers: which Backstage release
to move to and how to get the dependency set there. When the plugin's
@backstage/* dependencies are too old for the Blueprints this migration
needs, invoke it by name first, then return here./backstage-api-changes owns the NFS API deltas between the early alpha
and the current GA surface — removed NavItemBlueprint, the configSchema
replacement for config.schema, renamed blueprint params. Invoke it by name
when migrating a plugin that was already migrated against an older NFS API,
or when a Blueprint param produces a TypeScript error./rhdh-plugin-export owns exporting and packaging the migrated plugin./rhdh-plugin-wiring owns generating dynamic-plugins.yaml configuration./rhdh-local owns running a local RHDH instance and applying plugin
configuration to it./rhdh-pr-create owns staging, commits, and pull requests. Leave changed
files unstaged and list them when you finish.
Invoke a named skill and describe the handoff in the conversation. Never open
another skill's files.
Invariants
- NFS is not GA. Default to the alpha approach: NFS at
./alpha, legacy
untouched at the root export. Use the colocated approach only when the user
wants both APIs from one import path.
- Keep component-level imports (
useApi, useRouteRef) on
@backstage/core-plugin-api so the same components serve both export paths.
Reach for compatWrapper() only when a component needs a legacy context
provider that NFS does not supply.
- Core blueprints come from
@backstage/frontend-plugin-api. RHDH-only
blueprints such as AppDrawerContentBlueprint and
GlobalHeaderMenuItemBlueprint come from @red-hat-developer-hub/*. Do not
mix the two namespaces.
- Put entity content and cards directly in the plugin's
extensions array.
Use createFrontendModule only to target a different plugin — translations
at pluginId: 'app', homepage widgets at pluginId: 'home'.
- Legacy exports stay available. A breaking change to a legacy consumer needs
explicit user approval.
- Run
yarn tsc from the workspace root, not the plugin directory, so consumer
import breakage surfaces.
- Do not stage, commit, push, or open a pull request here.
Completion
Report the extensions discovered and their NFS equivalents, the export approach
chosen, the files changed and left unstaged, the verification commands run and
their results, any legacy consumer risk, and the named skill to invoke next for
export, wiring, local testing, or publication.
1---2name: rhdh-plugin-nfs-migration3description: Converts a legacy Backstage frontend plugin used by Red Hat Developer Hub to the New Frontend System (NFS): replace createPlugin and createRoutableExtension with createFrontendPlugin, PageBlueprint, EntityContentBlueprint, AppDrawerContentBlueprint and createFrontendModule; map RHDH app-config.dynamic.yaml mount points onto extensions; add the ./alpha export to package.json without breaking legacy consumers; and verify the migrated dynamic plugin in a real RHDH instance. Use for "migrate my plugin to NFS", Blueprint migration, createFrontendPlugin, compatWrapper, alpha versus colocated exports, translations moved into a createFrontendModule with pluginId app, RHDH operator app.extensions and app.routes.bindings, and ENABLE_STANDARD_MODULE_FEDERATION testing.4---56# RHDH Plugin NFS Migration78Own the shape of a frontend plugin's extensions as it moves from the legacy9frontend system to NFS. Discover what the plugin exports before changing10anything, migrate one extension type at a time, and keep legacy consumers11compiling until the user explicitly approves a breaking change.1213## Start here14151. Read the plugin's `package.json`, `src/plugin.ts` or `src/plugin.tsx`, route16 refs, API factories, exported components, and `app-config.dynamic.yaml`.172. Read the workspace's own `AGENTS.md` or `CLAUDE.md`; repository rules beat18 anything written here.193. List every discovered extension to the user before editing.204. Inspect branch and status before modifying files, and protect uncommitted21 work.2223## Route by outcome2425| Outcome | Load and follow |26|---|---|27| Migrate a plugin to NFS | `workflows/migrate-nfs.md` |28| Test a migrated plugin in RHDH | `workflows/test-nfs-plugin.md` |29| Explain NFS before migrating | `references/overview.md` |30| Migrate pages or API factories | `references/migrate-page.md` |31| Migrate entity tabs or cards | `references/migrate-entity-content.md` |32| Migrate translations | `references/migrate-translations.md` |33| Migrate RHDH drawers, header items, homepage widgets | `references/migrate-rhdh-extensions.md` |34| Migrate app-level wrappers or root elements | `references/migrate-app-level.md` |35| Translate a legacy dynamic mount point into an extension | `references/mount-point-mapping.md` |36| Update package exports | `references/package-json.md` |37| Set up or update the NFS dev app | `references/app-setup.md` |38| Verify the migration | `references/verification.md` |39| Reach RHDH operator `app.extensions` or `app.routes.bindings` | `references/operator-config.md` |40| Troubleshoot a failed migration | `references/gotchas.md`, then `references/support.md` |41| Find a real migrated plugin to copy | `references/reference-prs.md` |4243## Boundaries4445- This skill owns **extension shape**: which Blueprint replaces which legacy46 extension, where it attaches, and what the package exports. It does not47 choose `@backstage/*` version numbers.48- `/rhdh-backstage-upgrade` owns **version numbers**: which Backstage release49 to move to and how to get the dependency set there. When the plugin's50 `@backstage/*` dependencies are too old for the Blueprints this migration51 needs, invoke it by name first, then return here.52- `/backstage-api-changes` owns the NFS API deltas between the early alpha53 and the current GA surface — removed `NavItemBlueprint`, the `configSchema`54 replacement for `config.schema`, renamed blueprint params. Invoke it by name55 when migrating a plugin that was already migrated against an older NFS API,56 or when a Blueprint param produces a TypeScript error.57- `/rhdh-plugin-export` owns exporting and packaging the migrated plugin.58- `/rhdh-plugin-wiring` owns generating `dynamic-plugins.yaml` configuration.59- `/rhdh-local` owns running a local RHDH instance and applying plugin60 configuration to it.61- `/rhdh-pr-create` owns staging, commits, and pull requests. Leave changed62 files unstaged and list them when you finish.6364Invoke a named skill and describe the handoff in the conversation. Never open65another skill's files.6667## Invariants6869- NFS is not GA. Default to the alpha approach: NFS at `./alpha`, legacy70 untouched at the root export. Use the colocated approach only when the user71 wants both APIs from one import path.72- Keep component-level imports (`useApi`, `useRouteRef`) on73 `@backstage/core-plugin-api` so the same components serve both export paths.74 Reach for `compatWrapper()` only when a component needs a legacy context75 provider that NFS does not supply.76- Core blueprints come from `@backstage/frontend-plugin-api`. RHDH-only77 blueprints such as `AppDrawerContentBlueprint` and78 `GlobalHeaderMenuItemBlueprint` come from `@red-hat-developer-hub/*`. Do not79 mix the two namespaces.80- Put entity content and cards directly in the plugin's `extensions` array.81 Use `createFrontendModule` only to target a different plugin — translations82 at `pluginId: 'app'`, homepage widgets at `pluginId: 'home'`.83- Legacy exports stay available. A breaking change to a legacy consumer needs84 explicit user approval.85- Run `yarn tsc` from the workspace root, not the plugin directory, so consumer86 import breakage surfaces.87- Do not stage, commit, push, or open a pull request here.8889## Completion9091Report the extensions discovered and their NFS equivalents, the export approach92chosen, the files changed and left unstaged, the verification commands run and93their results, any legacy consumer risk, and the named skill to invoke next for94export, wiring, local testing, or publication.
redhat-developer