Customizing Backstage
The Customizing Backstage domain tests how you tailor the portal without forking core: themes and layout, app APIs, entity pages, catalog processors, and scaffolder actions. The exam favors knowing which extension point to use and where it is registered.
UI and theming
Backstage uses Material UI v4 (@material-ui/core), not v5. Themes come from @backstage/theme: use createTheme, lightTheme, or darkTheme, and supply palette plus page-theme values. The app composes routes, sidebar, sign-in page, and header in packages/app. Entity pages are customized in EntityPage.tsx with EntityLayout, EntityLayout.Route, EntitySwitch, and guards such as isKind. Add a tab by adding an EntityLayout.Route with a path and title; the entity page supplies the context.
APIs and extension points
Define an API reference with createApiRef({ id: 'plugin.my-plugin' }), implement it, and register a factory in packages/app/src/apis.ts using createApiFactory. Components consume it with useApi. A frontend plugin should expose a routable extension via createRoutableExtension, not just a raw component. For backend customization, a catalog processor implements CatalogProcessor (getProcessorName, validateEntityKind, preProcessEntity, postProcessEntity) and is registered with the catalog backend. A scaffolder action uses createTemplateAction with an id, a schema, and a handler; register it with the scaffolder backend.
Worked example
You need a “Security” tab on every Component entity page. In EntityPage.tsx, add <EntityLayout.Route path="/security" title="Security"><EntitySecurityCard /></EntityLayout.Route> inside the component entity layout. The route path is relative to the entity page, and EntityLayout renders it as a tab. If the card needs an API, create an API ref, register the factory in apis.ts, and call useApi inside the card. Reasoning: EntityLayout.Route is the supported extension point; bypassing it with a separate top-level route loses the entity context.
Traps
Do not use Material UI v5 imports or @backstage/core; use @backstage/core-components, @backstage/core-plugin-api, and @material-ui/core. Do not forget to register an API factory; useApi will throw without a provider. Do not make a catalog processor perform slow network calls without handling retries and idempotency. Do not edit generated api-report.md. Do not assume a custom scaffolder action can return arbitrary output; match its schema.