docs/releases/v1.52.0.md
These are the release notes for the v1.52.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.
FrontendHostDiscoveryThe default discovery API implementation in @backstage/plugin-app has been changed to FrontendHostDiscovery, which supports the discovery.endpoints configuration for per-plugin endpoint overrides. This means the frontend will now honor discovery.endpoints configuration, including string target values. If you currently use internal-only targets there, update them to the object form and move the internal URL to target.internal, omitting target.external (or setting it to a browser-reachable URL) to avoid routing the frontend to internal URLs.
The catalog.stitchingStrategy.mode: 'immediate' setting, which was deprecated in v1.51.0, has been removed. All stitching now uses the deferred mode, which processes entities asynchronously via a worker queue. If your configuration still includes catalog.stitchingStrategy.mode: 'immediate', it will be ignored with a deprecation warning. The pollingInterval and stitchTimeout settings continue to work as before.
This release brings several notable additions and changes to Backstage UI:
Async collections: Both Combobox and Select now support async collections, incremental loading, client and server search, and rich or custom item rendering. Loading placeholders and stale result indicators are exposed via public CSS classes for theme customization. The Combobox and Select popovers now correctly load additional pages as users scroll, rather than loading every page immediately.
Semantic color tokens: A new set of semantic color token families has been introduced -- Accent, Announcement, Warning, Negative, and Positive -- each providing a consistent set of background, foreground, and border tokens for both light and dark themes. A gray scale and updated foreground tokens are also included. The previous tokens remain in place for backward compatibility but are now deprecated. A new @backstage/no-deprecated-bui-tokens ESLint rule warns when deprecated tokens are referenced in JavaScript or TypeScript files.
New components: A NumberField component has been added for numeric input with support for min, max, step, and keyboard increment/decrement. Contributed by @jabrks in #34264.
Breaking changes:
ComboboxProps is now a union type. Replace interfaces that extend ComboboxProps with type intersections:
- interface MyComboboxProps extends ComboboxProps {
- trackingId: string;
- }
+ type MyComboboxProps = ComboboxProps & {
+ trackingId: string;
+ };
SelectProps is now a union type and the popover list content is no longer a direct child of .bui-SelectPopover. Apply the same intersection migration as ComboboxProps, and update CSS selectors that target list content as a direct child of .bui-SelectPopover.Check the BUI Changelog for more details.
@backstage/connectionsA new @backstage/connections package has been added as an experimental feature. Do not use this package unless you are experimenting with this new system. A Connection is a piece of configuration that stores an external host and the credentials required to authenticate with it. The goal of Connections to eventually replace the integrations concept, and to support a much wider range of systems. More information is available in BEP-0014.
Contributed by @neoreddog in #34546 and #34592
totalItems control and split count queriesThe /entities/by-query endpoint now accepts a totalItems parameter ('include' or 'exclude', default 'include') that controls whether the response's totalItems count is computed. Pass 'exclude' to skip the count entirely when the caller does not need it -- useful for cursor-paginated UIs that only display the count cosmetically. The corresponding CatalogApi.queryEntities method in @backstage/catalog-client has been updated to accept the same option.
Internally, the entity list provider now fetches the entity list and the total count as two separate parallel requests. The list query skips the expensive count computation, so the table populates immediately while the count arrives asynchronously. A new totalItemsLoading field on EntityListContextProps lets consumers distinguish a stale count from a fresh one. The catalog table now keeps stale rows visible during filter changes and page navigation instead of replacing the entire table body with a spinner.
Several additional performance improvements have been made to the catalog backend:
queryEntities list and count into separate queries instead of a multi-reference CTE. When the CTE was referenced twice, PostgreSQL refused to inline it, forcing full materialization before applying LIMIT. The standalone count query also fixes a pre-existing bug where totalItems was inflated for entities with multi-valued sort fields.(key, value) in the search table (PostgreSQL only), fixing severe row count estimation errors on compound filter queries that caused 10-40x slower catalog list views.entity_id in the search table.search_entity_id_idx index which is now redundant and was causing the query planner to choose an inefficient scan pattern for catalog list queries with multiple sort fields.entitiesBatch on PostgreSQL to use = ANY(array) instead of WHERE IN ($1, $2, ...), producing a single stable query plan regardless of batch size.Actions can now declare a Zod secrets schema separate from the input schema in @backstage/backend-plugin-api, enabling surfaces to collect sensitive credentials independently from tool arguments. A new v2 invoke endpoint (/.backstage/actions/v2/actions/:id/invoke) accepts a wrapped body format with secrets validation, while the existing v1 endpoint remains unchanged. The mock actions registry in @backstage/backend-test-utils has been updated to support validating and forwarding secrets.
A new scaffolder-field-extension-module template has been added to backstage-cli new, making it easier to scaffold custom Scaffolder form field extensions.
refresh functionThe useEntityList hook from @backstage/plugin-catalog-react now exposes a refresh function, allowing consumers to programmatically trigger a refresh of the entity list data.
Contributed by @mtlewis in #34555
A new CatalogExportButton component has been added to @backstage/plugin-catalog, providing CSV and JSON export support for the CatalogIndexPage.
Contributed by @the-serious-programmer in #31837
The react-syntax-highlighter and @dagrejs/dagre dependencies are now lazy-loaded in @backstage/core-components, so they are no longer pulled in eagerly through the barrel export. This reduces the upfront module cost of importing from @backstage/core-components by roughly 10 MB.
userGroupMember path by reverting the server-side accountEnabled eq true base filter that broke the group members endpoint. Disabled users are now filtered client-side in both paths.user.select to an empty array in the Microsoft Graph provider would cause all users to be dropped from the catalog. Contributed by @mtlewis in #34505.$ref paths in OpenAPI and AsyncAPI specs for cross-directory refs and nested refs at depth > 1. Contributed by @aramissennyeydd in #33954.package.json is present but does not provide a plugin entrypoint. Contributed by @gashcrumb in #34535.backend.rateLimit is enabled. IPv6 clients are now grouped by address block rather than individual address. Contributed by @officialasishkumar in #34353.SidebarSubmenuItem by correcting line-height. Contributed by @GitanshKapoor in #34438.Table component not filling its container width in Firefox. Contributed by @robingileborg in #34539.Git.push() for scaffolder actions that encounter transient failures when the repository is not yet fully provisioned. Contributed by @pc-bob in #34295.publish:github and github:repo:push that retries via the GitHub GraphQL API when the git push fails with a connection-level error, working around network proxies that block binary pack data. Contributed by @polasudo in #34036.getOptionLabel and renderOption props to EntityAutocompletePicker. Contributed by @rferreira98 in #33823.forwardedPreferredUsernameMatchingUserEntityName sign-in resolver to the OAuth2 proxy provider. Contributed by @JessicaJHee in #34156.RepoOwnerPicker custom variant for GitLab in the scaffolder. Contributed by @asheen1234 in #33690.disablePublicEntryPoint config option to the app backend to opt out of the automatic public sign-in entry point.@backstage/plugin-techdocs-module-addons-contrib /alpha entrypoint for dynamic plugin loaders. Contributed by @jroebu14 in #34514./kubernetes by mistake. Contributed by @vinzscam in #34522.HAS_LABEL and HAS_ANNOTATION permission rules are now case insensitive. Contributed by @04kash in #34572.ingestions.last_error column type in the incremental ingestion module to remove the 255-character restriction. Contributed by @koalaty-code in #34347.toastApi not being provided for the old frontend system. Contributed by @apc-kamezaki in #34112.basename. Contributed by @Naycon in #34469.npmMinimalAgeGate: 3d setting as a defense against supply-chain attacks. Contributed by @aramissennyeydd in #33701.infinispan from ^0.12.0 to ^0.13.0 to address known vulnerabilities.json-schema runtime dependency across several packages. Contributed by @rohanjethwani17 in #34143.mountPath option to renderInTestApp in @backstage/frontend-test-utils for testing page components that depend on URL parameters.runCli for creating executable CLI packages from a fixed collection of directly imported CLI modules.This release does not contain any security fixes.
Big shoutout to all 30 of you amazing folks who chipped in on this release: @04kash, @GitanshKapoor, @JessicaJHee, @Naga15, @Naycon, @alien2003, @apc-kamezaki, @aramissennyeydd, @asheen1234, @cdedreuille, @clairep94, @gashcrumb, @hudsonb, @its-mitesh-kumar, @jabrks, @jescalada, @jroebu14, @koalaty-code, @mtlewis, @neoreddog, @officialasishkumar, @pc-bob, @polasudo, @rferreira98, @robingileborg, @rohanjethwani17, @stephenglass, @stijnbrouwers, @the-serious-programmer, @vinzscam
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.