Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@backstage/core-app-api

backstage339.8kApache-2.01.17.0TypeScript support: included

Core app API used by Backstage apps

backstage

readme

headline

Backstage

English | 한국어 | 中文版 | Français

License CNCF Status Discord Code style Codecov OpenSSF Best Practices OpenSSF Scorecard

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

software-catalog

Out of the box, Backstage includes:

  • Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
  • Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
  • Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
  • Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

Community

To engage with our community, you can use the following resources:

Governance

See the GOVERNANCE.md document in the backstage/community repository.

License

Copyright 2020-2025 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

changelog

@backstage/core-app-api

1.17.0

Minor Changes

  • 1e0230e: Support custom AuthConnector for OAuth2.

    A user can pass their own AuthConnector implementation in OAuth2 constructor. In which case the session manager will use that instead of the DefaultAuthConnector to interact with the authentication provider.

    A custom AuthConnector may call the authentication provider from the front-end, store and retrieve tokens in the session storage, for example, and otherwise send custom requests to the authentication provider and handle its responses.

    Note, that if the custom AuthConnector transforms scopes returned from the authentication provider, the transformation must be the same as OAuth2CreateOptions#scopeTransform passed to OAuth2 constructor. See creating DefaultAuthConnector in OAuth2#create(...) for an example.

Patch Changes

1.17.0-next.1

Minor Changes

  • 1e0230e: Support custom AuthConnector for OAuth2.

    A user can pass their own AuthConnector implementation in OAuth2 constructor. In which case the session manager will use that instead of the DefaultAuthConnector to interact with the authentication provider.

    A custom AuthConnector may call the authentication provider from the front-end, store and retrieve tokens in the session storage, for example, and otherwise send custom requests to the authentication provider and handle its responses.

    Note, that if the custom AuthConnector transforms scopes returned from the authentication provider, the transformation must be the same as OAuth2CreateOptions#scopeTransform passed to OAuth2 constructor. See creating DefaultAuthConnector in OAuth2#create(...) for an example.

Patch Changes

1.16.2-next.0

Patch Changes

1.16.1

Patch Changes

1.16.1-next.0

Patch Changes

1.16.0

Minor Changes

  • 9262001: The default auth injection middleware for the FetchApi will now also take configuration under discovery.endpoints into consideration when deciding whether to include credentials or not.
  • 12f8e01: The discovery.endpoints configuration no longer requires both internal and external target when using the object form, instead falling back to the default.

Patch Changes

1.16.0-next.0

Minor Changes

  • 9262001: The default auth injection middleware for the FetchApi will now also take configuration under discovery.endpoints into consideration when deciding whether to include credentials or not.
  • 12f8e01: The discovery.endpoints configuration no longer requires both internal and external target when using the object form, instead falling back to the default.

Patch Changes

1.15.5

Patch Changes

1.15.5-next.0

Patch Changes

1.15.4

Patch Changes

1.15.4-next.0

Patch Changes

1.15.3

Patch Changes

  • e5fa018: The OAuth 2 client implementations will now attempt to refresh the session when the existing session doesn't have the required scopes. The previous behavior was to only try to refresh the session of it was missing, and otherwise directly request a new session. This fixes an issue where some auth providers will not return access tokens with certain scopes unless explicitly requested, leading to an auth popup even if the underlying session already had been granted the requested scopes.
  • 2830689: Decrease OAuth2 token refresh grace period
  • Updated dependencies

1.15.3-next.1

Patch Changes

1.15.3-next.0

Patch Changes

  • e5fa018: The OAuth 2 client implementations will now attempt to refresh the session when the existing session doesn't have the required scopes. The previous behavior was to only try to refresh the session of it was missing, and otherwise directly request a new session. This fixes an issue where some auth providers will not return access tokens with certain scopes unless explicitly requested, leading to an auth popup even if the underlying session already had been granted the requested scopes.
  • 2830689: Decrease OAuth2 token refresh grace period
  • Updated dependencies

1.15.2

Patch Changes

1.15.1

Patch Changes

1.15.1-next.1

Patch Changes

1.15.1-next.0

Patch Changes

1.15.0

Minor Changes

  • ddbeace: Added the ability to explicitly disable routes through the bindRoutes option by passing false as the route target. This also fixes a bug where route bindings in config were incorrectly prioritized above the ones in code in certain situations.

Patch Changes

  • ea69e46: The defaultConfigLoader now also reads configuration from scripts tags with type="backstage.io/config". The tag is expected to contain a JSON-serialized array of AppConfig objects. If any of these script tags are present, the injected runtime configuration in the static assets will no longer be used.
  • b537bd7: Allow custom star icons to be provided via the star and unstarred icon overrides. See how to override existing icons in the Backstage documentation.
  • 836127c: Updated dependency @testing-library/react to ^16.0.0.
  • Updated dependencies

1.14.3-next.0

Patch Changes

1.14.2

Patch Changes

1.14.1-next.0

Patch Changes

1.14.0

Minor Changes

  • d3c39fc: Allow for the disabling of external routes through config, which was rendered impossible after the introduction of default targets.

    app:
  routes:
    bindings:
      # This has the effect of removing the button for registering new
      # catalog entities in the scaffolder template list view
      scaffolder.registerComponent: false

