OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add https://backstage.io --skill plugin-full-frontend-system-migration
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.
npx skills add https://backstage.io --skill plugin-full-frontend-system-migration
This skill helps fully migrate an existing Backstage plugin from the old frontend system to the new one. Unlike adding dual support (which keeps the old system working), this is a complete migration that removes all @backstage/core-plugin-api usage and makes the plugin work exclusively with the new frontend system.
This is the preferred approach for internal plugins that are only used in a single app, since there is no need to maintain backward compatibility. It can also be used for published plugins when you're ready to drop old system support entirely.
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.
| Aspect | Dual Support | Full Migration |
|---|---|---|
| Entry point | Old src/plugin.ts + new src/alpha.tsx | Single src/plugin.tsx |
| Plugin creation | Both createPlugin and createFrontendPlugin | Only createFrontendPlugin |
| Core dependency | Keeps @backstage/core-plugin-api | Removes it, uses only @backstage/frontend-plugin-api |
| Route refs | Reuses @backstage/core-plugin-api refs directly | Uses createRouteRef from @backstage/frontend-plugin-api |
| Page shell | Old pages keep Page/Header, NFS pages skip it | All pages rely on framework's PageLayout/PluginHeader |
| Internal routing | May keep legacy <Route> trees in components | Replaced with SubPageBlueprint tabbed pages |
| Compatibility | Not needed | Not needed |
Replace createRouteRef / createSubRouteRef / createExternalRouteRef imports:
Key differences:
createRouteRef() no longer takes an id — the ID is derived from the extensioncreateSubRouteRef path must start with / and must not end with /createExternalRouteRef() no longer takes an id or optional flagWhen migrating external route refs, always set defaultTarget to the most common binding target. This removes the need for apps to explicitly bind routes via bindRoutes for standard plugin combinations:
The defaultTarget string uses the <pluginId>.<routeName> format, where routeName matches a key in the target plugin's routes map. The default is only activated when the target plugin is installed — otherwise the route stays unbound and useRouteRef returns undefined.
This is especially important for a full migration because in the old system, apps typically had explicit bindRoutes calls. With default targets, most of those bindings become unnecessary, improving the plug-and-play experience.
Replace src/plugin.ts with a createFrontendPlugin-based definition:
For the plugin icon, prefer using Remix Icons from @remixicon/react. If the plugin already has an existing MUI icon, it can be kept with fontSize="inherit" (e.g. <CategoryIcon fontSize="inherit" />), but for new icons Remix is the recommended choice.
Since this is the only entry point now, export it as default from src/index.ts or update package.json exports accordingly. If the plugin was previously consumed via its main entry point, you can make the main entry point export the new plugin:
ApiBlueprintAlso update the API ref creation to the new builder pattern with explicit pluginId:
The builder form (createApiRef<T>().with(...)) is preferred because ownership is explicit via pluginId rather than parsed from the ID string. The id must still be globally unique across the app — the pluginId is ownership metadata, not a namespace prefix.
The new system enforces API ownership — only the owning plugin (or a module targeting it) can provide or override a given API. Ownership is determined by:
pluginId on the ApiRef (if set via the builder pattern)ApiRef ID string:
plugin.<pluginId>.* → owned by that plugincore.* → owned by the app pluginIf app adopters want to replace your plugin's default API implementation, they must use a createFrontendModule with pluginId matching your plugin — they cannot override it from a different plugin or from a generic app module. This is a stricter model than the old system where any API could be overridden from the app's apis array.
PageBlueprintThe MyPage component should not include Page, Header, or PageWithHeader from @backstage/core-components. The framework's PageLayout renders PluginHeader automatically.
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.
Header for Custom ActionsIf your page needs a subtitle or action buttons below the framework header, use Header from @backstage/ui:
For pages that manage their own layout entirely (e.g. home page, dashboards), set noHeader: true:
Old frontend plugins often use React Router <Route> trees inside a router component to handle internal navigation. Before migrating, determine which routing pattern fits the plugin.
Not all internal routing maps to tabs. Read the plugin's existing router component and ask the user:
"Does your plugin use top-level tabs that users navigate between via a header (e.g. Overview / Settings)? Or does it use detail/drill-down routes (e.g.
/my-plugin/items/:id)?"
Use SubPageBlueprint when:
Keep internal routing within a PageBlueprint loader when:
/my-plugin/items/:id)If the plugin uses drill-down routing only, use a PageBlueprint with a loader that handles its own <Routes> and skip the rest of this step:
If the plugin uses top-level tabs, continue with the SubPageBlueprint migration below.
PageBlueprint + SubPageBlueprintHow this works:
PageBlueprint without a loader automatically renders its sub-pages as tabsSubPageBlueprint gets a tab in the header with its titlepath values are relative (no leading /)Page, Header, or HeaderTabsIf the sub-page content needs padding, use Container from @backstage/ui as a wrapper inside the component.
Replace all @backstage/core-plugin-api imports with @backstage/frontend-plugin-api:
useRouteRef Behavior ChangeIn the new system, useRouteRef may return undefined for external route refs that aren't bound. Handle this:
Old Import (@backstage/core-plugin-api) | New Import (@backstage/frontend-plugin-api) |
|---|---|
createPlugin | createFrontendPlugin |
createRouteRef | createRouteRef |
createSubRouteRef | createSubRouteRef |
createExternalRouteRef | createExternalRouteRef |
createApiRef | createApiRef |
createApiFactory | ApiBlueprint.make |
useApi | useApi |
useRouteRef | useRouteRef |
configApiRef | configApiRef |
discoveryApiRef | discoveryApiRef |
fetchApiRef | fetchApiRef |
identityApiRef | identityApiRef |
storageApiRef | storageApiRef |
analyticsApiRef | analyticsApiRef |
createRoutableExtension | PageBlueprint.make |
createComponentExtension | Depends on context — blueprint or createExtension |
src/plugin.ts (old createPlugin)createRoutableExtension / createComponentExtension usagePage, Header, PageWithHeader wrapping from page componentsHeaderTabs if replaced by SubPageBlueprint tabs<Routes>/<Route> trees if replaced by sub-pages@backstage/core-plugin-api from package.json dependencies@backstage/core-compat-api from package.json dependencies if presentWith the full migration, page components should use @backstage/ui components and patterns. See the mui-to-bui-migration skill for detailed component migration guidance.
Key page-level changes:
PageWithHeader / Page + Header with framework-provided PluginHeader (automatic via PageLayout)Header from @backstage/ui for optional subtitle/custom actionsContent from @backstage/core-components for page body padding (this is still used even in NFS pages)ContentHeader with Header's customActions propHeaderTabs with SubPageBlueprint (tabs are rendered by the framework)The @backstage/plugin-auth plugin is a fully migrated example with no @backstage/core-plugin-api dependency:
The scaffolder plugin demonstrates the sub-page pattern (though it still has dual support — the pattern itself is what a full migration targets):
@backstage/frontend-plugin-api (createRouteRef, createSubRouteRef, createExternalRouteRef)createPlugin with createFrontendPluginApiBlueprint extensionsPageBlueprintSubPageBlueprint where appropriatePage/Header/PageWithHeader from page componentsHeader from @backstage/ui where subtitle/custom actions are neededHeaderTabs with SubPageBlueprint tabs@backstage/core-plugin-api imports to @backstage/frontend-plugin-apiuseRouteRef possibly returning undefinedsrc/plugin.ts (old system entry point)src/alpha.tsx if it existed (merge into main entry)@backstage/core-plugin-api from package.json dependencies@backstage/core-compat-api from package.json dependenciespackage.json exports (remove ./alpha if merged into main)yarn tsc to check for type errorsyarn lint to check for missing dependenciesyarn build:api-reports to update API reports (if the project uses API reports)packages/app)mui-to-bui-migration skillexport const createComponentRouteRef = createExternalRouteRef({
defaultTarget: 'scaffolder.root',
});
export const viewTechDocRouteRef = createExternalRouteRef({
params: ['namespace', 'kind', 'name'],
defaultTarget: 'techdocs.docRoot',
});
export const catalogEntityRouteRef = createExternalRouteRef({
params: ['namespace', 'kind', 'name'],
defaultTarget: 'catalog.catalogEntity',
});// NEW (src/plugin.tsx)
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
import { RiToolsLine } from '@remixicon/react';
import { rootRouteRef, externalDocsRouteRef } from './routes';
import { myPage } from './extensions';
import { myPluginApi } from './apis';
export default createFrontendPlugin({
pluginId: 'my-plugin',
title: 'My Plugin',
icon: <RiToolsLine />,
info: {
packageJson: () => import('../package.json'),
},
routes: {
root: rootRouteRef,
},
externalRoutes: {
docs: externalDocsRouteRef,
},
extensions: [myPluginApi, myPage],
});{
"exports": {
".": "./src/index.ts",
"./package.json": "./package.json"
}
}// src/index.ts
export { default } from './plugin';
export { rootRouteRef } from './routes';// OLD
import {
createApiFactory,
discoveryApiRef,
fetchApiRef,
} from '@backstage/core-plugin-api';
export const myApiFactory = createApiFactory({
api: myPluginApiRef,
deps: { discoveryApi: discoveryApiRef, fetchApi: fetchApiRef },
factory: ({ discoveryApi, fetchApi }) =>
new MyPluginClient({ discoveryApi, fetchApi }),
});
// NEW (src/apis.ts)
import {
ApiBlueprint,
discoveryApiRef,
fetchApiRef,
} from '@backstage/frontend-plugin-api';
import { myPluginApiRef } from './api';
export const myPluginApi = ApiBlueprint.make({
params: defineParams =>
defineParams({
api: myPluginApiRef,
deps: { discoveryApi: discoveryApiRef, fetchApi: fetchApiRef },
factory: ({ discoveryApi, fetchApi }) =>
new MyPluginClient({ discoveryApi, fetchApi }),
}),
});// OLD
import { createApiRef } from '@backstage/core-plugin-api';
export const myPluginApiRef = createApiRef<MyPluginApi>({
id: 'plugin.my-plugin.client',
});
// NEW (recommended builder pattern with explicit pluginId)
import { createApiRef } from '@backstage/frontend-plugin-api';
export const myPluginApiRef = createApiRef<MyPluginApi>().with({
id: 'plugin.my-plugin.client',
pluginId: 'my-plugin',
});// src/extensions.tsx
import { PageBlueprint } from '@backstage/frontend-plugin-api';
import { rootRouteRef } from './routes';
export const myPage = PageBlueprint.make({
params: {
path: '/my-plugin',
routeRef: rootRouteRef,
loader: () => import('./components/MyPage').then(m => <m.MyPage />),
},
});// src/components/MyPage/MyPage.tsx
import { Header } from '@backstage/ui';
import { Content } from '@backstage/core-components';
export function MyPage() {
return (
<>
<Header
title="Subtitle or description"
customActions={
<>
<CreateButton title="Create" to="/my-plugin/create" />
<SupportButton>Help text</SupportButton>
</>
}
/>
<Content>
<MyPageContent />
</Content>
</>
);
}export const myPage = PageBlueprint.make({
params: {
path: '/my-plugin',
routeRef: rootRouteRef,
noHeader: true,
loader: () => import('./components/MyPage').then(m => <m.MyPage />),
},
});export const myPage = PageBlueprint.make({
params: {
path: '/my-plugin',
routeRef: rootRouteRef,
loader: () => import('./components/Router').then(m => <m.MyPluginRouter />),
},
});// OLD — plugin owns its own routing
import { Route, Routes } from 'react-router-dom';
export function MyPluginRouter() {
return (
<Page themeId="tool">
<Header title="My Plugin" />
<HeaderTabs
tabs={[
{ id: 'overview', label: 'Overview' },
{ id: 'settings', label: 'Settings' },
]}
/>
<Content>
<Routes>
<Route path="/" element={<OverviewPage />} />
<Route path="/settings" element={<SettingsPage />} />
</Routes>
</Content>
</Page>
);
}// src/extensions.tsx
import {
PageBlueprint,
SubPageBlueprint,
} from '@backstage/frontend-plugin-api';
// Parent page WITHOUT a loader — uses built-in tabbed rendering
export const myPluginPage = PageBlueprint.make({
params: {
path: '/my-plugin',
routeRef: rootRouteRef,
},
});
export const overviewSubPage = SubPageBlueprint.make({
name: 'overview',
params: {
path: 'overview',
title: 'Overview',
loader: () =>
import('./components/OverviewPage').then(m => <m.OverviewPageContent />),
},
});
export const settingsSubPage = SubPageBlueprint.make({
name: 'settings',
params: {
path: 'settings',
title: 'Settings',
loader: () =>
import('./components/SettingsPage').then(m => <m.SettingsPageContent />),
},
});// OLD
import { useApi, useRouteRef, configApiRef } from '@backstage/core-plugin-api';
// NEW
import {
useApi,
useRouteRef,
configApiRef,
} from '@backstage/frontend-plugin-api';// OLD — throws if not bound
const docsLink = useRouteRef(externalDocsRouteRef);
// Always a function
// NEW — returns undefined if not bound
const docsLink = useRouteRef(externalDocsRouteRef);
if (docsLink) {
// render link
}// plugins/auth/src/routes.ts
import { createRouteRef } from '@backstage/frontend-plugin-api';
export const rootRouteRef = createRouteRef();
// plugins/auth/src/plugin.tsx
import {
createFrontendPlugin,
PageBlueprint,
} from '@backstage/frontend-plugin-api';
import { rootRouteRef } from './routes';
export const AuthPage = PageBlueprint.make({
params: {
path: '/oauth2',
routeRef: rootRouteRef,
loader: () => import('./components/Router').then(m => <m.Router />),
},
});
export default createFrontendPlugin({
pluginId: 'auth',
extensions: [AuthPage],
routes: {
root: rootRouteRef,
},
});// PageBlueprint WITHOUT loader — framework renders tabs
export const scaffolderPage = PageBlueprint.make({
params: {
path: '/create',
routeRef: rootRouteRef,
},
});
// Sub-pages with content only
export const templatesSubPage = SubPageBlueprint.make({
name: 'templates',
params: {
path: 'templates',
title: 'Templates',
loader: () => import('./TemplatesPage').then(m => <m.TemplatesSubPage />),
},
});
export const tasksSubPage = SubPageBlueprint.make({
name: 'tasks',
params: {
path: 'tasks',
title: 'Tasks',
loader: () => import('./TasksPage').then(m => <m.TasksSubPage />),
},
});