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

Package detail

@backstage/backend-defaults

backstage663.8kApache-2.00.9.0TypeScript support: included

Backend defaults used by Backstage backend 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/backend-defaults

0.9.0

Minor Changes

  • 1daedce: Remove Throttle of Bitbucket Server API calls
  • 01edf6e: Allow pass through of redis client and cluster options to Cache core service
  • cf4eb13: Added actor property to BackstageUserPrincipal containing the subject of the last service (if any) who performed authentication on behalf of the user.

Patch Changes

0.9.0-next.2

Patch Changes

0.9.0-next.1

Patch Changes

0.9.0-next.0

Minor Changes

  • 01edf6e: Allow pass through of redis client and cluster options to Cache core service

Patch Changes

0.8.2

Patch Changes

0.8.2-next.2

Patch Changes

0.8.2-next.1

Patch Changes

0.8.2-next.0

Patch Changes

0.8.0

Minor Changes

  • a4aa244: This change introduces the auditor service implementation details.

Patch Changes

0.8.0-next.3

Patch Changes

0.8.0-next.2

Patch Changes

0.8.0-next.1

Patch Changes

0.8.0-next.0

Minor Changes

  • a4aa244: This change introduces the auditor service implementation details.

Patch Changes

0.7.0

Minor Changes

  • ec547b8: Ensure that an error handler middleware exists at the end of each plugin httpRouter handler chain. This makes it so that exceptions thrown by plugin routes are caught and encoded in the standard error format.

    If you were using the standard MiddlewareFactory just to put an error middleware in you router, you can now remove that at your earliest convenience since it's redundant. If you have custom error handlers in your plugin router, those will continue to function as previously. If you were relying on thrown errors propagating all the way down to the root HTTP router, you will find that they no longer do that, and may want to hoist your error handling up to the plugin level instead.

Patch Changes

0.7.0-next.1

Patch Changes

0.7.0-next.0

Minor Changes

  • ec547b8: Ensure that an error handler middleware exists at the end of each plugin httpRouter handler chain. This makes it so that exceptions thrown by plugin routes are caught and encoded in the standard error format.

    If you were using the standard MiddlewareFactory just to put an error middleware in you router, you can now remove that at your earliest convenience since it's redundant. If you have custom error handlers in your plugin router, those will continue to function as previously. If you were relying on thrown errors propagating all the way down to the root HTTP router, you will find that they no longer do that, and may want to hoist your error handling up to the plugin level instead.

Patch Changes

0.6.0

Minor Changes

  • fd5d337: Added a new backend.health.headers configuration that can be used to set additional headers to include in health check responses.

    BREAKING CONSUMERS: As part of this change the createHealthRouter function exported from @backstage/backend-defaults/rootHttpRouter now requires the root config service to be passed through the config option.

  • 3f34ea9: Throttles Bitbucket Server API calls

  • de6f280: BREAKING Upgraded @keyv/redis and keyv packages to resolve a bug related to incorrect resolution of cache keys.

    This is a breaking change for clients using the redis store for cache with useRedisSets option set to false since cache keys will be calculated differently (without the sets:namespace: prefix). For clients with default configuration (or useRedisSets set to false) the cache keys will stay the same, but since @keyv/redis library no longer supports redis sets they won't be utilised anymore.

    If you were using useRedisSets option in configuration make sure to remove it from app-config.yaml:

    backend:
  cache:
    store: redis
    connection: redis://user:pass@cache.example.com:6379
-   useRedisSets: false

  • 29180ec: BREAKING PRODUCERS: The LifecycleMiddlewareOptions.startupRequestPauseTimeout has been removed. Use the backend.lifecycle.startupRequestPauseTimeout setting in your app-config.yaml file to customize how the createLifecycleMiddleware function should behave. Also the root config service is required as an option when calling the createLifecycleMiddleware function:

    - createLifecycleMiddleware({ lifecycle, startupRequestPauseTimeout })
+ createLifecycleMiddleware({ config,  lifecycle })

  • 277092a: Implemented AzureBlobStorageUrlReader to read from the url of committed location from the entity provider

  • 18a2c00: All middleware used by the default coreServices.http is now exported for use by custom implementations.