Patch Changes

1.13.1-next.1

Patch Changes

1.13.0-next.0

Minor Changes

  • d3c39fc: Allow for the disabling of external routes through config, which was rendered impossible after the introduction of default targets.

    app:
  routes:
    bindings:
      # This has the effect of removing the button for registering new
      # catalog entities in the scaffolder template list view
      scaffolder.registerComponent: false

Patch Changes

1.12.6

Patch Changes

  • 35fbe09: Added support for configuration of route bindings through static configuration, and default targets for external route refs.

    In addition to configuring route bindings through code, it is now also possible to configure route bindings under the app.routes.bindings key, for example:

    app:
  routes:
    bindings:
      catalog.createComponent: catalog-import.importPage

    Each key in the route binding object is of the form <plugin-id>.<externalRouteName>, where the route name is key used in the externalRoutes object passed to createPlugin. The value is of the same form, but with the name taken from the plugin routes option instead.

    The equivalent of the above configuration in code is the following:

    const app = createApp({
  // ...
  bindRoutes({ bind }) {
    bind(catalogPlugin.externalRoutes, {
      createComponent: catalogImportPlugin.routes.importPage,
    });
  },
});

  • Updated dependencies

1.12.6-next.0

Patch Changes

  • 35fbe09: Added support for configuration of route bindings through static configuration, and default targets for external route refs.

    In addition to configuring route bindings through code, it is now also possible to configure route bindings under the app.routes.bindings key, for example:

    app:
  routes:
    bindings:
      catalog.createComponent: catalog-import.importPage

    Each key in the route binding object is of the form <plugin-id>.<externalRouteName>, where the route name is key used in the externalRoutes object passed to createPlugin. The value is of the same form, but with the name taken from the plugin routes option instead.

    The equivalent of the above configuration in code is the following:

    const app = createApp({
  // ...
  bindRoutes({ bind }) {
    bind(catalogPlugin.externalRoutes, {
      createComponent: catalogImportPlugin.routes.importPage,
    });
  },
});

  • Updated dependencies

1.12.5

Patch Changes

  • 1bed9a3: The Backstage identity session expiration check will no longer fall back to using the provider expiration. This was introduced to smooth out the rollout of Backstage release 1.18, and is no longer needed.

1.12.4

Patch Changes

1.12.4-next.0

Patch Changes

1.12.3

Patch Changes

1.12.2

Patch Changes

1.12.1

Patch Changes

1.12.1-next.1

Patch Changes

1.12.1-next.0

Patch Changes

1.12.0

Minor Changes

  • f919be9: Added a utility API for VMware Cloud auth; the API ref is available in the @backstage/core-plugin-api and @backstage/frontend-plugin-api packages, the implementation is in @backstage/core-app-api and a factory has been added to @backstage/app-defaults.

Patch Changes

1.12.0-next.1

Minor Changes

  • f919be9: Added a utility API for VMware Cloud auth; the API ref is available in the @backstage/core-plugin-api and @backstage/frontend-plugin-api packages, the implementation is in @backstage/core-app-api and a factory has been added to @backstage/app-defaults.

Patch Changes

1.11.4-next.0

Patch Changes

1.11.3

Patch Changes

1.11.3-next.0

Patch Changes

1.11.2

Patch Changes

1.11.2-next.1

Patch Changes

1.11.2-next.0

Patch Changes

1.11.1

Patch Changes

1.11.1-next.0

Patch Changes

1.11.0

Minor Changes

  • c9d9bfeca2: URL encode some well known unsafe characters in RouteResolver (and therefore useRouteRef)

Patch Changes

  • 29e4d8b76b: Fixed bug in AppRouter to determine the correct signOutTargetUrl if app.baseUrl contains a basePath
  • acca17e91a: Wrap entire app in <Suspense>, enabling support for using translations outside plugins.
  • 1a0616fa10: Add missing resource and template app icons
  • 9a1fce352e: Updated dependency @testing-library/jest-dom to ^6.0.0.
  • f95af4e540: Updated dependency @testing-library/dom to ^9.0.0.
  • f1b349cfba: Fixed a bug in TranslationApi implementation where in some cases it wouldn't notify subscribers of language changes.
  • Updated dependencies

1.11.0-next.2

Minor Changes

  • c9d9bfeca2: URL encode some well known unsafe characters in RouteResolver (and therefore useRouteRef)

Patch Changes

1.10.1-next.1

Patch Changes

1.10.1-next.0

Patch Changes

1.10.0

Minor Changes

  • 18619f793c94: Fixed two bugs in how the OAuth2Session type represents the underlying data. The expiresAt and backstageIdentity are now both optional, since that's what they are in practice. This is not considered a breaking change since it was effectively a bug in the modelling of the state that this type represents, and the type was not used in any other external contract.
  • 18619f793c94: The OAuth class which is used by all OAuth providers will now consider both the session expiration of both the Backstage identity as well as the upstream identity provider, and refresh the session with either of them is about to expire.
  • 6e30769cc627: Introduced experimental support for internationalization.

Patch Changes

1.10.0-next.3

Patch Changes

1.10.0-next.2

Minor Changes

  • 6e30769cc627: Introduced experimental support for internationalization.

