Adding New Frontend System Support to an Existing Plugin

This skill helps add new frontend system (NFS) support to an existing Backstage plugin while keeping the old system fully functional. The result is a plugin that works in both old and new apps via a dual entry point pattern.

This is the preferred approach for published plugins or plugins that are used by external parties, since it avoids forcing consumers to migrate their app before they are ready.

It is highly recommended to be on Backstage version 1.49.x or above before starting this, although not mandatory, you may face issues with some of the instructions below. This can be verified by looking in the backstage.json file in the root of the repository.

Key Concepts

• Dual entry point: The plugin keeps its existing src/plugin.ts (old system) and adds a new src/alpha.tsx (new system)
• Old system: createPlugin from @backstage/core-plugin-api, pages via createRoutableExtension, routes defined in the app
• New system: createFrontendPlugin from @backstage/frontend-plugin-api, pages via PageBlueprint, routes owned by the plugin
• Dual header pattern: Old system uses Page/Header/PageWithHeader from @backstage/core-components; new system relies on the framework's PageLayout which renders PluginHeader from @backstage/ui — so NFS page components should NOT include their own page shell

Step 1: Create the Alpha Entry Point

Create src/alpha.tsx (or src/alpha/index.ts for larger plugins) with a createFrontendPlugin default export: