Skip to main content

v1.46.0

These are the release notes for the v1.46.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​

To begin with, this release has a few important framework level updates.

BREAKING: Updated supported Node.js versions to 22 and 24​

This release moves up the supported Node.js versions to 22 and 24, according to our versioning policy. As part of this change, we are also setting the compilation targets to ES2023, which lines up with the supported Node.js versions.

The default TypeScript target compiler option is however left at ES2022. This is because older versions of TypeScript will error if they see an unsupported value, even if an override is set in your local tsconfig.json. You can still choose to set the TypeScript target to either ES2023 or even ES2024 in your own tsconfig.json if you prefer.

BREAKING: Switched modules to ES2020 and resolution mode to bundler​

Now that the ecosystem has had some time to mature and adapt, we have finally switched over the default module resolution mode to bundler instead of node. The module setting was also changed to ES2022.

You may need to bump some dependencies as part of this change, or 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, but if you depend on old versions or unmaintained packages, you may still notice some effects of this.

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 of 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.

BREAKING: Moving toward updating jest and its DOM​

The jest test framework used to be a builtin dependency of the Backstage CLI. In this release, it has been made into a peer dependency to allow for easy upgrades to newer versions as you see fit.

If you run tests using the Backstage CLI, you must therefore add Jest and its environment dependencies as devDependencies in your project root package.json when you upgrade.

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: Install jest@^29 and jest-environment-jsdom@^29 in your root package.json. 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: Install jest@^30, @jest/environment-jsdom-abstract@^30, and jsdom@^27 in your root package.json. Fixes the stylesheet parsing warnings/errors, but requires migration steps.

See the Jest 30 migration guide for detailed migration instructions.

BREAKING: Now using correct configuration options for Valkey​

If you are using Valkey as your backend cache provider, take note. It used to piggyback on the Redis configuration format, but that was not quite correct. So its config options have been updated to better match its capabilities.

So if you use Valkey, you need to upgrade your app-config.yaml:

backend:
  cache:
    store: valkey
    connection: ...
    client:
-     namespace: 'my-app'
-     keyPrefixSeparator: ':'
+     keyPrefix: 'my-app:'
-     clearBatchSize: 1000
-     useUnlink: false

Contributed by @benjidotsh in #31497

BREAKING: Techdocs addon test utils removed explicit screen​

TechdocsAddonTester.renderWithEffects() used to return a screen that you could use for things like getByText. In order to support moving to newer versions of @testing-library, we have removed this, and you should import and use the normal screen from @testing-library/react instead.

However: that screen can’t see inside the shadow DOM, which TechDocs uses. So if your tests need to look inside shadow DOM, you must install shadow-dom-testing-library and use its screen which provides special shadow-DOM queries, such as getByShadowText instead of `getByText.

Example:

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();

BREAKING: Backstage-UI advances!​

Again, Backstage-UI has a bunch of updates! One of them is breaking: If you were using the Cell component with text-specific props (title etc), you should now instead use the CellText component for that. Plain Cell is now meant to be used with generic child elements instead.

Simplified route compatibility​

If you are partway through a migration to the New Frontend System, you may enjoy the fact that the useApp and useRouteRef hooks now are forwards compatible with NFS. 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.

Support for Bitbucket Cloud OAuth​

Support for Bitbucket Cloud OAuth has been added - which was much welcome. 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.

As part of this change, some breaking changes were made to low level auth getter functions, such that they now return a promise instead of a plain value.

Contributed by @jksmth in #31848

New Catalog actions​

There are two new MCP-usable actions on the block for registering and unregistering entities: catalog:register-entity and catalog:unregister-entity.

Contributed by @gabemontero in #32042

New RepoOwnerPicker for Scaffolder​

A new field extension for selecting an organization or owner for a particular repository has been shipped! Currently, this only supports GitHub autocomplete, but contributions welcome in making this available for other providers!

Contributed by @benjidotsh in #32105

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.