Patch Changes

  • dfc8b41: Updated dependency @opentelemetry/api to ^1.9.0.
  • 5b1e68c: Immediately close all connections when shutting down in local development.
  • 8863b38: Export PluginTokenHandler and pluginTokenHandlerDecoratorServiceRef to allow for custom decoration of the plugin token handler without having to re-implement the entire handler.
  • 29180ec: Fix server response time by moving the lifecycle startup hooks back to the plugin lifecycle service.
  • 57e0b11: The user and plugin token verification in the default AuthService implementation will no longer forward verification errors to the caller, and instead log them as warnings.
  • 97c6837: Export DefaultHttpAuthService to allow for custom token extraction logic.
  • e5255f1: Log request and response metadata so it can be used for filtering log messages. The format of the request date was also changed from clf to utc.
  • 57e0b11: The default authServiceFactory now correctly depends on the plugin scoped Logger services rather than the root scoped one.
  • fe87fbf: Add task metrics as two gauges that track the last start and end timestamps as epoch seconds.
  • 1ac6b72: Support connection.type: cloudsql in database client for usage with @google-cloud/cloud-sql-connector and iam auth
  • 0e9c9fa: Implements the DefaultRootLifecycleService.addBeforeShutdownHook method, and updates DefaultRootHttpRouterService and DefaultRootHealthService to listen to that event to stop accepting traffic and close service connections.
  • d0cbd82: Remove use of the stoppable library on the DefaultRootHttpRouterService as Node's native http server close method already drains requests.
  • 5c9cc05: Use native fetch instead of node-fetch
  • cf627c6: Fixed an issue in the WinstonLogger where Errors thrown and given to logger.error with field values that could not be cast to a string would throw a TypeError
  • Updated dependencies

0.6.0-next.2

Minor Changes

  • fd5d337: Added a new backend.health.headers configuration that can be used to set additional headers to include in health check responses.

    BREAKING CONSUMERS: As part of this change the createHealthRouter function exported from @backstage/backend-defaults/rootHttpRouter now requires the root config service to be passed through the config option.

  • 3f34ea9: Throttles Bitbucket Server API calls

Patch Changes

0.6.0-next.1

Patch Changes

0.6.0-next.0

Minor Changes

  • de6f280: BREAKING Upgraded @keyv/redis and keyv packages to resolve a bug related to incorrect resolution of cache keys.

    This is a breaking change for clients using the redis store for cache with useRedisSets option set to false since cache keys will be calculated differently (without the sets:namespace: prefix). For clients with default configuration (or useRedisSets set to false) the cache keys will stay the same, but since @keyv/redis library no longer supports redis sets they won't be utilised anymore.

    If you were using useRedisSets option in configuration make sure to remove it from app-config.yaml:

    backend:
  cache:
    store: redis
    connection: redis://user:pass@cache.example.com:6379
-   useRedisSets: false

  • 277092a: Implemented AzureBlobStorageUrlReader to read from the url of committed location from the entity provider

  • 18a2c00: All middleware used by the default coreServices.http is now exported for use by custom implementations.

Patch Changes

0.5.3

Patch Changes

0.5.3-next.3

Patch Changes

0.5.3-next.2

Patch Changes

0.5.3-next.1

Patch Changes

0.5.3-next.0

Patch Changes

0.5.1

Patch Changes

0.5.1-next.2

Patch Changes

0.5.1-next.1

Patch Changes

0.5.1-next.0

Patch Changes

0.5.0

