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

New Frontend System Alpha

This release marks the alpha release of the new frontend system, which has been in an experimental state since implementation began in the middle of 2023. This new system brings declarative integration of plugins, which is the ability to integrate new features into a Backstage app without writing any TypeScript code. Through this capability it also paves the way for supporting dynamic plugin installation at runtime.

The alpha release is a point of increased stability following the earlier experimental phase. There is now a complete system that lets you build out a full application, supported by documentation. From this point on any breaking changes will also be clearly marked in the changelog.

There is still a long road ahead to a stable release, and this is not the time to migrate existing applications. There are only a few plugins that support this system so far, and if you want to add to a plugin that you own, please do so under an /alpha sub-path export.

Still, we encourage you to explore this new system to see whether you are confident in this path forward. If you have feedback or want to know more you can reach out in the #declarative-integration channel on Discord, or join an Adoption SIG meeting where the new system is frequently discussed. You can also check out our maintainer talk at KubeCon NA 2023, where we talk about this new system and show a couple of demos.

React Router Beta deprecation

This release of Backstage officially deprecates, but does not immediately remove, support for old beta versions of react-router 6. Actual support for beta versions will be removed entirely in an upcoming release of Backstage. Please upgrade your own Backstage project as soon as possible to a stable version of react-router, by following this guide.

New PostgreSQL versioning policy

The Backstage project has now settled on a clearer policy for what versions of PostgreSQL that it supports. In short, we support the last five released major versions, and actively test against the first and last of those five, in a rolling window over time.

As part of this, the TestDatabases utility class now supports all of the last major versions of PostgreSQL in addition to the ones it supported before. You can also call TestDatabases.setDefaults inside your setupTests.ts file to configure the set of engines to test against, instead of enumerating them in every individual test.

Contributed by @awanlin in #21510

UnifiedTheme Now Supports Overrides

You can now supply overrides for Backstage components when using createUnifiedTheme. We've updated the demo site’s Aperture theme to work with this and you can see the code for that here.

If you are switching from the old way of defining a theme to createUnifiedTheme, note that it uses the MUI v5 overrides format. The style overrides are now nested in a styleOverrides key, and if you want access to the theme you’ll need to use a callback:

BackstageHeaderTabs: {
  styleOverrides: {
    defaultTab: {
      textTransform: 'none',
    },
  },
},
MuiChip: {
  styleOverrides: {
    root: ({ theme }) => ({
      color: theme.palette.primary.dark,
    }),
  },
},

Catalog pagination

CatalogIndexPage now offers an optional pagination feature, designed to accommodate adopters managing extensive catalogs. This new capability allows for better handling of large amounts of data.

To activate the pagination mode, simply update your App.tsx as follows:

  const routes = (
    <FlatRoutes>
      ...
-     <Route path="/catalog" element={<CatalogIndexPage />} />
+     <Route path="/catalog" element={<CatalogIndexPage pagination />} />
      ...

In case you have a custom catalog page and you want to enable pagination, you need to pass the pagination prop to EntityListProvider instead. For now both column sorting and search filtering are still done locally, meaning they only apply to each individual page. This is something we will improve in the future and we still wanted to make this feature available early as it can greatly improve the performance of the catalog page.

Azure DevOps Multi-Org Support

The Azure DevOps plugin now has multi-org support and there is a new processor to help with adding the needed annotations. Contributed by @awanlin in #19622

New Authentication providers

A new Atlassian authentication provider has been added to @backstage/plugin-auth-backend. Contributed by @handsamtw in #21007

A new VMware Cloud authentication provider has been added to @backstage/plugin-auth-backend. Contributed by @luchillo17 in #21337

Kubernetes single cluster selection

You can now select a single kubernetes cluster that the entity is part of from all your defined kubernetes clusters, by providing the backstage.io/kubernetes-cluster annotation with the defined cluster name.

If you do not specify the annotation then by default it fetches all defined kubernetes clusters.

To apply, update your catalog-info.yamlas follows:

 metadata:
   annotations:
     'backstage.io/kubernetes-id': dice-roller
     'backstage.io/kubernetes-namespace': dice-space
+    'backstage.io/kubernetes-cluster': dice-cluster
     'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'

Contributed by @deepan10 in #20954

BREAKING: Repo tools generated API Reports path changes

API Reports generated for sub-path exports now place the name as a suffix rather than prefix, for example api-report-alpha.md instead of alpha-api-report.md. When upgrading to this version you'll need to re-create any such API reports and delete the old ones.

PagerDuty plugin changes home 🏡

The PagerDuty plugin has been marked as deprecated in favor of pagerduty/backstage-plugin which is maintained by PagerDuty themselves! We encourage you to migrate to @pagerduty/backstage-plugin in order to receive future updates.

Congrats to the PagerDuty folks for taking ownership of the plugin 👏

Contributed by @t1agob in #21436

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 and Plugins

Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.