Patch Changes

1.10.0-next.1

Patch Changes

1.10.0-next.0

Minor Changes

  • 18619f793c94: Fixed two bugs in how the OAuth2Session type represents the underlying data. The expiresAt and backstageIdentity are now both optional, since that's what they are in practice. This is not considered a breaking change since it was effectively a bug in the modelling of the state that this type represents, and the type was not used in any other external contract.
  • 18619f793c94: The OAuth class which is used by all OAuth providers will now consider both the session expiration of both the Backstage identity as well as the upstream identity provider, and refresh the session with either of them is about to expire.

Patch Changes

1.9.1

Patch Changes

1.9.1-next.0

Patch Changes

1.9.0

Minor Changes

  • a77ddf7ccd71: add login in popup options to config popup width and height

Patch Changes

1.8.2-next.1

Patch Changes

1.8.2-next.0

Patch Changes

1.8.1

Patch Changes

  • 12adfbc8fe2d: Fixed a bug that prevented accurate plugin and route data from being applied to navigate analytics events when users visited pages constructed with <EntityLayout>, <TabbedLayout>, and similar components that are used to gather one or more routable extensions under a given path.
  • ac677bc30ae0: Expose discovery.endpoints configuration to use FrontendHostDiscovery
  • 74b216ee4e50: Add PropsWithChildren to usages of ComponentType, in preparation for React 18 where the children are no longer implicit.
  • Updated dependencies

1.8.1-next.0

Patch Changes

1.8.0

Minor Changes

  • c89437db899: The analytics' navigate event will now include the route parameters as attributes of the navigate event

Patch Changes

1.8.0-next.1

Minor Changes

  • c89437db899: The analytics' navigate event will now include the route parameters as attributes of the navigate event

Patch Changes

1.7.1-next.0

Patch Changes

1.7.0

Minor Changes

  • 7908d72e033: Introduce a new global config parameter, enableExperimentalRedirectFlow. When enabled, auth will happen with an in-window redirect flow rather than through a popup window.
  • c15e0cedbe1: The AuthConnector interface now supports specifying a set of scopes when refreshing a session. The DefaultAuthConnector implementation passes the scope query parameter to the auth-backend plugin appropriately. The RefreshingAuthSessionManager passes any scopes in its GetSessionRequest appropriately.

Patch Changes

1.7.0-next.3

Minor Changes

  • c15e0cedbe1: The AuthConnector interface now supports specifying a set of scopes when refreshing a session. The DefaultAuthConnector implementation passes the scope query parameter to the auth-backend plugin appropriately. The RefreshingAuthSessionManager passes any scopes in its GetSessionRequest appropriately.

Patch Changes

1.7.0-next.2

Patch Changes

1.7.0-next.1

Patch Changes

1.7.0-next.0

Minor Changes

  • 7908d72e033: Introduce a new global config parameter, enableExperimentalRedirectFlow. When enabled, auth will happen with an in-window redirect flow rather than through a popup window.

Patch Changes

1.6.0

Minor Changes

  • 456eaa8cf83: OAuth2 now gets ID tokens from a session with the openid scope explicitly requested.

    This should not be considered a breaking change, because spec-compliant OIDC providers will already be returning ID tokens if and only if the openid scope is granted.

    This change makes the dependence explicit, and removes the burden on OAuth2-based providers which require an ID token (e.g. this is done by various default auth handlers) to add openid to their default scopes. That could carry another indirect benefit: by removing openid from the default scopes for a provider, grants for resource-specific access tokens can avoid requesting excess ID token-related scopes.

Patch Changes

1.6.0-next.2

Minor Changes

  • 456eaa8cf83: OAuth2 now gets ID tokens from a session with the openid scope explicitly requested.

    This should not be considered a breaking change, because spec-compliant OIDC providers will already be returning ID tokens if and only if the openid scope is granted.

    This change makes the dependence explicit, and removes the burden on OAuth2-based providers which require an ID token (e.g. this is done by various default auth handlers) to add openid to their default scopes. That could carry another indirect benefit: by removing openid from the default scopes for a provider, grants for resource-specific access tokens can avoid requesting excess ID token-related scopes.

Patch Changes

1.5.1-next.1

Patch Changes

1.5.1-next.0

Patch Changes

1.5.0

Minor Changes

  • db10b6ef65: Added a Bitbucket Server Auth Provider and added its API to the app defaults

Patch Changes

1.4.1-next.0

Patch Changes

1.4.0

Minor Changes

Patch Changes

1.4.0-next.1

Minor Changes

Patch Changes

1.3.1-next.0

Patch Changes

1.3.0

Minor Changes

  • e0d9c9559a: Added a new AppRouter component and app.createRoot() method that replaces app.getRouter() and app.getProvider(), which are now deprecated. The new AppRouter component is a drop-in replacement for the old router component, while the new app.createRoot() method is used instead of the old provider component.

    An old app setup might look like this:

    const app = createApp(/* ... */);

const AppProvider = app.getProvider();
const AppRouter = app.getRouter();

const routes = ...;

const App = () => (
  <AppProvider>
    <AlertDisplay />
    <OAuthRequestDialog />
    <AppRouter>
      <Root>{routes}</Root>
    </AppRouter>
  </AppProvider>
);