Minor Changes

  • a4bac3c: BREAKING: You can no longer supply a basePath option to the host discovery implementation. In the new backend system, the ability to choose this path has been removed anyway at the plugin router level.
  • 359fcd7: BREAKING: The backwards compatibility with plugins using legacy auth through the token manager service has been removed. This means that instead of falling back to using the old token manager, requests towards plugins that don't support the new auth system will simply fail. Please make sure that all plugins in your deployment are hosted within a backend instance from the new backend system.
  • baeef13: BREAKING Removed createLifecycleMiddleware and LifecycleMiddlewareOptions to clean up API surface. These exports have no external usage and do not provide value in its current form. If you were using these exports, please reach out to the maintainers to discuss your use case.

  • d425fc4: BREAKING: The return values from createBackendPlugin, createBackendModule, and createServiceFactory are now simply BackendFeature and ServiceFactory, instead of the previously deprecated form of a function that returns them. For this reason, createServiceFactory also no longer accepts the callback form where you provide direct options to the service. This also affects all coreServices.* service refs.

    This may in particular affect tests; if you were effectively doing createBackendModule({...})() (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your packages/backend/src/index.ts too, where you add plugins, modules, and services. If you were using createServiceFactory with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.

    As part of this change, the IdentityFactoryOptions type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to migrate to the new auth system if you still rely on it.

  • 19ff127: BREAKING: The default backend instance no longer provides implementations for the identity and token manager services, which have been removed from @backstage/backend-plugin-api.

    If you rely on plugins that still require these services, you can add them to your own backend by re-creating the service reference and factory.

    The following can be used to implement the identity service:

    import {
  coreServices,
  createServiceFactory,
  createServiceRef,
} from '@backstage/backend-plugin-api';
import {
  DefaultIdentityClient,
  IdentityApi,
} from '@backstage/plugin-auth-node';

backend.add(
  createServiceFactory({
    service: createServiceRef<IdentityApi>({ id: 'core.identity' }),
    deps: {
      discovery: coreServices.discovery,
    },
    async factory({ discovery }) {
      return DefaultIdentityClient.create({ discovery });
    },
  }),
);

    The following can be used to implement the token manager service:

    import { ServerTokenManager, TokenManager } from '@backstage/backend-common';
import { createBackend } from '@backstage/backend-defaults';
import {
  coreServices,
  createServiceFactory,
  createServiceRef,
} from '@backstage/backend-plugin-api';

backend.add(
  createServiceFactory({
    service: createServiceRef<TokenManager>({ id: 'core.tokenManager' }),
    deps: {
      config: coreServices.rootConfig,
      logger: coreServices.rootLogger,
    },
    createRootContext({ config, logger }) {
      return ServerTokenManager.fromConfig(config, {
        logger,
        allowDisabledTokenManager: true,
      });
    },
    async factory(_deps, tokenManager) {
      return tokenManager;
    },
  }),
);

  • 055b75b: BREAKING: Simplifications and cleanup as part of the Backend System 1.0 work.

    For the /database subpath exports:

    • The deprecated dropDatabase function has now been removed, without replacement.
    • The deprecated LegacyRootDatabaseService type has now been removed.
    • The return type from DatabaseManager.forPlugin is now directly a DatabaseService, as arguably expected.
    • DatabaseManager.forPlugin now requires the deps argument, with the logger and lifecycle services.

    For the /cache subpath exports:

    • The PluginCacheManager type has been removed. You can still import it from @backstage/backend-common, but it's deprecated there, and you should move off of that package by migrating fully to the new backend system.
    • Accordingly, CacheManager.forPlugin immediately returns a CacheService instead of a PluginCacheManager. The outcome of this is that you no longer need to make the extra .getClient() call. The old CacheManager with the old behavior still exists on @backstage/backend-common, but the above recommendations apply.

Patch Changes

0.5.0-next.2

Minor Changes

  • baeef13: BREAKING Removed createLifecycleMiddleware and LifecycleMiddlewareOptions to clean up API surface. These exports have no external usage and do not provide value in its current form. If you were using these exports, please reach out to the maintainers to discuss your use case.

Patch Changes

0.5.0-next.1

Minor Changes

  • a4bac3c: BREAKING: You can no longer supply a basePath option to the host discovery implementation. In the new backend system, the ability to choose this path has been removed anyway at the plugin router level.

  • 055b75b: BREAKING: Simplifications and cleanup as part of the Backend System 1.0 work.

    For the /database subpath exports:

    • The deprecated dropDatabase function has now been removed, without replacement.
    • The deprecated LegacyRootDatabaseService type has now been removed.
    • The return type from DatabaseManager.forPlugin is now directly a DatabaseService, as arguably expected.
    • DatabaseManager.forPlugin now requires the deps argument, with the logger and lifecycle services.

    For the /cache subpath exports:

    • The PluginCacheManager type has been removed. You can still import it from @backstage/backend-common, but it's deprecated there, and you should move off of that package by migrating fully to the new backend system.
    • Accordingly, CacheManager.forPlugin immediately returns a CacheService instead of a PluginCacheManager. The outcome of this is that you no longer need to make the extra .getClient() call. The old CacheManager with the old behavior still exists on @backstage/backend-common, but the above recommendations apply.

Patch Changes

0.5.0-next.0

Minor Changes

  • 359fcd7: BREAKING: The backwards compatibility with plugins using legacy auth through the token manager service has been removed. This means that instead of falling back to using the old token manager, requests towards plugins that don't support the new auth system will simply fail. Please make sure that all plugins in your deployment are hosted within a backend instance from the new backend system.

  • d425fc4: BREAKING: The return values from createBackendPlugin, createBackendModule, and createServiceFactory are now simply BackendFeature and ServiceFactory, instead of the previously deprecated form of a function that returns them. For this reason, createServiceFactory also no longer accepts the callback form where you provide direct options to the service. This also affects all coreServices.* service refs.

    This may in particular affect tests; if you were effectively doing createBackendModule({...})() (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your packages/backend/src/index.ts too, where you add plugins, modules, and services. If you were using createServiceFactory with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.

    As part of this change, the IdentityFactoryOptions type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to migrate to the new auth system if you still rely on it.

  • 19ff127: BREAKING: The default backend instance no longer provides implementations for the identity and token manager services, which have been removed from @backstage/backend-plugin-api.

    If you rely on plugins that still require these services, you can add them to your own backend by re-creating the service reference and factory.

    The following can be used to implement the identity service:

    import {
  coreServices,
  createServiceFactory,
  createServiceRef,
} from '@backstage/backend-plugin-api';
import {
  DefaultIdentityClient,
  IdentityApi,
} from '@backstage/plugin-auth-node';

backend.add(
  createServiceFactory({
    service: createServiceRef<IdentityApi>({ id: 'core.identity' }),
    deps: {
      discovery: coreServices.discovery,
    },
    async factory({ discovery }) {
      return DefaultIdentityClient.create({ discovery });
    },
  }),
);

    The following can be used to implement the token manager service:

    import { ServerTokenManager, TokenManager } from '@backstage/backend-common';
import { createBackend } from '@backstage/backend-defaults';
import {
  coreServices,
  createServiceFactory,
  createServiceRef,
} from '@backstage/backend-plugin-api';

backend.add(
  createServiceFactory({
    service: createServiceRef<TokenManager>({ id: 'core.tokenManager' }),
    deps: {
      config: coreServices.rootConfig,
      logger: coreServices.rootLogger,
    },
    createRootContext({ config, logger }) {
      return ServerTokenManager.fromConfig(config, {
        logger,
        allowDisabledTokenManager: true,
      });
    },
    async factory(_deps, tokenManager) {
      return tokenManager;
    },
  }),
);

Patch Changes

0.4.2

Patch Changes

0.4.2-next.3

Patch Changes

0.4.2-next.2

Patch Changes

0.4.2-next.1

Patch Changes

0.4.2-next.0

Patch Changes

0.4.0

Minor Changes

  • 1cb84d7: BREAKING: Removed the depreacted getPath option from httpRouterServiceFactory, as well as the HttpRouterFactoryOptions type.

Patch Changes

0.3.4-next.1

Patch Changes

0.3.3-next.0

Patch Changes

0.3.0

Minor Changes

  • 662dce8: BREAKING: The workdir argument have been removed from The GerritUrlReader constructor.

    BREAKING: The Gerrit readTree implementation will now only use the Gitiles api. Support for using git to clone the repo has been removed.

  • 02103be: Deprecated and moved over core services to @backstage/backend-defaults

Patch Changes

0.3.0-next.3

Patch Changes

0.3.0-next.2

Patch Changes

0.3.0-next.1

Minor Changes

  • 02103be: Deprecated and moved over core services to @backstage/backend-defaults

Patch Changes

0.2.19-next.0

Patch Changes

0.2.18

Patch Changes

0.2.18-next.2

Patch Changes

0.2.18-next.1

Patch Changes

0.2.18-next.0

Patch Changes

0.2.17

Patch Changes

0.2.17-next.1

Patch Changes

0.2.17-next.0

Patch Changes

0.2.16

Patch Changes

0.2.15

Patch Changes

0.2.14

Patch Changes

0.2.14-next.2

Patch Changes

0.2.14-next.1

Patch Changes

0.2.13-next.0

Patch Changes

0.2.10

Patch Changes

0.2.10-next.3

Patch Changes

0.2.10-next.2

Patch Changes

0.2.10-next.1

Patch Changes

0.2.10-next.0

Patch Changes

0.2.9

Patch Changes

0.2.9-next.2

Patch Changes

0.2.9-next.1

Patch Changes

0.2.9-next.0

Patch Changes

0.2.8

Patch Changes

0.2.8-next.3

Patch Changes

0.2.8-next.2

Patch Changes

0.2.8-next.1

Patch Changes

0.2.8-next.0

Patch Changes

0.2.7

Patch Changes

0.2.7-next.2

Patch Changes

0.2.7-next.1

Patch Changes

0.2.7-next.0

Patch Changes

0.2.6

Patch Changes

0.2.6-next.2

Patch Changes

0.2.5-next.1

Patch Changes

0.2.5-next.0

Patch Changes

0.2.3

Patch Changes

0.2.3-next.3

Patch Changes

0.2.3-next.2

Patch Changes

0.2.3-next.1

Patch Changes

0.2.2-next.0

Patch Changes

0.2.0

Minor Changes

  • d008aefef808: BREAKING: Removing shared environments concept from the new experimental backend system.

  • a6d7983f349c: BREAKING: Removed the services option from createBackend. Service factories are now BackendFeatures and should be installed with backend.add(...) instead. The following should be migrated:

    const backend = createBackend({ services: [myCustomServiceFactory] });

    To instead pass the service factory via backend.add(...):

    const backend = createBackend();
backend.add(customRootLoggerServiceFactory);

Patch Changes

0.2.0-next.2

Patch Changes

0.2.0-next.1

Minor Changes

  • d008aefef808: BREAKING: Removing shared environments concept from the new experimental backend system.

Patch Changes

0.1.13-next.0

Patch Changes

0.1.12

Patch Changes

0.1.12-next.0

Patch Changes

0.1.11

Patch Changes

0.1.11-next.2

Patch Changes

0.1.11-next.1

Patch Changes

0.1.11-next.0

Patch Changes

0.1.10

Patch Changes

0.1.10-next.1

Patch Changes

0.1.10-next.0

Patch Changes

0.1.9

Patch Changes

0.1.9-next.2

Patch Changes

0.1.9-next.1

Patch Changes

0.1.9-next.0

Patch Changes

0.1.8

Patch Changes

0.1.8-next.2

Patch Changes

0.1.8-next.1

Patch Changes

0.1.8-next.0

Patch Changes

0.1.7

Patch Changes

0.1.7-next.2

Patch Changes

0.1.7-next.1

Patch Changes

0.1.7-next.0

Patch Changes

0.1.5

Patch Changes

  • 6cfd4d7073: Include implementations for the new rootLifecycleServiceRef.
  • ecc6bfe4c9: Use new ServiceFactoryOrFunction type.
  • 015a6dced6: Updated to make sure that service implementations replace default service implementations.
  • 843a0a158c: Added factory for the new core identity service to the set of default service factories.
  • 5b7bcd3c5e: Added support to supply a shared environment to createBackend, which can be created using createSharedEnvironment from @backstage/backend-plugin-api.
  • 02b119ff93: The new root HTTP router service is now installed by default.
  • Updated dependencies

0.1.5-next.1

Patch Changes

0.1.5-next.0

Patch Changes

0.1.4

Patch Changes

0.1.4-next.3

Patch Changes

0.1.4-next.2

Patch Changes

0.1.4-next.1

Patch Changes

0.1.4-next.0

Patch Changes

0.1.3

Patch Changes

0.1.3-next.1

Patch Changes

0.1.3-next.0

Patch Changes

0.1.2

Patch Changes

0.1.2-next.2

Patch Changes

0.1.2-next.1

Patch Changes

0.1.2-next.0

Patch Changes

0.1.1

Patch Changes

0.1.1-next.1

Patch Changes

0.1.1-next.0

Patch Changes

0.1.0

Minor Changes

  • 5df230d48c: Introduced a new backend-defaults package carrying createBackend which was previously exported from backend-app-api. The backend-app-api package now exports the createSpecializedBacked that does not add any service factories by default.

Patch Changes