docs/releases/v1.51.0.md
These are the release notes for the v1.51.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.
NavItemBlueprintThe deprecated NavItemBlueprint has been removed from @backstage/frontend-plugin-api. Navigation items are now discovered from PageBlueprint extensions based on their title and icon params. If you were still using NavItemBlueprint, migrate by setting title and icon on the page extension instead. All built-in plugins have been updated accordingly.
Additionally, renderInTestApp from @backstage/frontend-test-utils no longer renders a sidebar or legacy nav-item extensions. The app nav extension is now disabled in the minimal test app shell.
PortableSchema.schema property formThe deprecated property form of PortableSchema.schema has been removed from @backstage/frontend-plugin-api. The schema member is now a plain method that must be called as schema() — direct property access like schema.type or schema.properties is no longer supported.
The default allowed patterns for CIMD and DCR in @backstage/plugin-auth-backend have been hardened. The previous permissive ['*'] wildcards have been replaced with specific defaults for known MCP clients. If you previously relied on the permissive defaults and have custom MCP clients, you will need to explicitly add their patterns to the allow list.
PolicyQueryUser typeThe token and expiresInSeconds fields have been removed from PolicyQueryUser in @backstage/plugin-permission-node. These were previously deprecated in favor of credentials with coreServices.auth. The identity field has been deprecated. A new CachedUserInfoService with a 5-second TTL cache and in-flight request coalescing has been added to reduce repeated user info lookups.
When paginating entities with an order field via /entities/by-query, entities that lack the order field are now excluded from both the result set and the totalItems count. Previously these entities appeared at the end via NULLS LAST, but cursor-based pagination could not actually reach them past the first page — the count over-reported the number of navigable entities.
The @backstage/plugin-catalog-backend-module-msgraph and @backstage/plugin-catalog-backend-module-msgraph-incremental providers now filter out disabled user accounts by default. The provider automatically applies an accountEnabled eq true filter, combining it with any custom user.filter you provide. If you need to ingest disabled accounts, set the filter to explicitly include them.
Contributed by @mtlewis in #34165
There are several new additions in Backstage UI:
New components: A Combobox component pairs a text input with a filterable dropdown, supporting sectioned options, icons, sizes, and custom typed values. New DatePicker and DateRangePicker components provide accessible date selection with calendar popovers built on React Aria. Flex item props (grow, shrink, basis) have been added to Box, Card, Grid, and Flex.
Header improvements: A sticky prop has been added to the Header component that keeps the title-and-actions bar fixed at the top of its scroll container. New description, tags, and metadata props provide richer header content. The breadcrumbs prop has been deprecated.
Other additions: Grouped options in Select, isPending prop replacing loading across components, searchDebounceMs and filterDebounceMs options for useTable, PasswordField visual alignment with TextField, a public --bui-bg-inherit CSS variable, and keyboard focus indicators on Card links.
Breaking changes:
Header component. Custom styles targeting this class should be updated.@remixicon/react dependency limited to versions below 4.9.0 due to a license change.The Combobox was contributed by @jabrks in #34118. The DatePicker was contributed by @Swiftwork in #34184. Flex item props were contributed by @mtlewis in #33948.
Check the BUI Changelog for more details.
AiResource catalog entity kindA new AiResource catalog entity kind has been introduced, with entity types, validators, type guards, and model layer definitions exported from @backstage/catalog-model/alpha. Install @backstage/plugin-catalog-backend-module-ai-model to enable it. A new spec.type: 'mcp-server' structured subtype has also been added to the API kind, with a spec.remotes list for representing MCP server connections.
A new @backstage/plugin-catalog-backend-module-msgraph-incremental module provides cursor-based incremental ingestion for Microsoft Graph. Unlike MicrosoftGraphOrgEntityProvider, this module never holds the full dataset in memory — each burst processes a single page of up to 999 users or 100 groups. The cursor is persisted so a pod restart resumes from the last completed page.
Contributed by @sriharsha9618 in #34053
The formDecorators field on template specs, the formDecoratorsApiRef API, and the FormDecoratorBlueprint have been promoted from @alpha to @public across @backstage/plugin-scaffolder, @backstage/plugin-scaffolder-react, @backstage/plugin-scaffolder-common, and @backstage/plugin-scaffolder-backend. The previous EXPERIMENTAL_formDecorators field continues to work as a deprecated alias. Decorator input is now validated against the configured zod schema before execution.
An experimental Backstage UI form theme has been added for scaffolder forms. All default field extensions render BUI variants when enabled. Set enableBackstageUi: true in the sub-page:scaffolder/templates extension config to try it out.
The sub-page:scaffolder/templates extension now accepts a groups config field for defining template groups on the template list page. Each group has a title and a filter predicate. Templates not matched by any group fall into an "Other Templates" group.
app:
extensions:
- sub-page:scaffolder/templates:
config:
groups:
- title: Recommended Services
filter:
spec.type: service
- title: Documentation
filter:
spec.type: documentation
The TemplateCard is now a swappable component — apps using the new frontend system can replace it via SwappableComponentBlueprint.
ExtensionPointFactoryMiddleware for backendA new ExtensionPointFactoryMiddleware type and createExtensionPointFactoryMiddleware helper have been added to @backstage/backend-app-api, allowing extension point outputs to be replaced at backend creation time. The defaultServiceFactories export has been added to @backstage/backend-defaults for use with createSpecializedBackend.
Contributed by @UsainBloot in #33782
TracingServiceAn alpha TracingService has been added to @backstage/backend-plugin-api and @backstage/backend-defaults, providing a unified interface for emitting trace spans across Backstage plugins. The service includes context and propagation support for bridging OpenTelemetry context across async boundaries. MCP tools/call invocations now emit trace spans following OpenTelemetry server-side MCP semantic conventions. A corresponding mock is available in @backstage/backend-test-utils.
Contributed by @iamEAP in #34087
Several performance improvements have been made to the catalog backend:
(key, value, entity_id) index in sorted order and short-circuit on LIMIT, reducing typical paginated list times from seconds to milliseconds.WHERE entity_id IN (subquery) when filters are applied, with measured improvements from ~1.2x to 7x.COUNT(DISTINCT entity_id) to COUNT(*), enabled by the new unique constraint.catalog_entities_count metric now shares a single cached query between Prometheus and OpenTelemetry gauges.relations.target_entity_ref has been added, fixing full sequential scans on orphan deletion, entity ancestry, and eager pruning queries.WHERE ref IN (...) queries now use = ANY($1) with a single array parameter to reduce prepared statement bloat.search table, creates covering indices, and adds a UNIQUE constraint on (entity_id, key, value). For large installations, it is recommended to run the provided SQL commands before deploying — see the changelog for details.no-self-package-imports ruleA new no-self-package-imports lint rule has been added to @backstage/eslint-plugin, enabled as error in the recommended config. It reports when a package imports itself by its own name instead of using a relative path — a pattern that causes circular initialization errors in bundled ESM and with jest.requireActual.
Contributed by @dyatko in #34041
Added webIdentityTokenFile to @backstage/integration-aws-node account configuration. When set along with a roleName, DefaultAwsCredentialsManager retrieves credentials by calling AssumeRoleWithWebIdentity using the file's contents as the web identity token. The file is re-read on each credential refresh.
Contributed by @hudsonb in #34149
Added support for disabling external font downloads in TechDocs, useful for air-gapped Backstage instances. Available via the techdocs.generator.mkdocs.disableExternalFonts app-config option and the techdocs-cli generate --disableExternalFonts CLI flag.
Contributed by @karthikjeeyar in #31838
always() and failure() status functions for scaffolder stepsAdded always() and failure() status check functions for scaffolder steps. These can be used in the if field to control execution after failures. always() ensures a step runs regardless of previous step outcomes, while failure() runs a step only when a previous step has failed.
Contributed by @Ferin79 in #32890
The catalog.stitchingStrategy.mode: 'immediate' setting has been deprecated. A warning is now logged on startup when immediate mode is configured. Immediate mode will be removed in the next Backstage release.
sleep firing immediately for durations longer than ~24.8 days, caused by Node.js setTimeout overflowing its 32-bit millisecond limit.Cluster class instead of createCluster from @keyv/redis. Contributed by @ganievs in #33895.CachedUserInfoService where a failed request could incorrectly evict a newer cache entry.mockCredentials to include the internal version: 'v1' field on all credential objects.$all, $any, $not) with other keys now being rejected instead of silently dropping conditions.PackageGraph.listChangedPackages where removed dependencies were not detected during lockfile analysis.down functions in the catalog backend that were not properly reversible.--legacyCopyReadmeMdToIndexMd option to fail if docs directory is not present. Contributed by @rtar in #33370.~30.2.0 to prevent automatic upgrades to Jest 30.4.x, which requires Node.js v24.9+.tools/call trace spans following OpenTelemetry semantic conventions. Contributed by @iamEAP in #34089.ConfigContent component in DevTools from Material UI to Backstage UI. Contributed by @AdityaK60 in #33252.status filter parameter. Contributed by @johnmcollier in #33122.allowEmpty input option to the gitlab:repo:push scaffolder action. Contributed by @elaine-mattos in #33602.clustersCacheTtlMs option to KubernetesBackendClient for caching cluster responses. Contributed by @alde in #34136.theme.title for theme names in user settings. Contributed by @its-mitesh-kumar in #34113.GithubMultiOrgEntityProvider now emits entities in a stable order during full mutations.uuid dependency across many packages, replacing it with the built-in crypto.randomUUID().This release does not contain any security fixes.
Big shoutout to all 34 of you amazing folks who chipped in on this release: @AdityaK60, @Ferin79, @Naycon, @Swiftwork, @UsainBloot, @adobejmong, @alde, @aurnik, @benjidotsh, @cdedreuille, @copilot-swe-agent, @davidjosefson-neo4j, @deepthi-28, @djamaile, @drodil, @dyatko, @elaine-mattos, @emmaindal, @erikmiller-gusto, @etienne-napoleone, @ganievs, @hudsonb, @iamEAP, @its-mitesh-kumar, @jabrks, @johnmcollier, @jtbry, @karthikjeeyar, @mtlewis, @officialasishkumar, @rtar, @secustor, @sriharsha9618, @wss-dogara
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.