export default App;

    With these new APIs, the setup now looks like this:

    import { AppRouter } from '@backstage/core-app-api';

const app = createApp(/* ... */);

const routes = ...;

export default app.createRoot(
  <>
    <AlertDisplay />
    <OAuthRequestDialog />
    <AppRouter>
      <Root>{routes}</Root>
    </AppRouter>
  </>,
);

    Note that app.createRoot() accepts a React element, rather than a component.

Patch Changes

  • d3fea4ae0a: Internal fixes to avoid implicit usage of globals
  • b05dcd5530: Move the zod dependency to a version that does not collide with other libraries
  • b4b5b02315: Tweak feature flag registration so that it happens immediately before the first rendering of the app, rather than just after.
  • 6870b43dd1: Fix for the automatic rewriting of base URLs.
  • 203271b746: Prevent duplicate feature flag components from rendering in the settings when using <FeatureFlagged /> components
  • 3280711113: Updated dependency msw to ^0.49.0.
  • 19356df560: Updated dependency zen-observable to ^0.9.0.
  • c3fa90e184: Updated dependency zen-observable to ^0.10.0.
  • 8015ff1258: Tweaked wording to use inclusive terminology
  • 653d7912ac: Made WebStorage notify its subscribers when localStorage values change in other tabs/windows
  • 63310e3987: Apps will now rewrite the app.baseUrl configuration to match the current location.origin. The backend.baseUrl will also be rewritten in the same way when the app.baseUrl and backend.baseUrl have matching origins. This will reduce the need for separate frontend builds for different environments.
  • Updated dependencies

1.3.0-next.4

Minor Changes

  • e0d9c9559a: Added a new AppRouter component and app.createRoot() method that replaces app.getRouter() and app.getProvider(), which are now deprecated. The new AppRouter component is a drop-in replacement for the old router component, while the new app.createRoot() method is used instead of the old provider component.

    An old app setup might look like this:

    const app = createApp(/* ... */);

const AppProvider = app.getProvider();
const AppRouter = app.getRouter();

const routes = ...;

const App = () => (
  <AppProvider>
    <AlertDisplay />
    <OAuthRequestDialog />
    <AppRouter>
      <Root>{routes}</Root>
    </AppRouter>
  </AppProvider>
);

export default App;

    With these new APIs, the setup now looks like this:

    import { AppRouter } from '@backstage/core-app-api';

const app = createApp(/* ... */);

const routes = ...;

export default app.createRoot(
  <>
    <AlertDisplay />
    <OAuthRequestDialog />
    <AppRouter>
      <Root>{routes}</Root>
    </AppRouter>
  </>,
);

    Note that app.createRoot() accepts a React element, rather than a component.

Patch Changes

1.2.1-next.3

Patch Changes

1.2.1-next.2

Patch Changes

  • b4b5b02315: Tweak feature flag registration so that it happens immediately before the first rendering of the app, rather than just after.
  • 203271b746: Prevent duplicate feature flag components from rendering in the settings when using <FeatureFlagged /> components
  • 8015ff1258: Tweaked wording to use inclusive terminology
  • 63310e3987: Apps will now rewrite the app.baseUrl configuration to match the current location.origin. The backend.baseUrl will also be rewritten in the same way when the app.baseUrl and backend.baseUrl have matching origins. This will reduce the need for separate frontend builds for different environments.
  • Updated dependencies

1.2.1-next.1

Patch Changes

1.2.1-next.0

Patch Changes

1.2.0

Minor Changes

  • 9b737e5f2e: Updated the React Router wiring to make use of the new basename property of the router components in React Router v6 stable. To implement this, a new optional basename property has been added to the Router app component, which can be forwarded to the concrete router implementation in order to support this new behavior. This is done by default in any app that does not have a Router component override.
  • 127fcad26d: Deprecated the homepage config as the component that used it - HomepageTimer - has been removed and replaced by the HeaderWorldClock in the home plugin

Patch Changes

1.2.0-next.0

Minor Changes

  • 9b737e5f2e: Updated the React Router wiring to make use of the new basename property of the router components in React Router v6 stable. To implement this, a new optional basename property has been added to the Router app component, which can be forwarded to the concrete router implementation in order to support this new behavior. This is done by default in any app that does not have a Router component override.
  • 127fcad26d: Deprecated the homepage config as the component that used it - HomepageTimer - has been removed and replaced by the HeaderWorldClock in the home plugin

Patch Changes

1.1.1

Patch Changes

1.1.1-next.2

Patch Changes

1.1.1-next.1

Patch Changes

1.1.1-next.0

Patch Changes

1.1.0

Minor Changes

  • a448fea691: Updated the routing system to be compatible with React Router v6 stable.

