Skip to main content
Version: Next

v1.48.0

These are the release notes for the v1.48.0 release of Backstage.

A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for the hard work in getting this release developed and done.

Highlights​

BREAKING ALPHA: Catalog extension points graduated​

If you are providing custom processors and entity providers into the catalog, you will now note that several (but not quite all!) of those extension points have graduated out of alpha and into the regular stable exports.

Thus, if you are importing for example catalogProcessingExtensionPoint from @backstage/plugin-catalog-node/alpha, you now want to remove that /alpha suffix.

BREAKING: API restrictions in New Frontend System​

In the 1.47 release a new behavior was introduced to the New Frontend System that limits the ability for plugins and modules to provide APIs to plugins other than themselves. For example, the scaffolder plugin could no longer install a custom CatalogApi implementation. This also applies to modules, where you now need to use a module explicitly targeting the 'app' plugin to for example override the ErrorApi.

In 1.47 this new behavior simply triggered a warning, but in this release the API overrides are instead rejected with an error.

Experimental Client ID Metadata Documents​

With the latest MCP specification published in November, it outlined a new authorization method that’s going to take over from Dynamic Client Registration called Client ID Metadata Documents.

This can be enabled in the auth-backend plugin by using the auth.experimentalClientIdMetadataDocuments.enabled flag in config.

Be sure to head over to the changelog for additional configuration and security considerations.

Experimental Refresh Token Support​

Clients can now request the offline_access scope to receive refresh tokens when auth.experimentalRefreshToken.enabled is set, allowing new access tokens without re-authentication. This can be highly useful when using experimentalDynamicClientRegistration so that the tokens don’t expire every 1h by default, which then triggers another auth session approval request.

This also means that auth.experimentalDynamicClientRegistration.tokenExpiration has been removed in favor of using this method as a BREAKING EXPERIMENTAL change.

New Frontend System: Testing utilities​

The testing utilities for the new frontend system have gotten an overhaul in this release, with all new features documented in the plugin testing section. Some highlights include that mountedRoutes and apis options are available for all harnesses where applicable. The selection of mockApis has been increased to support more of the core APIs and have both Jest and minimal implementation mocks. The mockApis now also produces values that can be passed directly to the various testing apis options, without the need to wrap [ref, impl] tuples.

Utilities for creating frontend and backend mocks​

Both @backstage/frontend-test-utils and @backstage/backend-test-utils now export utilities for creating service and API mocks, createServiceMock and createApiMock. These utilities create the same kind of mock utilities as the ones provided by mockServices and mockApis, and are encouraged to be exported via the /testUtils sub-path export from packages, similar to how this pattern is used in @backstage/plugin-catalog-react.

New Frontend System: Plugin titles & icons​

Plugins now have optional titles and icons in the new frontend system. This helps implement app-wide features and navigation patterns that enumerate plugins or in other ways traverse the extension tree in the app.

As part of this change we are also updating the icon type in the new frontend system. The existing IconComponent type is being deprecated, and is being replaced by the element-based IconElement.

New Frontend System: Page and nav structure​

This release starts incorporating the new navigation system from @backstage/ui into the New Frontend System. This comes in the form of an updated PageBlueprint that now supports sub-page navigation using a new SubPageBlueprint. This also introduces the new plugin-wide PluginHeader, although in this release it is limited to only being shown on plugin pages that use the new sub-page navigation.

This change also updates the API provided by NavContentBlueprint. The items prop is now deprecated in favor of a new navItems prop, which is based on enumerating pages in the app rather than explicit nav items. The navItems prop also provides an API that makes it simpler to construct a nav bar that has explicit positioning of a few items, while leaving the rest to be rendered in a group.

New Frontend System: Home plugin support​

Added support for the New Frontend system to the Home plugin.

Contributed by @kunickiaj in #31225.

New Frontend System: Entity summary card type removed​

The summary type has been removed from EntityCardBlueprint. This card type saw little use and feedback mostly pointed to it being confusing. Existing usage is encouraged to move to a content type card with a list of smaller cards instead.

New Frontend System: Removed multiple attachment points​

The ability for extensions to have multiple attachment points was introduced a couple of releases back in order to support use-cases where extensibility was needed across multiple extensions in a plugin. For example TechDocs addons needed to be available both at the top-level reader page as well as the reader installed as entity content.

After observing this pattern in the wild, we concluded that it introduced more complexity than what it was worth, and support for multiple extension points has been removed.

The alternative pattern, which is now used throughout the core feature plugins, is to use a Utility API to collect and share extensions. This pattern is now documented in the architecture section for the new frontend system.

New @backstage/filter-predicates Package​

Extracted predicate types from @backstage/plugin-catalog-react/alpha into a standalone package for general reuse.

New Backstage UI Components + Fixes​

New Alert component with support for status variants, icons, loading states, and custom actions.

New FullPage component that fills the remaining viewport height below the PluginHeader.

Added a destructive prop to the Button component for dangerous actions like delete or remove, working with all button variants.

The useTable hook now accepts a direct data prop for mode "complete" instead of requiring getData(), reducing flickering when data changes.

Contributed by @grantila in #32685.

Experimental Catalog generic SCM event handling​

There’s a new experimental catalogScmEventsServiceRef in town. It’s a communication hub where event providers for example based on webhooks can feed distilled source code provider events into the catalog, where it can react in a generic way to them. This can enable instant refreshes of entities after you press Merge, automatic unregistration of locations when you decommission a repository, and much more.

See this issue for more information on how you can contribute to fleshing out this capability!

Module Federation enabled by default​

Apps built with @backstage/cli now have module federation enabled by default without additional overhead. This is achieved by relying on the runtime APIs rather than introducing it at build-time. See the new module federation section for more details and instructions for how to use this in your own app. Note that as part of this change the EXPERIMENTAL_MODULE_FEDERATION flag has been removed.

Contributed by @davidfestal in #30967.

Azure Database Microsoft Entra Authentication​

Added connection.type: azure in the database client config for Microsoft Entra authentication with Azure Database for PostgreSQL.

Contributed by @arjan07 in #31855.

Security Fixes​

This release does not contain any security fixes.

Upgrade path​

We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for keeping Backstage updated.

Below you can find a list of links and references to help you learn about and start using this new release.

Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.