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
: Usebackstage-cli new
insteadcreate-plugin
: Usebackstage-cli new
insteadplugin:diff
: Usebackstage-cli fix
insteadtest
: Usebackstage-cli repo test
orbackstage-cli package test
insteadversions:check
: Useyarn dedupe
ornpx yarn-deduplicate
insteadclean
: Usebackstage-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
.
Promoted New Backend System exports to default export
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.
Links and References
Below you can find a list of links and references to help you learn about and start using this new release.
- Backstage official website, documentation, and getting started guide
- GitHub repository
- Backstage's versioning and support policy
- Community Discord for discussions and support
- Changelog
- Backstage Demos, Blog, [Roadmap](https://backstage.io /docs/overview/roadmap) and Plugins
Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.