Patch Changes

  • 817f3196f6: Updated React Router dependencies to be peer dependencies.
  • f9ec4e46e3: When using React Router v6 stable, it is now possible for components within the Route element tree to have path props, although they will be ignored.
  • 7d47def9c4: Removed dependency on @types/jest.
  • 744fea158b: Added getSystemIcons() function to the AppContext available through useApp that will pull a list of all the icons that have been registered in the App.
  • 667d917488: Updated dependency msw to ^0.47.0.
  • 87ec2ba4d6: Updated dependency msw to ^0.46.0.
  • bf5e9030eb: Updated dependency msw to ^0.45.0.
  • 8448b53dd6: Clarify that the WebStorage observable returns JsonValue items.
  • 70299c99d5: Updated FlatRoutes to be compatible with React Router v6 stable.

  • e9d40ebf54: If you'd like to send analytics events to multiple implementations, you may now do so using the MultipleAnalyticsApi implementation provided by this package.

    import { MultipleAnalyticsApi } from '@backstage/core-app-api';
import {
  analyticsApiRef,
  configApiRef,
  storageApiRef,
  identityApiRef,
} from '@internal/backstage/core-plugin-api';
import { CustomAnalyticsApi } from '@internal/analytics';
import { VendorAnalyticsApi } from '@vendor/analytics';

createApiFactory({
  api: analyticsApiRef,
  deps: { configApi: configApiRef, identityApi: identityApiRef, storageApi: storageApiRef },
  factory: ({ configApi, identityApi, storageApi }) =>
    MultipleAnalyticsApi.fromApis([
      VendorAnalyticsApi.fromConfig(configApi, { identityApi }),
      CustomAnalyticsApi.fromConfig(configApi, { identityApi, storageApi }),
    ]),
}),

  • Updated dependencies

1.1.0-next.3

Patch Changes

1.1.0-next.2

Patch Changes

  • f9ec4e46e3: When using React Router v6 stable, it is now possible for components within the Route element tree to have path props, although they will be ignored.
  • 667d917488: Updated dependency msw to ^0.47.0.
  • 87ec2ba4d6: Updated dependency msw to ^0.46.0.

  • e9d40ebf54: If you'd like to send analytics events to multiple implementations, you may now do so using the MultipleAnalyticsApi implementation provided by this package.

    import { MultipleAnalyticsApi } from '@backstage/core-app-api';
import {
  analyticsApiRef,
  configApiRef,
  storageApiRef,
  identityApiRef,
} from '@internal/backstage/core-plugin-api';
import { CustomAnalyticsApi } from '@internal/analytics';
import { VendorAnalyticsApi } from '@vendor/analytics';

createApiFactory({
  api: analyticsApiRef,
  deps: { configApi: configApiRef, identityApi: identityApiRef, storageApi: storageApiRef },
  factory: ({ configApi, identityApi, storageApi }) =>
    MultipleAnalyticsApi.fromApis([
      VendorAnalyticsApi.fromConfig(configApi, { identityApi }),
      CustomAnalyticsApi.fromConfig(configApi, { identityApi, storageApi }),
    ]),
}),

  • Updated dependencies

1.1.0-next.1

Minor Changes

  • a448fea691: Updated the routing system to be compatible with React Router v6 stable.

Patch Changes

  • 817f3196f6: Updated React Router dependencies to be peer dependencies.
  • 70299c99d5: Updated FlatRoutes to be compatible with React Router v6 stable.
  • Updated dependencies

1.0.6-next.0

Patch Changes

  • 744fea158b: Added getSystemIcons() function to the AppContext available through useApp that will pull a list of all the icons that have been registered in the App.
  • bf5e9030eb: Updated dependency msw to ^0.45.0.
  • Updated dependencies

1.0.5

Patch Changes

1.0.5-next.0

Patch Changes

1.0.4

Patch Changes

  • 881fc75a75: Internal tweak removing usage of explicit type parameters for the BackstagePlugin type.
  • 8fe2357101: The signOut method of the IdentityApi will now navigate the user back to the base URL of the app as indicated by the app.baseUrl config.
  • a70869e775: Updated dependency msw to ^0.43.0.
  • 8006d0f9bf: Updated dependency msw to ^0.44.0.
  • Updated dependencies

1.0.4-next.1

Patch Changes

  • 881fc75a75: Internal tweak removing usage of explicit type parameters for the BackstagePlugin type.
  • a70869e775: Updated dependency msw to ^0.43.0.
  • Updated dependencies

1.0.4-next.0

Patch Changes

  • 8fe2357101: The signOut method of the IdentityApi will now navigate the user back to the base URL of the app as indicated by the app.baseUrl config.

1.0.3

Patch Changes

  • 8f7b1835df: Updated dependency msw to ^0.41.0.
  • 19781483a2: Handle URLs as the first argument to fetchApi, when using the plugin: protocol
  • Updated dependencies

1.0.3-next.0

Patch Changes

1.0.2

Patch Changes

1.0.2-next.1

Patch Changes

1.0.2-next.0

Patch Changes

1.0.1

Patch Changes

  • 7c7919777e: build(deps-dev): bump @testing-library/react-hooks from 7.0.2 to 8.0.0
  • 24254fd433: build(deps): bump @testing-library/user-event from 13.5.0 to 14.0.0
  • 3ff2bfb66e: Refactored the route collection logic to prepare for future changes and avoid duplicate element tree traversal for the analytics context.
  • a7bb762dab: fixed empty body issue for POST requests using FetchAPI with 'plugin://' prefix
  • 230ad0826f: Bump to using @types/node v16
  • c47509e1a0: Implemented changes suggested by Deepsource.io including multiple double non-null assertion operators and unexpected awaits for non-promise values.
  • Updated dependencies

