docs/releases/v1.46.0-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.46.0
8d6709e: BREAKING: TechDocsAddonTester.renderWithEffects() no longer returns a screen; this means that you can no longer grab assertions such as getByText from its return value.
Newer versions of @testing-library recommends using the screen export for assertions - and removing this from the addon tester contract allows us to more freely iterate on which underlying version of the testing library is being used.
One notable effect of this, however, is that the @testing-library screen does NOT support assertions on the shadow DOM, which techdocs relies on. You will therefore want to add a dependency on the shadow-dom-testing-library package in your tests, and using its screen and its dedicated *Shadow* methods. As an example, if you keep doing getByText you will not get matches inside the shadow DOM - switch to getByShadowText instead.
import { screen } from 'shadow-dom-testing-library';
// ... render the addon ...
await TechDocsAddonTester.buildAddonsInTechDocs([<AnAddon />])
.withDom(<body>TEST_CONTENT</body>)
.renderWithEffects();
expect(screen.getByShadowText('TEST_CONTENT')).toBeInTheDocument();
5a2d538: Introduced backend startup result tracking and error handling. The Backend.start() method now returns a BackendStartupResult with detailed success/failure status and timing information for all plugins and modules. When startup fails, a BackendStartupError is thrown that includes the complete startup results, making it easier to diagnose which plugins or modules failed.
This also improves the default error message when backend startup fails, and of course makes it possible to craft your own custom error reporting based on the startup results.
fa43826: Move better-sqlite3 from dependencies to peer dependencies
2bc4e02: BREAKING The correct configuration options for Valkey are now being used.
These changes are required to app-config.yaml:
backend:
cache:
store: valkey
connection: ...
client:
- namespace: 'my-app'
- keyPrefixSeparator: ':'
+ keyPrefix: 'my-app:'
- clearBatchSize: 1000
- useUnlink: false
In comparison to Redis, Valkey requires the full keyPrefix including the separator to be specified instead of separate namespace and keyPrefixSeparator options. Also, Valkey does not support the clearBatchSize and useUnlink options.
37fba1d: Added support for Bitbucket Cloud OAuth. This introduces an alternative authentication method using a workspace OAuth consumer, alongside App Passwords (deprecated) and API tokens. OAuth does not require a bot or service account and avoids token expiry issues.
BREAKING CHANGES
@backstage/integration (src/bitbucketCloud/core.ts)
getBitbucketCloudRequestOptions now returns a Promise and must be awaited.@backstage/plugin-scaffolder-backend-module-bitbucket-cloud (src/actions/helpers.ts)
getBitbucketClient now returns a Promise and must be awaited.getAuthorizationHeader now returns a Promise and must be awaited.OAuth usage example
integrations:
bitbucketCloud:
- clientId: client-id
clientSecret: client-secret
de96a60: chore(deps): bump express from 4.21.2 to 4.22.0
aa79251: build(deps): bump node-forge from 1.3.1 to 1.3.2
f96edff: Allow configuration of the referrerPolicy
fb029b6: Updated luxon types
d9759a1: BREAKING ALPHA: The old instanceMetadataService has been removed from alpha. Please switch over to using the stable coreServices.rootInstanceMetadata and related types instead, available from @backstage/backend-plugin-api.
847a330: Fix for jose types
25b560e: Internal change to support new versions of the logform library
2a0c4b0: Adds a new experimental RootSystemMetadataService for tracking the collection of Backstage instances that may be deployed at any one time. It currently offers a single API, getInstalledPlugins that returns a list of installed plugins based on config you have set up in discovery.endpoints as well as the plugins installed on the instance you're calling the API with. It does not handle wildcard values or fallback values. The intention is for this plugin to provide plugin authors with a simple interface to fetch a trustworthy list of all installed plugins.
3016a79: Updated dependency @types/archiver to ^7.0.0.
42db6a6: Don't warn when parsing storeOptions for memory cache
Updated dependencies
RootSystemMetadataService for tracking the collection of Backstage instances that may be deployed at any one time. It currently offers a single API, getInstalledPlugins that returns a list of installed plugins based on config you have set up in discovery.endpoints as well as the plugins installed on the instance you're calling the API with. It does not handle wildcard values or fallback values. The intention is for this plugin to provide plugin authors with a simple interface to fetch a trustworthy list of all installed plugins.instanceMetadataService has been removed from alpha. Please switch over to using the stable coreServices.rootInstanceMetadata and related types instead, available from @backstage/backend-plugin-api.f6f22a9: Provide --no-node-snapshot by default when running the package start or package test. You can disable this behavior by providing NODE_OPTIONS='--node-snapshot'.
f8dff94: Switched the default module resolution to bundler and the module setting to ES2020.
You may need to bump some dependencies as part of this change and fix imports in code. The most common source of this is that type checking will now consider the exports field in package.json when resolving imports. This in turn can break older versions of packages that had incompatible exports fields. Generally these issues will have already been fixed in the upstream packages.
You might be tempted to use --skipLibCheck to hide issues due to this change, but it will weaken the type safety of your project. If you run into a large number of issues and want to keep the old behavior, you can reset the moduleResolution and module settings your own tsconfig.json file to node and ESNext respectively. But keep in mind that the node option will be removed in future versions of TypeScript.
A future version of Backstage will make these new settings mandatory, as we move to rely on the exports field for type resolution in packages, rather than the typesVersions field.
cd0b8a1: BREAKING: jest is now a peer dependency. If you run tests using Backstage CLI, you must add Jest and its environment dependencies as devDependencies in your project.
You can choose to install either Jest 29 or Jest 30. The built-in Jest version before this change was Jest 29, however, we recommend that you switch to Jest 30. Upgrading will solve the Could not parse CSS stylesheet errors, allow you to use MSW v2 in web packages, and ensure that you remain compatible with future versions of the Backstage CLI. Support for Jest 29 is temporary, with the purpose of allowing you to upgrade at your own pace, but it will eventually be removed.
jest@^29 and jest-environment-jsdom@^29. No migration needed, but you may see Could not parse CSS stylesheet warnings/errors when testing components from @backstage/ui or other packages using CSS @layer declarations.jest@^30, @jest/environment-jsdom-abstract@^30, and jsdom@^27. Fixes the stylesheet parsing warnings/errors, but requires migration steps.See the Jest 30 migration guide for detailed migration instructions.
de96a60: chore(deps): bump express from 4.21.2 to 4.22.0
e7db290: Add missing peer/dev dependencies to the frontend plugin template.
react-dom was not declared as a peer dependency, causing module resolution
errors when generating plugins outside a Backstage monorepo. This adds
react-dom to peerDependencies (for consuming apps) and devDependencies
(for local development). react-router-dom is also added to peerDependencies (for consuming apps) and devDependencies
to support routing during plugin development.
Fixes:
1226647: Updated dependency esbuild to ^0.27.0.
f89a074: Updated dependency @pmmmwh/react-refresh-webpack-plugin to ^0.6.0.
2b81751: Updated dependency webpack to ~5.103.0.
fafd9e1: Fixed internal usage of yargs.
c8c2329: Add proxy configuration from env-vars to create-app tasks
2bae83a: Switched compilation target to ES2022 in order to match the new set of supported Node.js versions, which are 22 and 24.
The TypeScript compilation target has been set to ES2022, because setting it to a higher target will break projects on older TypeScript versions. If you use a newer TypeScript version in your own project, you can bump compilerOptions.target to ES2023 or ES2024 in your own tsconfig.json file.
7fbac5c: Updated to use new utilities from @backstage/cli-common.
2bae83a: Bumped dev dependencies @types/node
Updated dependencies
37fba1d: Added support for Bitbucket Cloud OAuth. This introduces an alternative authentication method using a workspace OAuth consumer, alongside App Passwords (deprecated) and API tokens. OAuth does not require a bot or service account and avoids token expiry issues.
BREAKING CHANGES
@backstage/integration (src/bitbucketCloud/core.ts)
getBitbucketCloudRequestOptions now returns a Promise and must be awaited.@backstage/plugin-scaffolder-backend-module-bitbucket-cloud (src/actions/helpers.ts)
getBitbucketClient now returns a Promise and must be awaited.getAuthorizationHeader now returns a Promise and must be awaited.OAuth usage example
integrations:
bitbucketCloud:
- clientId: client-id
clientSecret: client-secret
publicAccess option is enabled. When all other authentication methods fail (e.g., the app is not installed in that organization), the provider will now use an available installation to generate a token that can be used to access public repositories as read only.16543fa: Breaking change The Cell component has been refactored to be a generic wrapper component that accepts children for custom cell content. The text-specific functionality (previously part of Cell) has been moved to a new CellText component.
If you were using Cell with text-specific props (title, description, leadingIcon, href), you need to update your code to use CellText instead:
Before:
<Cell
title="My Title"
description="My description"
leadingIcon={<Icon />}
href="/path"
/>
After:
<CellText
title="My Title"
description="My description"
leadingIcon={<Icon />}
href="/path"
/>
For custom cell content, use the new generic Cell component:
<Cell></Cell>
50b7927: Fixed Checkbox indicator showing checkmark color when unchecked.
Affected components: Checkbox
5bacf55: Fixed ButtonIcon incorrectly applying className to inner elements instead of only the root element.
Affected components: ButtonIcon
b3ad928: Fixed Table Row component to correctly handle cases where no href is provided, preventing unnecessary router provider wrapping and fixing the cursor incorrectly showing as a pointer despite the element not being a link.
Affected components: Row
a20d317: Added row selection support with visual state styling for hover, selected, and pressed states. Fixed checkbox rendering to only show for multi-select toggle mode.
Affected components: Table, TableHeader, Row, Column
fe7c751: Fixed useTable hook to prioritize providedRowCount over data length for accurate row count in server-side pagination scenarios.
c145031: Fixed Table column sorting indicator to show up arrow when no sort is active, correctly indicating that clicking will sort ascending.
Affected components: Column
github.com/user-id annotation to store GitHub's user ID (immutable) in user entities. Also includes addition of the userIdMatchingUserEntityAnnotation sign-in resolver that matches users by the new ID.ActionsRegistry actions for register-entity and unregister-entityexpress from 4.21.2 to 4.22.0github.com/user-id annotation to store GitHub's user ID (immutable) in user entities. Also includes addition of the userIdMatchingUserEntityAnnotation sign-in resolver that matches users by the new ID.ed5a7a3: Introduce new configuration option to exclude suspended users from GitHub Enterprise instances.
When it’s set to true, suspended users won’t be returned when querying the organization users for GitHub Enterprise instances. Note that this option should be used only against GitHub Enterprise instances, the property does not exist in the github.com GraphQL schema, setting it will cause a schema validation error and the syncing of users will fail.
a413977: Added configurable pageSizes option to GithubOrgEntityProvider for GitHub GraphQL API queries to prevent RESOURCE_LIMITS_EXCEEDED errors with organizations with large number of teams and members. This aligns the configuration options with GithubMultiOrgEntityProvider.
Updated dependencies
2c74ea9: Added support for multiple named instances in kafkaConsumingEventPublisher configuration. The previous single configuration format is still supported for backward compatibility.
2c74ea9: Added KafkaPublishingEventConsumer to support sending Backstage events to Kafka topics.
This addition enables Backstage to publish events to external Kafka systems, complementing the existing ability to receive events from Kafka. This allows for better integration with external systems that rely on Kafka for event streaming.
express from 4.21.2 to 4.22.0@aws-sdk/signature-v4 with @smithy/signature-v4,
as stated in the package documentationconcurrencyLimit and throttleInterval options.@faker-js/faker to ^10.0.0.RepoOwnerPicker for retrieving GitHub repository owners.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.@rjsf/utils to 5.24.13.
Updated dependency @rjsf/core to 5.24.13.
Updated dependency @rjsf/material-ui to 5.24.13.
Updated dependency @rjsf/validator-ajv8 to 5.24.13.defaultEnvironment config to scaffolder to enable more flexible and custom templates. Now it's possible enable access to default parameters and secrets in templates, improving security and reducing complexity.express from 4.21.2 to 4.22.0isolated-vm to 6.0.1logform libraryesbuild to ^0.27.0.37fba1d: Added support for Bitbucket Cloud OAuth. This introduces an alternative authentication method using a workspace OAuth consumer, alongside App Passwords (deprecated) and API tokens. OAuth does not require a bot or service account and avoids token expiry issues.
BREAKING CHANGES
@backstage/integration (src/bitbucketCloud/core.ts)
getBitbucketCloudRequestOptions now returns a Promise and must be awaited.@backstage/plugin-scaffolder-backend-module-bitbucket-cloud (src/actions/helpers.ts)
getBitbucketClient now returns a Promise and must be awaited.getAuthorizationHeader now returns a Promise and must be awaited.OAuth usage example
integrations:
bitbucketCloud:
- clientId: client-id
clientSecret: client-secret
gitlabRepoPush action, add 'auto' possibility for commitAction input.express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0textextensions dependency for text-extensions.TestDatabases by pinning the data directoryrun, runOutput, and runCheck utilities to help run child processes in a safe and portable way.@types/node@backstage/cli-common.@backstage/cli-common.@types/nodetypescript-json-schema to ^0.67.0.AlertApiForwarder to buffer and replay recent alerts to new subscribers, preventing missed alerts that were posted before subscription.9a942a4: Fixed bug in the LogViewer component where shift + click always opened a new window instead of just changing the selection.
In addition, improved the LogViewer component by a few usability enhancements:
207c3c8: long words like urls now breaks to new line on warning panels instead of overflowing the container
4c00303: Add tooltipClasses prop to OverflowTooltip component to allow customisation of the tooltip
5d52dab: Add i18n support for LogViewer search control
f6b49ce: added support for wrapLongLines option in CodeSnippet
Updated dependencies
useApp and useRouteRef functions are now forwards compatible with the new frontend system. Along with the previous route reference changes this means that there is no longer a need to use compatWrapper from @backstage/core-compat-api to make code based on @backstage/core-plugin-api compatible with @backstage/frontend-plugin-api APIs.@backstage/core-plugin-api and the new @backstage/frontend-plugin-api. Previously, the a lot of API definitions and utilities where defined in the old and re-exported from the old, but this change flips that around so that they now reside in the new package and are re-exported from the old. The external API of both packages remain the same, but this is a step towards being able to add further compatibility with the new frontend system built into the old.@types/node75683ed: Added a new errorPresentation prop to ExtensionBoundary to control how errors are presented to the user. The default is 'error-display', which is the current behavior of showing the error in the ErrorDisplay component. The new option is 'error-api', posts errors to the ErrorApi and does not allow retries.
The AppRootElementBlueprint now wraps its element in an ErrorBoundary using the new 'error-api' presentation mode.
0bc1ce9: Fixed a versioning conflict that could result in a .withContext is not a function error.
f3f84f1: Made the return type of .withOverrides to be simplified.
97cd16f: Reversed the relationship between the old @backstage/core-plugin-api and the new @backstage/frontend-plugin-api. Previously, the a lot of API definitions and utilities where defined in the old and re-exported from the old, but this change flips that around so that they now reside in the new package and are re-exported from the old. The external API of both packages remain the same, but this is a step towards being able to add further compatibility with the new frontend system built into the old.
9b8bde4: Removed unnecessary dependencies on @backstage/core-components, @backstage/config, @material-ui/core, and lodash.
688f070: Updated to use new utilities from @backstage/cli-common.
85895f9: Updates OpenAPI generator templates to preserve original property names (like 'group-name', 'user-id') from OpenAPI specs when propertyNaming=original is specified. Previously, these were always converted to camelCase regardless of the propertyNaming setting.
2bae83a: Bump @microsoft/api-documenter and @microsoft/api-extractor to latest versions.
d1e38a7: Properly create workspace in OS temporary directory for generate-patch command
2bae83a: Bumped dev dependencies @types/node
Updated dependencies
@backstage/cli-common.@types/nodethemeName prop to UnifiedThemeProvider, enabling Backstage UI data-theme-name CSS attribute to be set based on active theme.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.defaultLanguage and availableLanguages for the app language API in the new frontend systemcompatWrapper and convertLegacyRouteRef(s) for the new frontend system.express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0compatWrapper and convertLegacyRouteRef(s) for the new frontend system.express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.037fba1d: Added support for Bitbucket Cloud OAuth. This introduces an alternative authentication method using a workspace OAuth consumer, alongside App Passwords (deprecated) and API tokens. OAuth does not require a bot or service account and avoids token expiry issues.
BREAKING CHANGES
@backstage/integration (src/bitbucketCloud/core.ts)
getBitbucketCloudRequestOptions now returns a Promise and must be awaited.@backstage/plugin-scaffolder-backend-module-bitbucket-cloud (src/actions/helpers.ts)
getBitbucketClient now returns a Promise and must be awaited.getAuthorizationHeader now returns a Promise and must be awaited.OAuth usage example
integrations:
bitbucketCloud:
- clientId: client-id
clientSecret: client-secret
Updated dependencies
compatWrapper and convertLegacyRouteRef(s) for the new frontend system.catalogAboutEntityCard to filter icon links before calling useProps(), preventing side effects from hooks in filtered-out linksed5a7a3: Introduce new configuration option to exclude suspended users from GitHub Enterprise instances.
When it’s set to true, suspended users won’t be returned when querying the organization users for GitHub Enterprise instances. Note that this option should be used only against GitHub Enterprise instances, the property does not exist in the github.com GraphQL schema, setting it will cause a schema validation error and the syncing of users will fail.
Updated dependencies
express from 4.21.2 to 4.22.0& with &)compatWrapper and convertLegacyRouteRef(s) for the new frontend system.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.EntityOwnerPicker failed to filter options when the input text contained uppercase characters.useEntityList, to better work with mixed @backstage/plugin-catalog-react versions.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.d02db50: Remove unnecessary use of compatWrapper and convertLegacyRouteRef(s) for the new frontend system.
df4d646: Moved types, API and client to the common package, allowing both frontend and
backend plugins to use the CatalogUnprocessedEntitiesClient.
The following types, clients and interfaces have been deprecated and should be
imported from the @backstage/plugin-catalog-unprocessed-entities-common instead:
CatalogUnprocessedEntitiesApi, CatalogUnprocessedEntitiesApiResponse, UnprocessedEntity,
UnprocessedEntityCache, UnprocessedEntityError, CatalogUnprocessedEntitiesClient.
All those types, clients and interfaces are re-exported temporarily in the
@backstage/plugin-catalog-unprocessed-entities package until cleaned up.
Updated dependencies
df4d646: Moved types, API and client to the common package, allowing both frontend and
backend plugins to use the CatalogUnprocessedEntitiesClient.
The following types, clients and interfaces have been deprecated and should be
imported from the @backstage/plugin-catalog-unprocessed-entities-common instead:
CatalogUnprocessedEntitiesApi, CatalogUnprocessedEntitiesApiResponse, UnprocessedEntity,
UnprocessedEntityCache, UnprocessedEntityError, CatalogUnprocessedEntitiesClient.
All those types, clients and interfaces are re-exported temporarily in the
@backstage/plugin-catalog-unprocessed-entities package until cleaned up.
compatWrapper and convertLegacyRouteRef(s) for the new frontend system.express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0eventsource to ^4.0.0.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.@rjsf/utils to 5.24.13.
Updated dependency @rjsf/core to 5.24.13.
Updated dependency @rjsf/material-ui to 5.24.13.
Updated dependency @rjsf/validator-ajv8 to 5.24.13.@rjsf/utils to 5.24.13.
Updated dependency @rjsf/core to 5.24.13.
Updated dependency @rjsf/material-ui to 5.24.13.
Updated dependency @rjsf/validator-ajv8 to 5.24.13.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.@types/node@cfworker/json-schema as a dependency to this package part of the @modelcontextprotocol/sdk bump as it's required in the typesexpress from 4.21.2 to 4.22.0d02db50: Remove unnecessary use of compatWrapper and convertLegacyRouteRef(s) for the new frontend system.
53347cc: Move long notification descriptions behind Show more/less button.
This improves readability of the notifications list by preventing long descriptions from taking up too much space or rendering very small scrollable areas.
Updated dependencies
express from 4.21.2 to 4.22.0a5d5b3a: SES config for the notification email processor now supports utilizing an ARN for the SES identity when sending an email after the SES SDK V2 update.
The sesConfig.fromArn will set the fromEmailAddressIdentityArn option for the SES SendEmailCommand. The sesConfig.sourceArn field is removed since no equivalent option is available in the send email command options. Setting sesConfig.sourceArn will have no effect and log a warning. Example changes:
notifications:
processors:
email:
transportConfig:
transport: "ses"
region: "us-west-2"
sender: "[email protected]"
replyTo: "[email protected]"
sesConfig:
- sourceArn: "arn:aws:ses:us-west-2:123456789012:identity/example.com"
fromArn: "arn:aws:ses:us-west-2:123456789012:identity/example.com"
b267aea: Updated dependency @types/nodemailer to ^7.0.0.
Updated dependencies
compatWrapper and convertLegacyRouteRef(s) for the new frontend system.express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0owners for retrieving GitHub repository owners.@types/nodereview.name values were incorrectly formatted by startCase, preserving them exactly as written.@rjsf/utils to 5.24.13.
Updated dependency @rjsf/core to 5.24.13.
Updated dependency @rjsf/material-ui to 5.24.13.
Updated dependency @rjsf/validator-ajv8 to 5.24.13.use-immer to ^0.11.0.compatWrapper and convertLegacyRouteRef(s) for the new frontend system.express from 4.21.2 to 4.22.0@backstage-community/plugin-explore-common to ^0.9.0.express from 4.21.2 to 4.22.0express from 4.21.2 to 4.22.0compatWrapper and convertLegacyRouteRef(s) for the new frontend system.techdocs config is now marked as optional.express from 4.21.2 to 4.22.0ErrorCallback type to work with Node 22 typestechdocs config is now marked as optional.express from 4.21.2 to 4.22.0compatWrapper and convertLegacyRouteRef(s) for the new frontend system.express from 4.21.2 to 4.22.0