diff --git a/docs/releases/v1.48.0.md b/docs/releases/v1.48.0.md new file mode 100644 index 0000000000..53b45c2f5f --- /dev/null +++ b/docs/releases/v1.48.0.md @@ -0,0 +1,130 @@ +--- +id: v1.48.0 +title: v1.48.0 +description: Backstage Release v1.48.0 +--- + +These are the release notes for the v1.48.0 release of [Backstage](https://backstage.io/). + +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](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) published in November, it outlined a new authorization method that’s going to take over from Dynamic Client Registration called [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#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](https://github.com/backstage/backstage/blob/master/plugins/auth-backend/CHANGELOG.md) 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](https://backstage.io/docs/frontend-system/building-plugins/testing). 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](https://github.com/kunickiaj) in [#31225](https://github.com/backstage/backstage/pull/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](https://backstage.io/docs/next/frontend-system/architecture/extensions#sharing-extensions-across-multiple-locations) 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](https://github.com/grantila) in [#32685](https://github.com/backstage/backstage/pull/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](https://github.com/backstage/backstage/issues/32833) 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](https://backstage.io/docs/frontend-system/building-apps/module-federation) 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](https://github.com/davidfestal) in [#30967](https://github.com/backstage/backstage/pull/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](https://github.com/arjan07) in [#31855](https://github.com/backstage/backstage/pull/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](https://backstage.io/docs/getting-started/keeping-backstage-updated). + +## Links and References + +Below you can find a list of links and references to help you learn about and start using this new release. + +- [Backstage official website](https://backstage.io/), [documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/) +- [GitHub repository](https://github.com/backstage/backstage) +- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy) +- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support +- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.48.0-changelog.md) +- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins) + +Sign up for our [newsletter](https://spoti.fi/backstagenewsletter) if you want to be informed about what is happening in the world of Backstage.