1.0.1-next.1

Patch Changes

  • 24254fd433: build(deps): bump @testing-library/user-event from 13.5.0 to 14.0.0
  • 3ff2bfb66e: Refactored the route collection logic to prepare for future changes and avoid duplicate element tree traversal for the analytics context.
  • 230ad0826f: Bump to using @types/node v16
  • Updated dependencies

1.0.1-next.0

Patch Changes

  • a7bb762dab: fixed empty body issue for POST requests using FetchAPI with 'plugin://' prefix
  • c47509e1a0: Implemented changes suggested by Deepsource.io including multiple double non-null assertion operators and unexpected awaits for non-promise values.

1.0.0

Major Changes

  • b58c70c223: This package has been promoted to v1.0! To understand how this change affects the package, please check out our versioning policy.

Patch Changes

0.6.0

Minor Changes

  • bb2bb36651: BREAKING: Removed the deprecated get method from StorageAPI and its implementations, this method has been replaced by the snapshot method. The return value from snapshot no longer includes newValue which has been replaced by value. For getting notified when a value changes, use `observe# @backstage/core-app-api.
  • f3cce3dcf7: BREAKING: Removed export of GithubSession and SamlSession which are only used internally.
  • af5eaa87f4: BREAKING: Removed deprecated auth0AuthApiRef, oauth2ApiRef, samlAuthApiRef and oidcAuthApiRef as these APIs are too generic to be useful. Instructions for how to migrate can be found at https://backstage.io/docs/api/deprecations#generic-auth-api-refs.
  • dbf84eee55: BREAKING: Removed the deprecated GithubAuth.normalizeScopes method.

Patch Changes

0.5.4

Patch Changes

0.5.3

Patch Changes

0.5.2

Patch Changes

  • 40775bd263: Switched out the GithubAuth implementation to use the common OAuth2 implementation. This relies on the simultaneous change in @backstage/plugin-auth-backend that enabled access token storage in cookies rather than the current solution that's based on LocalStorage.

    NOTE: Make sure you upgrade the auth-backend deployment before or at the same time as you deploy this change.

0.5.2-next.0

Patch Changes

  • 40775bd263: Switched out the GithubAuth implementation to use the common OAuth2 implementation. This relies on the simultaneous change in @backstage/plugin-auth-backend that enabled access token storage in cookies rather than the current solution that's based on LocalStorage.

    NOTE: Make sure you upgrade the auth-backend deployment before or at the same time as you deploy this change.

0.5.1

Patch Changes

  • f959c22787: Asynchronous methods on the identity API can now reliably be called at any time, including early in the bootstrap process or prior to successful sign-in.

    Previously in such situations, a Tried to access IdentityApi before app was loaded error would be thrown. Now, those methods will wait and resolve eventually (as soon as a concrete identity API is provided).

0.5.0

Minor Changes

  • ceebe25391: Removed deprecated SignInResult type, which was replaced with the new onSignInSuccess callback.

Patch Changes

  • fb565073ec: Add an allowUrl callback option to FetchMiddlewares.injectIdentityAuth
  • f050eec2c0: Added validation during the application startup that detects if there are any plugins present that have not had their required external routes bound. Failing the validation will cause a hard crash as it is a programmer error. It lets you detect early on that there are dangling routes, rather than having them cause an error later on.
  • Updated dependencies

0.5.0-next.0

Minor Changes

  • ceebe25391: Removed deprecated SignInResult type, which was replaced with the new onSignInSuccess callback.

Patch Changes

0.4.0

Minor Changes

  • e2eb92c109: Removed previously deprecated ApiRegistry export.

Patch Changes

  • 34442cd5cf: Fixed an issue where valid SAML and GitHub sessions would be considered invalid and not be stored.

    Deprecated the SamlSession and GithubSession types.

  • 784d8078ab: Removed direct and transitive Material UI dependencies.

  • Updated dependencies

0.3.1

Patch Changes

0.3.0

Minor Changes

  • a195284c7b: Updated WebStorageApi to reflect the StorageApi changes in @backstage/core-plugin-api.
  • b3605da81c: - Removed deprecated definition createApp from @backstage/core-app-api which has been replaced by @backstage/app-defaults#createApp
    • Removed deprecated type BackstagePluginWithAnyOutput
    • Removed deprecated constructors for GithubAuth, OAuth2, and SamlAuth as the create method should be used instead
  • 68f8b10ccd: - Removed deprecation configuration option theme from AppTheme of the AppThemeApi
    • Removed reference to theme in the app-defaults default AppTheme
    • Removed logic in AppThemeProvider that creates ThemeProvider from appTheme.theme

Patch Changes

0.2.1

Patch Changes

0.2.0

Minor Changes

  • a036b65c2f: BREAKING CHANGE

    The app SignInPage component has been updated to switch out the onResult callback for a new onSignInSuccess callback. This is an immediate breaking change without any deprecation period, as it was deemed to be the way of making this change that had the lowest impact.

    The new onSignInSuccess callback directly accepts an implementation of an IdentityApi, rather than a SignInResult. The SignInPage from @backstage/core-component has been updated to fit this new API, and as long as you pass on props directly you should not see any breakage.

    However, if you implement your own custom SignInPage, then this will be a breaking change and you need to migrate over to using the new callback. While doing so you can take advantage of the UserIdentity.fromLegacy helper from @backstage/core-components to make the migration simpler by still using the SignInResult type. This helper is also deprecated though and is only provided for immediate migration. Long-term it will be necessary to build the IdentityApi using for example UserIdentity.create instead.

    The following is an example of how you can migrate existing usage immediately using UserIdentity.fromLegacy:

    onResult(signInResult);
// becomes
onSignInSuccess(UserIdentity.fromLegacy(signInResult));

    The following is an example of how implement the new onSignInSuccess callback of the SignInPage using UserIdentity.create:

    const identityResponse = await authApi.getBackstageIdentity();
// Profile is optional and will be removed, but allows the
// synchronous getProfile method of the IdentityApi to be used.
const profile = await authApi.getProfile();
onSignInSuccess(
  UserIdentity.create({
    identity: identityResponse.identity,
    authApi,
    profile,
  }),
);

Patch Changes

0.1.24

Patch Changes

0.1.23

Patch Changes

  • bab752e2b3: Change default port of backend from 7000 to 7007.

    This is due to the AirPlay Receiver process occupying port 7000 and preventing local Backstage instances on MacOS to start.

    You can change the port back to 7000 or any other value by providing an app-config.yaml with the following values:

    backend:
  listen: 0.0.0.0:7123
  baseUrl: http://localhost:7123

    More information can be found here: https://backstage.io/docs/conf/writing

  • 000190de69: The ApiRegistry from @backstage/core-app-api class has been deprecated and will be removed in a future release. To replace it, we have introduced two new helpers that are exported from @backstage/test-utils, namely TestApiProvider and TestApiRegistry.

    These two new helpers are more tailored for writing tests and development setups, as they allow for partial implementations of each of the APIs.

    When migrating existing code it is typically best to prefer usage of TestApiProvider when possible, so for example the following code:

    render(
  <ApiProvider
    apis={ApiRegistry.from([
      [identityApiRef, mockIdentityApi as unknown as IdentityApi]
    ])}
  >
    {...}
  </ApiProvider>
)

    Would be migrated to this:

    render(
  <TestApiProvider apis={[[identityApiRef, mockIdentityApi]]}>
    {...}
  </TestApiProvider>
)

    In cases where the ApiProvider is used in a more standalone way, for example to reuse a set of APIs across multiple tests, the TestApiRegistry can be used instead. Note that the TestApiRegistry only has a single static factory method, .from(), and it is slightly different from the existing .from() method on ApiRegistry in that it doesn't require the API pairs to be wrapped in an outer array.

    Usage that looks like this:

    const apis = ApiRegistry.with(
  identityApiRef,
  mockIdentityApi as unknown as IdentityApi,
).with(configApiRef, new ConfigReader({}));

    OR like this:

    const apis = ApiRegistry.from([
  [identityApiRef, mockIdentityApi as unknown as IdentityApi],
  [configApiRef, new ConfigReader({})],
]);

    Would be migrated to this:

    const apis = TestApiRegistry.from(
  [identityApiRef, mockIdentityApi],
  [configApiRef, new ConfigReader({})],
);

    If your app is still using the ApiRegistry to construct the apis for createApp, we recommend that you move over to use the new method of supplying API factories instead, using createApiFactory.

  • Updated dependencies

0.1.22

Patch Changes

  • Reverted the createApp TypeScript type to match the one before version 0.1.21, as it was an accidental breaking change.

0.1.21

Patch Changes

  • 0b1de52732: Migrated to using new ErrorApiError and ErrorApiErrorContext names.
  • ecd1fcb80a: Deprecated the BackstagePluginWithAnyOutput type.
  • 32bfbafb0f: Start exporting and marking several types as public to address errors in the API report.

  • 014cbf8cb9: The createApp function from @backstage/core-app-api has been deprecated, with two new options being provided as a replacement.

    The first and most commonly used one is createApp from the new @backstage/app-defaults package, which behaves just like the existing createApp. In the future this method is likely to be expanded to add more APIs and other pieces into the default setup, for example the Utility APIs from @backstage/integration-react.

    The other option that we now provide is to use createSpecializedApp from @backstage/core-app-api. This is a more low-level API where you need to provide a full set of options, including your own components, icons, defaultApis, and themes. The createSpecializedApp way of creating an app is particularly useful if you are not using @backstage/core-components or Material UI, as it allows you to avoid those dependencies completely.

  • 475edb5bc5: move the BehaviorSubject init into the constructor

  • Updated dependencies

0.1.20

Patch Changes

0.1.19

Patch Changes

  • 10615525f3: Switch to use the json and observable types from @backstage/types
  • 41c49884d2: Start using the new @backstage/types package. Initially, this means using the Observable and Json* types from there. The types also remain in their old places but deprecated, and will be removed in a future release.
  • 925a967f36: Replace usage of test-utils-core with test-utils
  • 6b615e92c8: Api cleanup, adding @public where necessary and tweaking some comments
  • Updated dependencies

0.1.18

Patch Changes

  • 202f322927: Atlassian auth provider

    • AtlassianAuth added to core-app-api
    • Atlassian provider added to plugin-auth-backend
    • Updated user-settings with Atlassian connection

  • 36e67d2f24: Internal updates to apply more strict checks to throw errors.

  • Updated dependencies

0.1.17

Patch Changes

0.1.16

Patch Changes

  • d9fd798cc8: The Core App API now automatically instruments all route location changes using the new Analytics API. Each location change triggers a navigate event, which is an analogue of a "pageview" event in traditional web analytics systems. In addition to the path, these events provide plugin-level metadata via the analytics context, which can be useful for analyzing plugin usage:

    {
  "action": "navigate",
  "subject": "/the-path/navigated/to?with=params#and-hashes",
  "context": {
    "extension": "App",
    "pluginId": "id-of-plugin-that-exported-the-route",
    "routeRef": "associated-route-ref-id"
  }
}

    These events can be identified and handled by checking for the action navigate and the extension App.

  • 4c3eea7788: Bitbucket Cloud authentication - based on the existing GitHub authentication + changes around BB apis and updated scope.

    • BitbucketAuth added to core-app-api.
    • Bitbucket provider added to plugin-auth-backend.
    • Cosmetic entry for Bitbucket connection in user-settings Authentication Providers tab.

  • d6ad46eb22: Stop calling connector.removeSession in StaticAuthSessionManager, instead just discarding the session locally.

  • Updated dependencies

0.1.15

Patch Changes

0.1.14

Patch Changes

0.1.13

Patch Changes

0.1.12

Patch Changes

0.1.11

Patch Changes

0.1.10

Patch Changes

  • cfcb486aa: Add system icons for the built-in entity types and use them in the entity list of the catalog-import plugin.

  • 392b36fa1: Added support for using authenticating via GitHub Apps in addition to GitHub OAuth Apps. It used to be possible to use GitHub Apps, but they did not handle session refresh correctly.

    Note that GitHub Apps handle OAuth scope at the app installation level, meaning that the scope parameter for getAccessToken has no effect. When calling getAccessToken in open source plugins, one should still include the appropriate scope, but also document in the plugin README what scopes are required in the case of GitHub Apps.

    In addition, the authHandler and signInResolver options have been implemented for the GitHub provider in the auth backend.

  • Updated dependencies

0.1.9

Patch Changes

0.1.8

Patch Changes

0.1.7

Patch Changes

0.1.6

Patch Changes

  • 9d40fcb1e: - Bumping material-ui/core version to at least 4.12.2 as they made some breaking changes in later versions which broke Pagination of the Table.
    • Switching out material-table to @material-table/core for support for the later versions of material-ui/core
    • This causes a minor API change to @backstage/core-components as the interface for Table re-exports the prop from the underlying Table components.
    • onChangeRowsPerPage has been renamed to onRowsPerPageChange
    • onChangePage has been renamed to onPageChange
    • Migration guide is here: https://material-table-core.com/docs/breaking-changes
  • Updated dependencies

0.1.5

Patch Changes

  • ea249c6e6: Fix a bug in FlatRoutes that prevented outlets from working with the root route, as well as matching root routes too broadly.
  • Updated dependencies

0.1.4

Patch Changes

0.1.3

Patch Changes

  • dc3e7ce68: Introducing new UnhandledErrorForwarder installed by default. For catching unhandled promise rejections, you can override the API to align with general error handling.
  • 5f4339b8c: Adding FeatureFlag component and treating FeatureFlags as first class citizens to composability API
  • Updated dependencies

0.1.2

Patch Changes

  • 9bca2a252: Fixes a type bug where supplying all app icons to createApp was required, rather than just a partial list.

  • 75b8537ce: This change adds automatic error boundaries around extensions.

    This means that all exposed parts of a plugin are wrapped in a general error boundary component, that is plugin aware. The default design for the error box is borrowed from @backstage/errors. To override the default "fallback", one must provide a component named ErrorBoundaryFallback to createApp, like so:

    const app = createApp({
  components: {
    ErrorBoundaryFallback: props => {
      // a custom fallback component
      return (
        <>
          <h1>Oops.</h1>
          <h2>
            The plugin {props.plugin.getId()} failed with{' '}
            {props.error.message}
          </h2>
          <button onClick={props.resetError}>Try again</button>
        </>
      );
    },
  },
});

    The props here include:

    • error. An Error object or something that inherits it that represents the error that was thrown from any inner component.
    • resetError. A callback that will simply attempt to mount the children of the error boundary again.
    • plugin. A BackstagePlugin that can be used to look up info to be presented in the error message. For instance, you may want to keep a map of your internal plugins and team names or slack channels and present these when an error occurs. Typically, you'll do that by getting the plugin ID with plugin.getId().

  • da8cba44f: Deprecate and disable the extension creation methods, which were added to this package by mistake and should only exist within @backstage/core-plugin-api.

  • 9bca2a252: Update createApp options to allow plugins with unknown output types in order to improve forwards and backwards compatibility.
  • Updated dependencies [e47336ea4]
  • Updated dependencies [75b8537ce]
  • Updated dependencies [da8cba44f]

0.1.1

Patch Changes