rhdh-plugin-nfs-migration
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.
How do I install this agent skill?
npx skills add https://github.com/redhat-developer/rhdh-skills --skill rhdh-plugin-nfs-migrationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive instructions and reference material for migrating Backstage frontend plugins to the New Frontend System. It outlines workflows for code conversion, configuration updates, and verification. No malicious patterns, such as data exfiltration or credential harvesting, were found. A low-severity finding is noted for indirect prompt injection, as the skill is designed to process external project source code and configuration files, which is necessary for its functionality.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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.tsorsrc/plugin.tsx, route refs, API factories, exported components, andapp-config.dynamic.yaml. - Read the workspace's own
AGENTS.mdorCLAUDE.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-upgradeowns 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-changesowns the NFS API deltas between the early alpha and the current GA surface — removedNavItemBlueprint, theconfigSchemareplacement forconfig.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-exportowns exporting and packaging the migrated plugin./rhdh-plugin-wiringowns generatingdynamic-plugins.yamlconfiguration./rhdh-localowns running a local RHDH instance and applying plugin configuration to it./rhdh-pr-createowns 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-apiso the same components serve both export paths. Reach forcompatWrapper()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 asAppDrawerContentBlueprintandGlobalHeaderMenuItemBlueprintcome from@red-hat-developer-hub/*. Do not mix the two namespaces. - Put entity content and cards directly in the plugin's
extensionsarray. UsecreateFrontendModuleonly to target a different plugin — translations atpluginId: 'app', homepage widgets atpluginId: 'home'. - Legacy exports stay available. A breaking change to a legacy consumer needs explicit user approval.
- Run
yarn tscfrom 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/redhat-developer/rhdh-skills/rhdh-plugin-nfs-migration">View rhdh-plugin-nfs-migration on skillZs</a>