Skip to main content

v1.32.0

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

BREAKING: Auth improvements​

We have entirely removed the profileEmailMatchingUserEntityEmail sign-in resolver as it was using an insecure fallback for resolving user identities. See this article for how to create a custom sign-in resolver if needed as a replacement.

The emailLocalPartMatchingUserEntityName also now has an allowedDomains option that makes it easier to set it up to safely only permit people from your own organization to authenticate. We recommend that you set that option in your installation, if you use this resolver.

Example:

auth:
  providers:
    github:
      development:
        ...
        signIn:
          resolvers:
            - resolver: emailLocalPartMatchingUserEntityName
              allowedDomains:
                - acme.org

See also the full identity resolvers documentation for more details.

BREAKING: CLI Changes​

We’ve been doing some cleanup and removed some deprecated commands, updated as follows:

  • create: Use backstage-cli new instead
  • create-plugin: Use backstage-cli new instead
  • plugin:diff: Use backstage-cli fix instead
  • test: Use backstage-cli repo test or backstage-cli package test instead
  • versions:check: Use yarn dedupe or npx yarn-deduplicate instead
  • clean: Use backstage-cli package clean instead

Jest configuration no longer merges from all parent package.json jest configurations. Instead it only merges from the package under test and the root monorepo jest config.

BREAKING: New Frontend System Deprecation Removals​

This section only applies if you are an early adopter of the new frontend system which is in alpha.

We’ve removed the previously deprecated namespace option from createExtension and createExtensionBlueprint methods, including .make and .makeWithOverrides.

We’ve also removed the deprecated createExtensionOverrides in favor of createFrontendModule as well as removing BackstagePlugin type in favor of FrontendPlugin to align with the New Backend System.

And lastly, createApp should now be imported from @backstage/frontend-defaults instead of previously deprecated @backstage/frontend-app-api.

Since the New Backend System was shipped as 1.0 in a previous release, our core plugins are now available from the regular default package export instead of the /alpha subpath. The old alpha exports still work for a bit longer, but will be removed completely in an upcoming release.

This means that in your packages/backend/src/index.ts file, you can now change your imports as follows:

-backend.add(import('@backstage/plugin-catalog-backend/alpha'));
+backend.add(import('@backstage/plugin-catalog-backend'));

And similarly for other plugins. You’ll find that many plugin modules however may still remain on the /alpha export for a bit longer, while we settle their interfaces.

We would also like to highlight that the @backstage/backend-common and @backstage/backend-tasks packages that were part of the old backend system are now fully deprecated and removed from our code repositories, and therefore no longer get published or updated. If you have not yet moved off of features in those packages, now would be a good time to look into doing so. The new backend system section of the documentation contains lots of details and migration instructions.

Scaffolder UI Improvements​

This month we've been working on improving the user flow for creating templates with Scaffolder. You can now use the Template Editor to sketch templates from zero. We also updated the Template Editor layout for you to have quick access to the Custom Fields Explorer and installed Actions documentation while editing the template files.

And last but not least, a Publish button was added to the editor, which opens a modal with instructions on how to start using a new template in production.

We hope you like it, and please do not hesitate to give us feedback via our community channels!

New Frontend System Updates​

This section only applies if you are an early adopter of the new frontend system which is in alpha.

It’s now possible to override extensions that were created with Blueprints by passing through params instead.

const myExtension = MyBlueprint.make({
  params: {
    myParam: 'myDefault',
  },
});

const myOverride = myExtension.override({
  params: {
    myParam: 'myOverride',
  },
});

The app plugin now provides three more default extensions which means you don’t have to provide these in order to get up and running with the New Frontend System. It now provides default implementations for the scmAuthApiRef as well as scmIntegrationsApiRef, and also a default SignInPage which is configured by default to login as Guest.

You can override the default implementation by using .withOverrides on the app plugin, or by providing another SignInPage extension in a FrontendModule for the app plugin.

CLI Improvements​

We’ve been working on adding some additional features to the CLI and improve performance when working in larger monorepos and setups with Backstage.

There’s a new --successCache option, for both backstage-cli repo lint and backstage-cli repo test which can help cache previous runs from other builds in CI to speed up these commands.

Support for rspack has been added behind an EXPERIMENTAL_RSPACK variable thanks to @JounQin in #25953. Please go ahead and try this out, and report back with some findings!

For those of you who publish Backstage packages, you may also note that the CLI prepack script now automatically adds information about your exported feature to published package.json files. This will serve as a foundation for some cool features, such as dynamic discovery and loading of plugins! Contributed by @HHogg in #26524.

Updated API Extractor​

This section only applies if you are generating API reports using the @backstage/repo-tools CLI.

The API Extractor dependency of @backstage/repo-tools has been updated to the latest version. This changes the API report file name to use the report<entry>.api.md format, for example report.api.md or report-alpha.api.md. This update adds a new ae-undocumented warning, which you can disable using the -o ae-undocumented option if needed.

Contributed by @secustor in #25671.

The events service is now global by default​

It used to be the case that backends using the events service only had their events distributed to local observers on the same actual backend instance. This forced adopters to co-deploy plugins that needed to communicate with each other via this mechanism.

This has now been improved, such that the @backstage/plugin-events-backend (if deployed somewhere) automatically acts as an efficient intermediary bus for distribution across all of your backends when using split deployments. Therefore, you may start to see events flowing between machines as well after this version update.

New testing utilities​

The @backstage/test-utils and @backstage/frontend-test-utils packages now contain a mockApis export that lets you create fakes and mocks for many common utility APIs. This is analogous to the mockServices that already existed in @backstage/backend-test-utils. As this was introduced, the old Mock*Api classes were marked as deprecated - please use mockApis.* instead.

Likewise, there’s a catalogApiMock in @backstage/plugin-catalog-react/testUtils, and a catalogServiceMock in @backstage/plugin-catalog-node/testUtils, that help you easily test against a client that behaves just like a catalog with a fake set of entities.

You’ll also start seeing that your API JSON responses are pretty-printed by default for convenience - but only in development of course.

Finally, improvements were made to the OpenAPI based test facilities. Now you can get simple schema validation immediately as part of your existing tests. See the PR for more details. Contributed by @aramissennyeydd in #25538.

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.