docs/releases/v1.48.0-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.48.0
f1d29b4: Added support for extension point factories. This makes it possible to call registerExtensionPoint with a single options argument and provide a factory for the extension point rather than a direct implementation. The factory is passed a context with a reportModuleStartupFailure method that makes it possible for plugins to report and attribute startup errors to the module that consumed the extension point.
bb9b471: Plugin IDs that do not match the standard format are deprecated (letters, digits, and dashes only, starting with a letter). Plugin IDs that do no match this format will be rejected in a future release.
In addition, plugin IDs that don't match the legacy pattern that also allows underscores, with be rejected.
createServiceMock, a public utility for creating ServiceMock instances for custom service refs. This allows plugin authors to define mock creators for their own services following the same pattern as the built-in mockServices mocks.startTestBackend to support factory-based extension points (v1.1 format) in addition to the existing direct implementation format.@types/jest as an optional peer dependency, since jest types are exposed in the public API surface.queryLocations and streamLocations that allow paginated/streamed and filtered location queriesInMemoryCatalogClient test utility to support ordering, pagination, full-text search, and field projection for entity query methods. Also fixed getEntityFacets to correctly handle multi-valued fields.@backstage/plugin-catalog-react/alpha7edb810: Implemented support for the internal extension input option.
492503a: Updated error reporting and app tree resolution logic to attribute errors to the correct extension and allow app startup to proceed more optimistically:
ef6916e: Added IconElement type as a replacement for the deprecated IconComponent. The IconsApi now has a new icon() method that returns IconElement, while the existing getIcon() method is deprecated. The IconBundleBlueprint now accepts both IconComponent and IconElement values.
122d39c: Completely removed support for the deprecated app.experimental.packages configuration. Replace existing usage directly with app.packages.
9554c36: DEPRECATED: Deprecated support for multiple attachment points.
53b6549: Plugins in the new frontend system now have a pluginId field rather than id to better align with naming conventions used throughout the frontend and backend systems. The old field is still present but marked as deprecated. All internal code has been updated to prefer pluginId while maintaining backward compatibility by falling back to id when needed.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
09032d7: Internal update to simplify testing utility implementations.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
API_FACTORY_CONFLICT warning is now treated as an error and will prevent the app from starting.app.experimental.packages configuration. Replace existing usage directly with app.packages.pluginId field rather than id to better align with naming conventions used throughout the frontend and backend systems. The old field is still present but marked as deprecated. All internal code has been updated to prefer pluginId while maintaining backward compatibility by falling back to id when needed.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.ef6916e: Added IconElement type as a replacement for the deprecated IconComponent. The IconsApi now has a new icon() method that returns IconElement, while the existing getIcon() method is deprecated. The IconBundleBlueprint now accepts both IconComponent and IconElement values.
bb9b471: Plugin IDs that do not match the standard format are deprecated (letters, digits, and dashes only, starting with a letter). Plugin IDs that do no match this format will be rejected in a future release.
ef6916e: Added SubPageBlueprint for creating sub-page tabs, PluginHeaderActionBlueprint and PluginHeaderActionsApi for plugin-scoped header actions, and PageLayout as a swappable component. The PageBlueprint now supports sub-pages with tabbed navigation, page title, icon, and header actions. Plugins can now specify a title and icon in createFrontendPlugin.
c38b74d: BREAKING: The following blueprints have been removed and are now only available from @backstage/plugin-app-react:
IconBundleBlueprintNavContentBlueprintRouterBlueprintSignInPageBlueprintSwappableComponentBlueprintThemeBlueprintTranslationBlueprint10ebed4: BREAKING: Removed type support for multiple attachment points in the ExtensionDefinitionAttachTo type. Extensions can no longer specify an array of attachment points in the attachTo property.
The runtime still supports multiple attachment points for backward compatibility with existing compiled code, but new code will receive type errors if attempting to use this pattern.
Extensions that previously used multiple attachment points should migrate to using a Utility API pattern instead. See the Sharing Extensions Across Multiple Locations guide for the recommended approach.
7edb810: Added a new internal option to createExtensionInput that marks the input as only allowing attachments from the same plugin.
9554c36: DEPRECATED: Multiple attachment points for extensions have been deprecated. The functionality continues to work for backward compatibility, but will log a deprecation warning and be removed in a future release.
Extensions using array attachment points should migrate to using Utility APIs instead. See the Sharing Extensions Across Multiple Locations guide for the recommended pattern.
53b6549: Plugins in the new frontend system now have a pluginId field rather than id to better align with naming conventions used throughout the frontend and backend systems. The old field is still present but marked as deprecated. All internal code has been updated to prefer pluginId while maintaining backward compatibility by falling back to id when needed.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
09a6aad: BREAKING: Removed the TestApiRegistry class, use TestApiProvider directly instead, storing reused APIs in a variable, e.g. const apis = [...] as const.
d2ac2ec: Added MockAlertApi and MockFeatureFlagsApi implementations to the mockApis namespace. The mock implementations include useful testing methods like clearAlerts(), waitForAlert(), getState(), setState(), and clearState() for better test ergonomics.
09a6aad: BREAKING: The mockApis namespace is no longer a re-export from @backstage/test-utils. It's now a standalone namespace with mock implementations of most core APIs. Mock API instances can be passed directly to TestApiProvider, renderInTestApp, and renderTestApp without needing [apiRef, impl] tuples. As part of this change, the .factory() method on some mocks has been removed, since it's now redundant.
// Before
import { mockApis } from '@backstage/frontend-test-utils';
renderInTestApp(<MyComponent />, {
apis: [[identityApiRef, mockApis.identity()]],
});
// After - mock APIs can be passed directly
renderInTestApp(<MyComponent />, {
apis: [mockApis.identity()],
});
This change also adds createApiMock, a public utility for creating mock API factories, intended for plugin authors to create their own .mock() variants.
22864b7: Added an apis option to createExtensionTester, renderInTestApp, and renderTestApp to override APIs when testing extensions. Use the mockApis helpers to create mock implementations:
import { identityApiRef } from '@backstage/frontend-plugin-api';
import { mockApis } from '@backstage/frontend-test-utils';
// Override APIs in createExtensionTester
const tester = createExtensionTester(myExtension, {
apis: [
[
identityApiRef,
mockApis.identity({ userEntityRef: 'user:default/guest' }),
],
],
});
// Override APIs in renderInTestApp
renderInTestApp(<MyComponent />, {
apis: [
[
identityApiRef,
mockApis.identity({ userEntityRef: 'user:default/guest' }),
],
],
});
// Override APIs in renderTestApp
renderTestApp({
extensions: [myExtension],
apis: [
[
identityApiRef,
mockApis.identity({ userEntityRef: 'user:default/guest' }),
],
],
});
15ed3f9: Added snapshot() method to ExtensionTester, which returns a tree-shaped representation of the resolved extension hierarchy. Convenient to use with toMatchInlineSnapshot().
013ec22: Added mountedRoutes option to renderTestApp for binding route refs to paths, matching the existing option in renderInTestApp:
renderTestApp({
extensions: [...],
mountedRoutes: {
'/my-path': myRouteRef,
},
});
d7dd5bd: Fixed Router deprecation warning and switched to using new RouterBlueprint from @backstage/plugin-app-api.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
{org}.visualstudio.com domains used by Azure DevOps@backstage/module-federation-common package that provides shared types, default configurations, and runtime utilities for module federation. It includes loadModuleFederationHostShared for loading shared dependencies in parallel at runtime, defaultHostSharedDependencies and defaultRemoteSharedDependencies for consistent dependency configuration, and types such as HostSharedDependencies, RemoteSharedDependencies, and RuntimeSharedDependenciesGlobal.46a9adc: BREAKING: Alert no longer accepts a surface prop
The Alert component's background is now driven entirely by its status prop. The surface prop has been removed.
- <Alert surface="1" status="info" />
+ <Alert status="info" />
Affected components: Alert
b63c25b: BREAKING: Removed gray scale tokens and renamed background surface tokens to neutral tokens
The --bui-gray-1 through --bui-gray-8 tokens have been removed. The --bui-bg-surface-* and --bui-bg-neutral-on-surface-* tokens have been replaced by a unified --bui-bg-neutral-* scale.
Migration:
Replace surface tokens directly:
- background: var(--bui-bg-surface-0);
+ background: var(--bui-bg-neutral-0);
Replace on-surface tokens shifted by +1:
- background: var(--bui-bg-neutral-on-surface-0);
+ background: var(--bui-bg-neutral-1);
Replace gray tokens 1-4 with neutral equivalents (--bui-gray-5 through --bui-gray-8 have no direct replacement):
- background: var(--bui-gray-1);
+ background: var(--bui-bg-neutral-1);
7898df0: BREAKING: Replaced Surface / onSurface system with new provider/consumer background system
The old Surface type ('0'–'3', 'auto') and its associated props (surface, onSurface) have been replaced by a provider/consumer bg architecture.
Types:
ContainerBg — 'neutral-1' | 'neutral-2' | 'neutral-3' | 'danger' | 'warning' | 'success'ProviderBg — ContainerBg | 'neutral-auto'Consumer components (e.g. Button) inherit the parent's bg via data-on-bg, and CSS handles the visual step-up. See "Neutral level capping" below for details on how levels are bounded.
Hooks:
useBgProvider(bg?) — for provider components. Returns { bg: undefined } when no bg is given (transparent). Supports 'neutral-auto' to auto-increment from the parent context.useBgConsumer() — for consumer components. Returns the parent container's bg unchanged.Component roles:
data-bg, wrap children in BgProvider. Transparent by default — they do not auto-increment; pass bg="neutral-auto" explicitly if you want automatic neutral stepping.data-on-bg, inherit the parent container's bg unchanged.data-bg and data-on-bg, wraps children. Card passes bg="neutral-auto" to its inner Box, so it auto-increments from the parent context.Neutral level capping:
Provider components cap at neutral-3. There is no neutral-4 prop value. The neutral-4 level exists only in consumer component CSS — for example, a Button sitting on a neutral-3 surface uses neutral-4 tokens internally via data-on-bg.
Migration:
Rename the surface prop to bg on provider components and update values:
- <Box surface="1">
+ <Box bg="neutral-1">
- <Card surface="2">
+ <Card bg="neutral-2">
- <Flex surface="0">
+ <Flex bg="neutral-1">
- <Grid.Root surface="1">
+ <Grid.Root bg="neutral-1">
Remove onSurface from consumer components — they now always inherit from the parent container:
- <Button onSurface="1" variant="secondary">
+ <Button variant="secondary">
- <ButtonIcon onSurface="2" variant="secondary" />
+ <ButtonIcon variant="secondary" />
- <ToggleButton onSurface="1">
+ <ToggleButton>
Update type imports:
- import type { Surface, LeafSurfaceProps, ContainerSurfaceProps } from '@backstage/ui';
+ import type { ContainerBg, ProviderBg } from '@backstage/ui';
Replace hook usage in custom components:
- import { useSurface, SurfaceProvider } from '@backstage/ui';
+ import { useBgProvider, useBgConsumer, BgProvider } from '@backstage/ui';
- const { surface } = useSurface({ surface: props.surface });
+ const { bg } = useBgProvider(props.bg);
- const { surface } = useSurface({ onSurface: props.onSurface });
+ const { bg } = useBgConsumer();
Update CSS selectors targeting surface data attributes:
- [data-surface='1'] { ... }
+ [data-bg='neutral-1'] { ... }
- [data-on-surface='1'] { ... }
+ [data-on-bg='neutral-1'] { ... }
Note: Provider components use data-bg (values: neutral-1 through neutral-3, plus intent values). Consumer components use data-on-bg, which reflects the parent container's bg directly. The neutral-4 level never appears as a prop or data-bg value — it is used only in consumer CSS.
Affected components: Box, Button, ButtonIcon, ButtonLink, ToggleButton, Card, Flex, Grid
4137a43: BREAKING: Renamed, added, and removed CSS tokens.
--bui-bg-neutral-0 to --bui-bg-app.--bui-border to --bui-border-2.--bui-border-1 for subtle, low-contrast borders.--bui-bg-popover for the background color of popovers, tooltips, menus, and dialogs.--bui-border-hover, --bui-border-pressed, and --bui-border-disabled.Migration:
- var(--bui-bg-neutral-0)
+ var(--bui-bg-app)
- var(--bui-border)
+ var(--bui-border-2)
Remove any references to --bui-border-hover, --bui-border-pressed, and --bui-border-disabled as these tokens no longer exist.
b1f723b: BREAKING: Changed CSS selectors for ButtonIcon and ButtonLink components. Custom styles targeting .bui-Button to style these components must be updated to use .bui-ButtonIcon or .bui-ButtonLink respectively.
-/* This no longer styles ButtonIcon or ButtonLink */
-.bui-Button[data-variant="primary"] { ... }
+/* Use component-specific selectors */
+.bui-ButtonIcon[data-variant="primary"] { ... }
+.bui-ButtonLink[data-variant="primary"] { ... }
Affected components: ButtonIcon, ButtonLink
caeb9ad: BREAKING: The cell and header properties in ColumnConfig now return ReactElement instead of ReactNode.
This fixes an issue where React Aria's Collection component would inject an id prop into Fragment wrappers, causing "Invalid prop id supplied to React.Fragment" errors on render.
Migration:
const columns: ColumnConfig<MyItem>[] = [
{
id: 'name',
label: 'Name',
- cell: (item) => item.name,
+ cell: (item) => <CellText title={item.name} />,
- header: () => 'Name',
+ header: () => <Column>Name</Column>,
},
];
0ec3c0e: BREAKING: Renamed the Header component to PluginHeader for clarity.
The following exports have been renamed:
Header → PluginHeaderHeaderProps → PluginHeaderPropsHeaderDefinition → PluginHeaderDefinitionThe HeaderTab type is unchanged as it is shared with HeaderPage.
CSS class names have been updated from bui-Header* to bui-PluginHeader*.
Migration:
-import { Header, HeaderDefinition } from '@backstage/ui';
+import { PluginHeader, PluginHeaderDefinition } from '@backstage/ui';
-<Header title="My plugin" />
+<PluginHeader title="My plugin" />
Affected components: plugin-header
058ffd9: BREAKING: Removed large size variant from Button component as it was never implemented.
Migration:
- <Button size="large">Click me</Button>
+ <Button size="medium">Click me</Button>
Affected components: Button
110fec0: BREAKING: Removed link and tint color tokens, added new status foreground tokens, and improved Link component styling
The following color tokens have been removed:
--bui-fg-link (and all related tokens: -hover, -pressed, -disabled)--bui-fg-tint (and all related tokens: -hover, -pressed, -disabled)--bui-bg-tint (and all related tokens: -hover, -pressed, -disabled)--bui-border-tint (and all related tokens)New Status Tokens:
Added dedicated tokens for status colors that distinguish between usage on status backgrounds vs. standalone usage:
--bui-fg-danger-on-bg / --bui-fg-danger--bui-fg-warning-on-bg / --bui-fg-warning--bui-fg-success-on-bg / --bui-fg-success--bui-fg-info-on-bg / --bui-fg-infoThe -on-bg variants are designed for text on colored backgrounds, while the base variants are for standalone status indicators with improved visibility and contrast.
Migration:
For link colors, migrate to one of the following alternatives:
.custom-link {
- color: var(--bui-fg-link);
+ color: var(--bui-fg-info); /* For informational links */
+ /* or */
+ color: var(--bui-fg-primary); /* For standard text links */
}
For tint colors (backgrounds, foregrounds, borders), migrate to appropriate status or neutral colors:
.info-section {
- background: var(--bui-bg-tint);
+ background: var(--bui-bg-info); /* For informational sections */
+ /* or */
+ background: var(--bui-bg-neutral-1); /* For neutral emphasis */
}
If you're using status foreground colors on colored backgrounds, update to the new -on-bg tokens:
.error-badge {
- color: var(--bui-fg-danger);
+ color: var(--bui-fg-danger-on-bg);
background: var(--bui-bg-danger);
}
Affected components: Link
644e303: Added a new FullPage component that fills the remaining viewport height below the PluginHeader.
<PluginHeader title="My Plugin" tabs={tabs} />
<FullPage>
</FullPage>
Affected components: FullPage
44877e4: Fixed dark theme --bui-fg-secondary and --bui-fg-disabled tokens using black-based oklch(0% ...) instead of white-based oklch(100% ...), making secondary and disabled text visible on dark backgrounds.
350c948: Fixed Box component to forward HTML attributes to the underlying div element.
Affected components: Box
7455dae: Use node prefix on native imports
c8ae765: Fixed nested Accordion icon state issue where the inner accordion's arrow icon would incorrectly show as expanded when only the outer accordion was expanded. The CSS selector now uses a direct parent selector to ensure the icon only responds to its own accordion's expanded state.
Affected components: Accordion
4d1b7f4: Fixed CSS Module syntax to comply with Next.js 16 Turbopack validation by flattening nested dark theme selectors.
Affected components: Popover, Tooltip
2c219b9: Added destructive prop to Button for dangerous actions like delete or remove. Works with all variants (primary, secondary, tertiary).
Affected components: Button
5af9e14: Fixed useDefinition hook adding literal "undefined" class name when no className prop was passed.
5c76d13: Allow ref as a prop on the Tag component
Affected components: Tag
ab25658: Cleaned up useDefinition ownProps types to remove never-typed ghost properties from autocomplete.
741a98d: Allow data to be passed directly to the useTable hook using the property data instead of getData() for mode "complete".
This simplifies usage as data changes, rather than having to perform a useEffect when data changes, and then reloading the data. It also happens immediately, so stale data won't remain until a rerender (with an internal async state change), so less flickering.
Affected components: Table
a0fe1b2: Fixed changing columns after first render from crashing. It now renders the table with the new column layout as columns change.
Affected components: Table
508bd1a: Added new Alert component with support for status variants (info, success, warning, danger), icons, loading states, and custom actions.
Updated status color tokens for improved contrast and consistency across light and dark themes:
--bui-bg-info and --bui-fg-info tokens for info status--bui-bg-danger, --bui-fg-danger tokens--bui-bg-warning, --bui-fg-warning tokens--bui-bg-success, --bui-fg-success tokensAffected components: Alert
da30862: Fixed client-side navigation for container components by wrapping the container (not individual items) in RouterProvider. Components now conditionally provide routing context only when children have internal links, removing the Router context requirement when not needed. This also removes the need to wrap these components in MemoryRouter during tests when they are not using the href prop.
Additionally, when multiple tabs match the current URL via prefix matching, the tab with the most specific path (highest segment count) is now selected. For example, with URL /catalog/users/john, a tab with path /catalog/users is now selected over a tab with path /catalog.
Affected components: Tabs, Tab, TagGroup, Tag, Menu, MenuItem, MenuAutocomplete
092c453: Fixed an infinite render loop in Tabs when navigating to a URL that doesn't match any tab href.
becf851: export PasswordField component
becee36: Migrated Accordion components to use useDefinition instead of useStyles, and added automatic background adaptation based on parent container context.
5320aa8: Fixed components to not require a Router context when rendering without internal links.
Affected components: Link, ButtonLink, Row
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
8c39412: The Table component now wraps the react-aria-components Table with a ResizableTableContainer only if any column has a width property set. This means that column widths can adapt to the content otherwise (if no width is explicitly set).
Affected components: Table
cb090b4: Bump react-aria-components to v1.14.0
c429101: Fixed React 17 compatibility by using useId from react-aria instead of the built-in React hook which is only available in React 18+.
74c5a76: Fixed Switch component disabled state styling to show not-allowed cursor and disabled text color.
Affected components: Switch
20131c5: Migrated to use the standard backstage-cli package build for CSS bundling instead of a custom build script.
Updated dependencies
ef6916e: Added SubPageBlueprint for creating sub-page tabs, PluginHeaderActionBlueprint and PluginHeaderActionsApi for plugin-scoped header actions, and PageLayout as a swappable component. The PageBlueprint now supports sub-pages with tabbed navigation, page title, icon, and header actions. Plugins can now specify a title and icon in createFrontendPlugin.
7edb810: BREAKING: Extensions created with the following blueprints must now be provided via an override or a module for the app plugin. Extensions from other plugins will now trigger a warning in the app and be ignored.
IconBundleBlueprintNavContentBlueprintRouterBlueprintSignInPageBlueprintSwappableComponentBlueprintThemeBlueprintTranslationBlueprintNavContentNavItem, NavContentNavItems, and navItems prop to NavContentComponentProps for auto-discovering navigation items from page extensions. The new navItems collection supports take(id) and rest() methods for placing specific items in custom sidebar positions, as well as withComponent(Component) which returns a NavContentNavItemsWithComponent for rendering items directly as elements. The existing items prop is now deprecated in favor of navItems.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.NavContentNavItem, NavContentNavItems, and navItems prop to NavContentComponentProps for auto-discovering navigation items from page extensions. The new navItems collection supports take(id) and rest() methods for placing specific items in custom sidebar positions, as well as withComponent(Component) which returns a NavContentNavItemsWithComponent for rendering items directly as elements. The existing items prop is now deprecated in favor of navItems.IconElement type as a replacement for the deprecated IconComponent. The IconsApi now has a new icon() method that returns IconElement, while the existing getIcon() method is deprecated. The IconBundleBlueprint now accepts both IconComponent and IconElement values.@backstage/frontend-plugin-api to this package.SubPageBlueprint for tabbed navigation and added a copy-tree-as-JSON plugin header action using PluginHeaderActionBlueprint. The plugin now specifies a title and icon.@backstage/plugin-app-react.--bui-border-2 token.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.31de2c9: Added experimental support for Client ID Metadata Documents (CIMD).
This allows Backstage to act as an OAuth 2.0 authorization server that supports the IETF Client ID Metadata Document draft. External OAuth clients can use HTTPS URLs as their client_id, and Backstage will fetch metadata from those URLs to validate the client.
Configuration example:
auth:
experimentalClientIdMetadataDocuments:
enabled: true
# Optional: restrict which `client_id` URLs are allowed (defaults to ['*'])
allowedClientIdPatterns:
- 'https://example.com/*'
- 'https://*.trusted-domain.com/*'
# Optional: restrict which redirect URIs are allowed (defaults to ['*'])
allowedRedirectUriPatterns:
- 'http://localhost:*'
- 'https://*.example.com/*'
Clients using CIMD must host a JSON metadata document at their client_id URL containing at minimum:
{
"client_id": "https://example.com/.well-known/oauth-client/my-app",
"client_name": "My Application",
"redirect_uris": ["http://localhost:8080/callback"],
"token_endpoint_auth_method": "none"
}
d0786b9: Added experimental support for refresh tokens via the auth.experimentalRefreshToken.enabled configuration option. When enabled, clients can request the offline_access scope to receive refresh tokens that can be used to obtain new access tokens without re-authentication.
userIdMatchingUserEntityAnnotation sign-in resolver that matches users by their GitHub user ID.{gitlab-integration-host}/user-id annotation to store GitLab's user ID (immutable) in user entities. Also includes addition of the userIdMatchingUserEntityAnnotation sign-in resolver that matches users by the new ID.491a06c: Add the ability to show icons for the tabs on the entity page (new frontend)
05aac34: Migrated DeleteEntityDialog and EntityOrphanWarning components to Backstage UI.
The deleteEntity.description translation key no longer includes "Click here to delete" text. A new deleteEntity.actionButtonTitle key was added for the action button.
220d6c3: Add missing translation entries for catalog UI text.
This change adds translation keys and updates relevant UI components to use the correct localized labels and text in the catalog plugin. It ensures that catalog screens such as entity layout, tabs, search result items, table labels, and other UI elements correctly reference the i18n system for translation.
No functional behavior is changed aside from the improved internationalization support.
8d4c48b: Fixed vertical spacing between tags in the catalog table.
7feb83b: Adjusted to use the new @backstage/filter-predicates types for predicate expressions.
018ca87: Added title and icon to the plugin definition for the new frontend system.
e8258d0: The default entity content layout still supports rendering summary cards at runtime for backward compatibility, but logs a console warning when they are detected to help identify where migration is needed.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
75ac651: Migrated EntityRelationWarning and EntityProcessingErrorsPanel components from Material UI to Backstage UI.
Updated dependencies
f1d29b4: Failures to connect catalog providers are now attributed to the module that provided the failing provider. This means that such failures will be reported as module startup failures rather than a failure to start the catalog plugin, and will therefore respect onPluginModuleBootFailure configuration instead.
34cc520: Implemented handling of events from the newly introduced alpha
catalogScmEventsServiceRef service, in the builtin entity providers. This
allows entities to get refreshed, and locations updated or removed, as a
response to incoming events. In its first iteration, only the GitHub module
implements such event handling however.
This is not yet enabled by default, but this fact may change in a future release. To try it out, ensure that you have the latest catalog GitHub module installed, and set the following in your app-config:
catalog:
scmEvents: true
Or if you want to pick and choose from the various features:
catalog:
scmEvents:
# refresh (reprocess) upon events?
refresh: true
# automatically unregister locations based on events? (files deleted, repos archived, etc)
unregister: true
# automatically move locations based on events? (repo transferred, file renamed, etc)
move: true
b4e8249: Implemented the POST /locations/by-query endpoint which allows paginated, filtered location queries
@backstage/plugin-catalog-node instead of the deprecated alpha exports.peerModules metadata declaring recommended modules for cross-plugin integrations.buildEntitySearch traverse() by replacing Array.some() linear scan with a Set for O(1) duplicate path key detection.{gitlab-integration-host}/user-id annotation to store GitLab's user ID (immutable) in user entities. Also includes addition of the userIdMatchingUserEntityAnnotation sign-in resolver that matches users by the new ID.@backstage/plugin-catalog-node instead of the deprecated alpha exports.'blob' to 'blobs', resolving 400 errors in discovery provider.@backstage/plugin-catalog-node instead of the deprecated alpha exports.cfd8103: Promoted stable catalog extension points from alpha to main export. The following extension points are now exported from @backstage/plugin-catalog-node instead of @backstage/plugin-catalog-node/alpha:
catalogLocationsExtensionPoint and CatalogLocationsExtensionPointcatalogProcessingExtensionPoint and CatalogProcessingExtensionPointcatalogAnalysisExtensionPoint and CatalogAnalysisExtensionPointThe old alpha exports for these extension points are now deprecated with @deprecated markers pointing to the new stable exports. Please update your imports from @backstage/plugin-catalog-node/alpha to @backstage/plugin-catalog-node.
Note: The catalogModelExtensionPoint, catalogPermissionExtensionPoint, and related types remain in alpha.
b4e8249: Implemented support for the new queryLocations and streamLocations that allow paginated/streamed and filtered location queries
34cc520: Introduced the catalogScmEventsServiceRef, along with CatalogScmEventsService and associated types. These allow communicating a unified set of events, that parts of the catalog can react to.
catalogServiceMock.mock to use createServiceMock from @backstage/backend-test-utils, replacing the internal copy of simpleMock. Added @backstage/backend-test-utils as an optional peer dependency.0e9578d: Migrated UnregisterEntityDialog from Material UI to Backstage UI components.
491a06c: Add the ability to show icons for the tabs on the entity page (new frontend)
b4e8249: Implemented support for the new queryLocations and streamLocations that allow paginated/streamed and filtered location queries
7feb83b: BREAKING ALPHA: All of the predicate types and functions have been moved to the @backstage/filter-predicates package.
When moving into the more general package, they were renamed as follows:
EntityPredicate -> FilterPredicateEntityPredicateExpression -> FilterPredicateExpressionEntityPredicatePrimitive -> FilterPredicatePrimitiveentityPredicateToFilterFunction -> filterPredicateToFilterFunctionEntityPredicateValue -> FilterPredicateValuee8258d0: BREAKING: Removed the 'summary' entity card type from EntityCardType. Users should migrate to using 'content' or 'info' card types instead.
TypeScript will now show errors if you try to use type: 'summary' when creating entity cards.
ac9bead: Added createTestEntityPage test utility for testing entity cards and content extensions in the new frontend system. This utility creates a test page extension that provides EntityProvider context and accepts entity extensions through input redirects:
import { renderTestApp } from '@backstage/frontend-test-utils';
import { createTestEntityPage } from '@backstage/plugin-catalog-react/testUtils';
renderTestApp({
extensions: [createTestEntityPage({ entity: myEntity }), myEntityCard],
});
EntityListProvider would not correctly hydrate query parameters if more than 20 were provided for the same key.catalogApiMock test utility now returns a MockWithApiFactory, allowing it to be passed directly to test utilities like renderTestApp and TestApiProvider without needing the [catalogApiRef, catalogApiMock()] tuple.UserListPicker by getting the kindParamater from the filters rather than from the queryParametersreact-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.filter property to PubSub consumers/publisherssearch.defaultType option in app-config.yaml. This applies to both the legacy and new frontend systems. If not set, the default is empty, which means searching for "all" types.title and icon to the plugin definition for the new frontend system.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.elasticsearchAuthExtensionPoint to enable dynamic authentication mechanisms such as bearer tokens with automatic rotation.27798df: Add two config values to the page:techdocs/reader extension that configure default layout, withoutSearch and withoutHeader. Default are unchanged to false.
E.g. to disable the search and header on the Techdocs Reader Page:
app:
extensions:
- page:techdocs/reader:
config:
withoutSearch: true
withoutHeader: true
@backstage/filter-predicates types for predicate expressions.title and icon to the plugin definition for the new frontend system.AddonBlueprint now uses this new approach, and while addons created with older versions still work, they will produce a deprecation warning and will stop working in a future release.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.title and icon to the plugin definition for the new frontend system.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@backstage/backend-defaults from dependencies to devDependencies.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.createRateLimitMiddleware is now exported from @backstage/backend-defaults/httpRouterconnection.type: azure in database client to use Microsoft Entra authentication with Azure database for PostgreSQL@module-federation/enhanced, @module-federation/runtime, and @module-federation/sdk dependencies from ^0.9.0 to ^0.21.6.cfd8103: Updated catalog provider module template to use stable catalog extension points from @backstage/plugin-catalog-node instead of alpha exports.
20131c5: Added support for CSS exports in package builds. When a package declares a CSS file in its exports field (e.g., "./styles.css": "./src/styles.css"), the CLI will automatically bundle it during backstage-cli package build, resolving any @import statements. The export path is rewritten from src/ to dist/ at publish time.
Fixed backstage-cli repo fix to not add typesVersions entries for non-script exports like CSS files.
7455dae: Use node prefix on native imports
6ce4a13: Removed /alpha from scaffolderActionsExtensionPoint import
fdbd404: Removed the EXPERIMENTAL_MODULE_FEDERATION environment variable flag, making module federation host support always available during package start. The host shared dependencies are now managed through @backstage/module-federation-common and injected as a versioned runtime script at build time.
fdbd404: Updated @module-federation/enhanced, @module-federation/runtime, and @module-federation/sdk dependencies from ^0.9.0 to ^0.21.6.
4fc7bf0: Bump to tar v7
5e3ef57: Added support for the new peerModules metadata field in package.json. This field allows plugin packages to declare modules that should be installed alongside them for cross-plugin integrations. The field is validated by backstage-cli repo fix --publish.
122d39c: Completely removed support for the deprecated app.experimental.packages configuration. Replace existing usage directly with app.packages.
73351c2: Updated dependency webpack to ~5.104.0.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
peerModules metadata field in package.json. This field allows plugin packages to declare modules that should be installed alongside them for cross-plugin integrations. The field is validated by backstage-cli repo fix --publish.AppThemeSelector instances and missing cleanup in AppThemeSelector and AppLanguageSelector. Added dispose() method to both selectors for proper resource cleanup.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@backstage/plugin-app-react.IconElement type as a replacement for the deprecated IconComponent. The IconsApi now has a new icon() method that returns IconElement, while the existing getIcon() method is deprecated. The IconBundleBlueprint now accepts both IconComponent and IconElement values.pluginId field rather than id to better align with naming conventions used throughout the frontend and backend systems. The old field is still present but marked as deprecated. All internal code has been updated to prefer pluginId while maintaining backward compatibility by falling back to id when needed.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.pluginId field rather than id to better align with naming conventions used throughout the frontend and backend systems. The old field is still present but marked as deprecated. All internal code has been updated to prefer pluginId while maintaining backward compatibility by falling back to id when needed.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.--next flag. Also updated react-router* versions and added Jest 30-related dependencies. Finally, moved the order of @playwright/test so it won't trigger a file change during the creation process.NavContentBlueprint API for page-based navigation.next-app template to use blueprint from @backstage/plugin-app-react.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.b96c20e: Added optional channel option to generateProjects() to allow customizing the Playwright browser channel for testing against different browsers variants. When not provided, the function defaults to 'chrome' to maintain backward compatibility.
Example usage:
import { generateProjects } from '@backstage/e2e-test-utils';
export default defineConfig({
projects: generateProjects({ channel: 'msedge' }),
});
7455dae: Use node prefix on native imports
@module-federation/enhanced/runtime createInstance API and the new loadModuleFederationHostShared from @backstage/module-federation-common for loading shared dependencies. Also added support for passing a pre-created ModuleFederation instance via the moduleFederation.instance option.@module-federation/enhanced, @module-federation/runtime, and @module-federation/sdk dependencies from ^0.9.0 to ^0.21.6.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.type-deps command now follows relative imports and re-exports into declaration chunk files, and detects ambient global types such as the jest namespace.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.find-process to ^2.0.0.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@types/jest as an optional peer dependency, since jest types are exposed in the public API surface.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@backstage/frontend-test-utils dev dependency.@backstage/filter-predicates types for predicate expressions.title and icon to the plugin definition for the new frontend system.tableOptions and title to Components cards of APIsreact-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.audience configuration values that are not absolute URLs (i.e. missing https:// or http:// prefix).react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@backstage/plugin-catalog-node instead of the deprecated alpha exports.{org}.visualstudio.com domains used by Azure DevOps@backstage/plugin-catalog-node instead of the deprecated alpha exports.branch field to the azureDevOps provider config schema.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.catalogScmEventsServiceRef events.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/plugin-catalog-node instead of the deprecated alpha exports.@backstage/frontend-test-utils dev dependency.@backstage/filter-predicates types for predicate expressions.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.title and icon to the plugin definition for the new frontend system.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.title and icon to the plugin definition for the new frontend system.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@backstage/backend-defaults from dependencies to devDependencies.@testing-library/react to ^16.0.0.title and icon to the plugin definition for the new frontend system.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@backstage/filter-predicates types for predicate expressions.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.@xterm/addon-attach to ^0.12.0.
Updated dependency @xterm/addon-fit to ^0.11.0.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.31de2c9: Added OAuth Protected Resource Metadata endpoint (/.well-known/oauth-protected-resource) per RFC 9728. This allows MCP clients to discover the authorization server for the resource.
Also enabled OAuth well-known endpoints when CIMD (Client ID Metadata Documents) is configured, not just when DCR is enabled.
8148621: Moved @backstage/backend-defaults from dependencies to devDependencies.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
4137a43: Updated CSS token references to use renamed --bui-bg-app and --bui-border-2 tokens.
a88c437: Updated MUI to BUI theme converter to align with latest token changes
Changes:
--bui-fg-link, --bui-fg-link-hover, --bui-fg-tint, --bui-fg-tint-disabled, --bui-bg-tint and all its variantsinfo status tokens: --bui-fg-info, --bui-fg-info-on-bg, --bui-bg-info, --bui-border-info-on-bg variants for danger, warning, success, and info.main for standalone variants and .dark for -on-bg variants, providing better visual hierarchyThe converter now generates tokens that match the updated BUI design system structure, with clear distinction between status colors for standalone use vs. use on colored backgrounds.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
Updated dependencies
renderItem prop to NotificationsSidebarItem component, allowing custom UI rendering while retaining all built-in notification logic (unread count, snackbar, signals, web notifications).react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.peerModules metadata declaring recommended modules for cross-plugin integrations.@backstage/frontend-test-utils dev dependency.@backstage/filter-predicates types for predicate expressions.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.7455dae: Use node prefix on native imports
4e581a6: Updated the browser tab title on the template wizard page to display the specific template title instead of the generic "Create a new component" text.
7feb83b: Adjusted to use the new @backstage/filter-predicates types for predicate expressions.
018ca87: Added title and icon to the plugin definition for the new frontend system.
2eeca03: Scaffolder form fields in the new frontend system now use a Utility API pattern instead of multiple attachment points. The FormFieldBlueprint now uses this new approach, and while form fields created with older versions still work, they will produce a deprecation warning and will stop working in a future release.
As part of this change, the following alpha exports were removed:
formFieldsApiRefScaffolderFormFieldsApib9d90a7: Added @backstage/frontend-test-utils as a dev dependency for mock API usage in tests.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
if conditions inside each loops for scaffolder stepspeerModules metadata declaring recommended modules for cross-plugin integrations.@backstage/backend-defaults from dependencies to devDependencies.libsodium-wrappers to ^0.8.0.
Updated dependency @types/libsodium-wrappers to ^0.8.0.gitlab:group:ensureExists action to use Groups.show API instead of Groups.search for checking if a group path exists. This is more efficient as it directly retrieves the group by path rather than searching and filtering results.gitlab:user:info scaffolder action that retrieves information about a GitLab user. The action can fetch either the current authenticated user or a specific user by ID.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.2eeca03: Scaffolder form fields in the new frontend system now use a Utility API pattern instead of multiple attachment points. The FormFieldBlueprint now uses this new approach, and while form fields created with older versions still work, they will produce a deprecation warning and will stop working in a future release.
As part of this change, the following alpha exports were removed:
formFieldsApiformFieldsApiRefScaffolderFormFieldsApib9d90a7: Added @backstage/frontend-test-utils as a dev dependency for mock API usage in tests.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
69d880e: Bump to latest zod to ensure it has the latest features
Updated dependencies
@backstage/backend-defaults from dependencies to devDependencies.@backstage-community/plugin-explore-common to ^0.12.0.numberOfResults count with search query responsesreact-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.peerModules metadata declaring recommended modules for cross-plugin integrations.@backstage/backend-defaults from dependencies to devDependencies.react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.22dce2b: TechDocs addons in the new frontend system now use a Utility API pattern instead of multiple attachment points. The AddonBlueprint now uses this new approach, and while addons created with older versions still work, they will produce a deprecation warning and will stop working in a future release.
As part of this change, the techDocsAddonDataRef alpha export was removed.
a7e0d50: Updated react-router-dom peer dependency to ^6.30.2 and explicitly disabled v7 future flags to suppress deprecation warnings.
Updated dependencies