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

Package detail

@backstage/backend-plugin-api

backstage1.1mApache-2.01.3.0TypeScript support: included

Core API used by Backstage backend plugins

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-plugin-api

1.3.0

Minor Changes

  • 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

1.2.1

Patch Changes

1.2.1-next.1

Patch Changes

1.2.1-next.0

Patch Changes

1.2.0

Minor Changes

  • 92a56f6: BREAKING ALPHA: Removed the deprecated featureDiscoveryServiceRef and FeatureDiscoveryService.
  • a4aa244: This change introduces the auditor service definition.

Patch Changes

1.2.0-next.2

Patch Changes

1.2.0-next.1

Minor Changes

  • 92a56f6: BREAKING ALPHA: Removed the deprecated featureDiscoveryServiceRef and FeatureDiscoveryService.

Patch Changes

1.2.0-next.0

Minor Changes

  • a4aa244: This change introduces the auditor service definition.

Patch Changes

1.1.1

Patch Changes

1.1.1-next.1

Patch Changes

1.1.1-next.0

Patch Changes

1.1.0

Minor Changes

  • 12eac85: EXPERIMENTAL: Adds a new instanceMetadataService to hold information about a specific backend instance.

Patch Changes

1.1.0-next.2

Patch Changes

1.1.0-next.1

Minor Changes

  • 12eac85: EXPERIMENTAL: Adds a new instanceMetadataService to hold information about a specific backend instance.

Patch Changes

1.0.3-next.0

Patch Changes

1.0.2

Patch Changes

1.0.2-next.2

Patch Changes

1.0.2-next.1

Patch Changes

1.0.2-next.0

Patch Changes

1.0.1

Patch Changes

1.0.1-next.1

Patch Changes

1.0.1-next.0

Patch Changes

1.0.0

Major Changes

  • ec1b4be: Release 1.0 of the new backend system! :tada:

    The backend system is finally getting promoted to 1.0.0. This means that the API is now stable and breaking changes should not occur until version 2.0.0, see our package versioning policy for more information what this means.

    This release also marks the end of the old backend system based on createRouter exports. Going forward backend plugins packages will start to deprecate and later this year remove exports supporting the old backend system. If you would like to help out with this transition, see https://github.com/backstage/backstage/issues/26353 or consult the migration guide.

Minor Changes

  • 19ff127: BREAKING: The deprecated identity and token manager services have been removed. This means that coreServices.identity and coreServices.tokenManager are gone, along with related types and utilities in other packages.

  • f687050: Removed the following deprecated exports

    • BackendPluginConfig use CreateBackendPluginOptions
    • BackendModuleConfig use CreateBackendModuleOptions
    • ExtensionPointConfig use CreateExtensionPointOptions

  • 4d82481: Removed deprecated ServiceFactoryOrFunction type.

  • 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.

Patch Changes

1.0.0-next.2

Major Changes

  • ec1b4be: Release 1.0 of the new backend system! :tada:

    The backend system is finally getting promoted to 1.0.0. This means that the API is now stable and breaking changes should not occur until version 2.0.0, see our package versioning policy for more information what this means.

    This release also marks the end of the old backend system based on createRouter exports. Going forward backend plugins packages will start to deprecate and later this year remove exports supporting the old backend system. If you would like to help out with this transition, see https://github.com/backstage/backstage/issues/26353 or consult the migration guide.

Patch Changes

0.9.0-next.1

Patch Changes

0.9.0-next.0

Minor Changes

  • 19ff127: BREAKING: The deprecated identity and token manager services have been removed. This means that coreServices.identity and coreServices.tokenManager are gone, along with related types and utilities in other packages.

  • f687050: Removed the following deprecated exports

    • BackendPluginConfig use CreateBackendPluginOptions
    • BackendModuleConfig use CreateBackendModuleOptions
    • ExtensionPointConfig use CreateExtensionPointOptions

  • 4d82481: Removed deprecated ServiceFactoryOrFunction type.

  • 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.

Patch Changes

0.8.0

Minor Changes

  • 389f5a4: BREAKING Deleted the following deprecated UrlReader exports

    • ReadUrlOptions: Use UrlReaderServiceReadUrlOptions instead;
    • ReadUrlResponse: Use UrlReaderServiceReadUrlResponse instead;
    • ReadTreeOptions: Use UrlReaderServiceReadTreeOptions instead;
    • ReadTreeResponse: Use UrlReaderServiceReadTreeResponse instead;
    • ReadTreeResponseFile: Use UrlReaderServiceReadTreeResponseFile instead;
    • ReadTreeResponseDirOptions: Use UrlReaderServiceReadTreeResponseDirOptions instead;
    • SearchOptions: Use UrlReaderServiceSearchOptions instead;
    • SearchResponse: Use UrlReaderServiceSearchResponse instead;
    • SearchResponseFile: Use UrlReaderServiceSearchResponseFile instead.

  • 7c5f3b0: The createServiceRef function now accepts a new boolean multiple option. The multiple option defaults to false and when set to true, it enables that multiple implementation are installed for the created service ref.

    We're looking for ways to make it possible to augment services without the need to replace the entire service.

    Typical example of that being the ability to install support for additional targets for the UrlReader service without replacing the service itself. This achieves that by allowing us to define services that can have multiple simultaneous implementation, allowing the UrlReader implementation to depend on such a service to collect all possible implementation of support for external targets:

    // @backstage/backend-defaults

+ export const urlReaderFactoriesServiceRef = createServiceRef<ReaderFactory>({
+   id: 'core.urlReader.factories',
+   scope: 'plugin',
+   multiton: true,
+ });

...

export const urlReaderServiceFactory = createServiceFactory({
  service: coreServices.urlReader,
  deps: {
    config: coreServices.rootConfig,
    logger: coreServices.logger,
+   factories: urlReaderFactoriesServiceRef,
  },
-  async factory({ config, logger }) {
+  async factory({ config, logger, factories }) {
    return UrlReaders.default({
      config,
      logger,
+     factories,
    });
  },
});

    With that, you can then add more custom UrlReader factories by installing more implementations of the urlReaderFactoriesServiceRef in your backend instance. Something like:

    // packages/backend/index.ts
import { createServiceFactory } from '@backstage/backend-plugin-api';
import { urlReaderFactoriesServiceRef } from '@backstage/backend-defaults';
...

backend.add(createServiceFactory({
  service: urlReaderFactoriesServiceRef,
  deps: {},
  async factory() {
    return CustomUrlReader.factory;
  },
}));

...

  • c99c620: BREAKING Removed the following deprecated types:

    • ServiceRefConfig use ServiceRefOptions
    • RootServiceFactoryConfig use RootServiceFactoryOptions
    • PluginServiceFactoryConfig use PluginServiceFactoryOptions

Patch Changes

  • 6061061: Added createBackendFeatureLoader, which can be used to create an installable backend feature that can in turn load in additional backend features in a dynamic way.
  • ba9abf4: The SchedulerService now allows tasks with frequency: { trigger: 'manual' }. This means that the task will not be scheduled, but rather run only when manually triggered with SchedulerService.triggerTask.

  • 8b13183: Added createBackendFeatureLoader, which can be used to programmatically select and install backend features.

    A feature loader can return an list of features to be installed, for example in the form on an Array or other for of iterable, which allows for the loader to be defined as a generator function. Both synchronous and asynchronous loaders are supported.

    Additionally, a loader can depend on services in its implementation, with the restriction that it can only depend on root-scoped services, and it may not override services that have already been instantiated.

    const searchLoader = createBackendFeatureLoader({
  deps: {
    config: coreServices.rootConfig,
  },
  *loader({ config }) {
    // Example of a custom config flag to enable search
    if (config.getOptionalString('customFeatureToggle.search')) {
      yield import('@backstage/plugin-search-backend/alpha');
      yield import('@backstage/plugin-search-backend-module-catalog/alpha');
      yield import('@backstage/plugin-search-backend-module-explore/alpha');
      yield import('@backstage/plugin-search-backend-module-techdocs/alpha');
    }
  },
});

  • ddde5fe: Fixed a type issue where plugin and modules depending on multiton services would not receive the correct type.

  • f011d1b: fix typo in getPluginRequestToken comments
  • Updated dependencies

0.8.0-next.3

Patch Changes

0.8.0-next.2

Minor Changes

  • 7c5f3b0: The createServiceRef function now accepts a new boolean multiple option. The multiple option defaults to false and when set to true, it enables that multiple implementation are installed for the created service ref.

    We're looking for ways to make it possible to augment services without the need to replace the entire service.

    Typical example of that being the ability to install support for additional targets for the UrlReader service without replacing the service itself. This achieves that by allowing us to define services that can have multiple simultaneous implementation, allowing the UrlReader implementation to depend on such a service to collect all possible implementation of support for external targets:

    // @backstage/backend-defaults

+ export const urlReaderFactoriesServiceRef = createServiceRef<ReaderFactory>({
+   id: 'core.urlReader.factories',
+   scope: 'plugin',
+   multiton: true,
+ });

...

export const urlReaderServiceFactory = createServiceFactory({
  service: coreServices.urlReader,
  deps: {
    config: coreServices.rootConfig,
    logger: coreServices.logger,
+   factories: urlReaderFactoriesServiceRef,
  },
-  async factory({ config, logger }) {
+  async factory({ config, logger, factories }) {
    return UrlReaders.default({
      config,
      logger,
+     factories,
    });
  },
});

    With that, you can then add more custom UrlReader factories by installing more implementations of the urlReaderFactoriesServiceRef in your backend instance. Something like:

    // packages/backend/index.ts
import { createServiceFactory } from '@backstage/backend-plugin-api';
import { urlReaderFactoriesServiceRef } from '@backstage/backend-defaults';
...

backend.add(createServiceFactory({
  service: urlReaderFactoriesServiceRef,
  deps: {},
  async factory() {
    return CustomUrlReader.factory;
  },
}));

...

Patch Changes

  • 6061061: Added createBackendFeatureLoader, which can be used to create an installable backend feature that can in turn load in additional backend features in a dynamic way.
  • ba9abf4: The SchedulerService now allows tasks with frequency: { trigger: 'manual' }. This means that the task will not be scheduled, but rather run only when manually triggered with SchedulerService.triggerTask.

  • 8b13183: Added createBackendFeatureLoader, which can be used to programmatically select and install backend features.

    A feature loader can return an list of features to be installed, for example in the form on an Array or other for of iterable, which allows for the loader to be defined as a generator function. Both synchronous and asynchronous loaders are supported.

    Additionally, a loader can depend on services in its implementation, with the restriction that it can only depend on root-scoped services, and it may not override services that have already been instantiated.

    const searchLoader = createBackendFeatureLoader({
  deps: {
    config: coreServices.rootConfig,
  },
  *loader({ config }) {
    // Example of a custom config flag to enable search
    if (config.getOptionalString('customFeatureToggle.search')) {
      yield import('@backstage/plugin-search-backend/alpha');
      yield import('@backstage/plugin-search-backend-module-catalog/alpha');
      yield import('@backstage/plugin-search-backend-module-explore/alpha');
      yield import('@backstage/plugin-search-backend-module-techdocs/alpha');
    }
  },
});

  • Updated dependencies

0.7.1-next.1

Patch Changes

0.7.1-next.0

Patch Changes

0.7.0

Minor Changes

  • 36f91e8: BREAKING: The PermissionsService no longer supports passing the deprecated token option, and the request options are now required.

Patch Changes

  • 53ced70: Added a new Root Health Service which adds new endpoints for health checks.
  • 083eaf9: Fix bug where ISO durations could no longer be used for schedules

  • 062c01c: Deprecated the ability to define options for service factories through createServiceFactory. In the future all service factories will return a plain ServiceFactory object, rather than allowing users to pass options to the factory. To allow for customization of a service implementation one can instead export one or a few building blocks that allows for simple re-implementation of the service instead.

    For example, instead of:

    export const fooServiceFactory = createServiceFactory<FooService>(
  (options?: { bar: string }) => ({
    service: fooServiceRef,
    deps: { logger: coreServices.logger },
    factory({ logger }) {
      return {
        // Implementation of the foo service using the `bar` option.
      };
    },
  }),
);

    We instead encourage service implementations to provide an easy to use API for re-implementing the service for advanced use-cases:

    /** @public */
export class DefaultFooService implements FooService {
  static create(options: { bar: string; logger: LoggerService }) {
    return new DefaultFooService(options.logger, options.bar ?? 'default');
  }

  private constructor(
    private readonly logger: string,
    private readonly bar: string,
  ) {}

  // The rest of the implementation
}

    A user that wishes to customize the service can then easily do so by defining their own factory:

    export const customFooServiceFactory = createServiceFactory<FooService>({
  service: fooServiceRef,
  deps: { logger: coreServices.logger },
  factory({ logger }) {
    return DefaultFooService.create({ logger, bar: 'baz' });
  },
});

    This is of course more verbose than the previous solution where the factory could be customized through fooServiceFactory({ bar: 'baz' }), but this is a simplified which in practice should be using static configuration instead.

    In cases where the old options patterns significantly improves the usability of the service factory, the old pattern can still be implemented like this:

    const fooServiceFactoryWithOptions = (options?: { bar: string }) =>
  createServiceFactory<FooService>({
    service: fooServiceRef,
    deps: { logger: coreServices.logger },
    factory({ logger }) {
      return {
        // Implementation of the foo service using the `bar` option.
      };
    },
  });

export const fooServiceFactory = Object.assign(
  fooServiceFactoryWithOptions,
  fooServiceFactoryWithOptions(),
);

    This change is being made because the ability to define an options callback encourages bad design of services factories. When possible, a service should be configurable through static configuration, and the existence of options may discourage that. More importantly though, the existing options do not work well with the dependency injection system of services, which is a problem for callbacks an other more advanced options. This lead to a bad pattern where only a few explicit dependencies where made available in callbacks, rather than providing an API that allowed simple re-implementation of the service with full access to dependency injection.

    A separate benefit of this change is that it simplifies the TypeScript types in a way that allows TypeScript to provide a much better error message when a service factory doesn't properly implement the service interface.

  • fe47a3e: All service config types were renamed to option types in order to standardize frontend and backend create* function signatures:

    • The ServiceRefConfig type was renamed toServiceRefOptions;
    • The RootServiceFactoryConfig type was renamed to RootServiceFactoryOptions;
    • The PluginServiceFactoryConfig type was renamed to PluginServiceFactoryOptions

  • Updated dependencies

0.6.22-next.1

Patch Changes

0.6.21-next.0

Patch Changes

0.6.19

Patch Changes

  • 78a0b08: DEPRECATION: You should no longer do a function call on backend features when adding them to backends. The support for doing that is deprecated, and you should remove all trailing () parentheses after plugins and modules where you add them to your backend or test backends (e.g. when using startTestBackend).

    The background for this is that createBackendPlugin and createBackendModule function now effectively return a BackendFeature rather than a () => BackendFeature. This is part of the cleanup efforts for New Backend System 1.0. In the short run this is non-breaking because the feature type has been given a callback signature that returns itself. But we strongly recommend that you remove all now-redundant calls made to feature objects, because that callback signature will be removed in a future release.

    Service factories are still callbacks at this point.

    Example change:

     await startTestBackend({
   features: [
     eventsServiceFactory(), // service - stays unchanged
-    catalogModuleBitbucketCloudEntityProvider(), // module - remove parentheses
+    catalogModuleBitbucketCloudEntityProvider,

  • 9bdc3e8: In tests, return null rather than throwing an error when trying to get the ExtensionPoint.T property, so that tests asserting the property are not easily broken.

  • 9e63318: Added an optional accessRestrictions to external access service tokens and service principals in general, such that you can limit their access to certain plugins or permissions.
  • 3aa3fc7: Marked the TokenManagerService and IdentityService types as deprecated

  • b2ee7f3: Deprecated all of the UrlReader related type names and replaced them with prefixed versions. Please update your imports.

    • ReadTreeOptions was renamed to UrlReaderServiceReadTreeOptions
    • ReadTreeResponse was renamed to UrlReaderServiceReadTreeResponse
    • ReadTreeResponseDirOptions was renamed to UrlReaderServiceReadTreeResponseDirOptions
    • ReadTreeResponseFile was renamed to UrlReaderServiceReadTreeResponseFile
    • ReadUrlResponse was renamed to UrlReaderServiceReadUrlResponse
    • ReadUrlOptions was renamed to UrlReaderServiceReadUrlOptions
    • SearchOptions was renamed to UrlReaderServiceSearchOptions
    • SearchResponse was renamed to UrlReaderServiceSearchResponse
    • SearchResponseFile was renamed to UrlReaderServiceSearchResponseFile

  • 9539a0b: Improved coreServices doc comments

  • 6551b3d: Moved the declaration of the SchedulerService here, along with prefixed versions of all of the types it depends on, from @backstage/backend-tasks
  • 0665b7e: Renamed BackendPluginConfig, BackendModuleConfig, and ExtensionPointConfig respectively to CreateBackendPluginOptions, CreateBackendModuleOptions, and CreateExtensionPointOptions to standardize frontend and backend factories signatures.
  • 1779188: Start using the isDatabaseConflictError helper from the @backstage/backend-plugin-api package in order to avoid dependency with the soon to deprecate @backstage/backend-common package.
  • Updated dependencies

0.6.19-next.3

Patch Changes

  • 9bdc3e8: In tests, return null rather than throwing an error when trying to get the ExtensionPoint.T property, so that tests asserting the property are not easily broken.

  • b2ee7f3: Deprecated all of the UrlReader related type names and replaced them with prefixed versions. Please update your imports.

    • ReadTreeOptions was renamed to UrlReaderServiceReadTreeOptions
    • ReadTreeResponse was renamed to UrlReaderServiceReadTreeResponse
    • ReadTreeResponseDirOptions was renamed to UrlReaderServiceReadTreeResponseDirOptions
    • ReadTreeResponseFile was renamed to UrlReaderServiceReadTreeResponseFile
    • ReadUrlResponse was renamed to UrlReaderServiceReadUrlResponse
    • ReadUrlOptions was renamed to UrlReaderServiceReadUrlOptions
    • SearchOptions was renamed to UrlReaderServiceSearchOptions
    • SearchResponse was renamed to UrlReaderServiceSearchResponse
    • SearchResponseFile was renamed to UrlReaderServiceSearchResponseFile

  • Updated dependencies

0.6.19-next.2

Patch Changes

0.6.19-next.1

Patch Changes

  • 9e63318: Added an optional accessRestrictions to external access service tokens and service principals in general, such that you can limit their access to certain plugins or permissions.
  • 0665b7e: Renamed BackendPluginConfig, BackendModuleConfig, and ExtensionPointConfig respectively to CreateBackendPluginOptions, CreateBackendModuleOptions, and CreateExtensionPointOptions to standardize frontend and backend factories signatures.
  • Updated dependencies

0.6.19-next.0

Patch Changes

0.6.18

Patch Changes

0.6.18-next.1

Patch Changes

0.6.18-next.0

Patch Changes

0.6.17

Patch Changes

0.6.17-next.1

Patch Changes

0.6.17-next.0

Patch Changes

0.6.16

Patch Changes

0.6.15

Patch Changes

0.6.14

Patch Changes

0.6.14-next.2

Patch Changes

0.6.14-next.1

Patch Changes

0.6.13-next.0

Patch Changes

0.6.10

Patch Changes

0.6.10-next.3

Patch Changes

0.6.10-next.2

Patch Changes

0.6.10-next.1

Patch Changes

0.6.10-next.0

Patch Changes

0.6.9

Patch Changes

0.6.9-next.2

Patch Changes

0.6.9-next.1

Patch Changes

0.6.9-next.0

Patch Changes

0.6.8

Patch Changes

0.6.8-next.3

Patch Changes

0.6.8-next.2

Patch Changes

0.6.8-next.1

Patch Changes

0.6.8-next.0

Patch Changes

0.6.7

Patch Changes

0.6.7-next.2

Patch Changes

0.6.7-next.1

Patch Changes

0.6.7-next.0

Patch Changes

0.6.6

Patch Changes

0.6.6-next.2

Patch Changes

0.6.5-next.1

Patch Changes

0.6.5-next.0

Patch Changes

0.6.3

Patch Changes

0.6.3-next.3

Patch Changes

0.6.3-next.2

Patch Changes

0.6.3-next.1

Patch Changes

0.6.2-next.0

Patch Changes

0.6.0

Minor Changes

  • c49785f00cab: BREAKING: It is no longer possible to declare options as being required with createServiceFactory.
  • 629cbd194a87: BREAKING: Renamed coreServices.config to coreServices.rootConfig.
  • 51987dbdaf87: BREAKING: Removed the ability to define options for plugins and modules. Existing options should be migrated to instead use either static configuration or extension points.
  • d008aefef808: BREAKING: Removing shared environments concept from the new experimental backend system.

Patch Changes

  • c7aa4ff1793c: Allow modules to register extension points.
  • cc9256a33bcc: Added new experimental featureDiscoveryServiceRef, available as an /alpha export.

  • 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);

  • Updated dependencies

0.6.0-next.2

Patch Changes

0.6.0-next.1

Minor Changes

  • 629cbd194a87: BREAKING: Renamed coreServices.config to coreServices.rootConfig.
  • d008aefef808: BREAKING: Removing shared environments concept from the new experimental backend system.

Patch Changes

0.5.5-next.0

Patch Changes

0.5.4

Patch Changes

0.5.4-next.0

Patch Changes

0.5.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.2

Patch Changes

0.5.2-next.1

Patch Changes

0.5.2-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

  • c1ee073a82b: Added lastModifiedAt field on UrlReaderService responses and a lastModifiedAfter option to UrlReaderService.readUrl.

Patch Changes

0.4.1-next.2

Patch Changes

0.4.1-next.1

Patch Changes

0.4.1-next.0

Patch Changes

0.4.0

Minor Changes

  • e716946103: BREAKING: Split out the hook for both lifecycle services so that the first parameter of addShutdownHook is the hook function, and the second is the options.
  • 0ff03319be: BREAKING: The plugin ID option passed to createBackendPlugin is now pluginId, rather than just id. This is to make it match createBackendModule more closely.
  • 71a5ec0f06: BREAKING: Switched out LogMeta type for JsonObject.
  • 5febb216fe: BREAKING: The CacheService has been changed to remove the indirection of getClient, instead making the CacheClient methods directly available on the CacheService. In order to allow for the creation of clients with default options, there is now a new .withOptions method that must be implemented as part of the service interface.
  • b86efa2d04: Switch ServiceFactory to be an opaque type, keeping only the service field as public API, but also adding a type parameter for the service scope.
  • 610d65e143: Switched BackendFeature to be an opaque type.

Patch Changes

  • 9c9456fd33: Removed the unused TypesToServiceRef type
  • 181c03edb5: Aligned opaque type markers to all use a $type property with namespacing.
  • 725383f69d: Tweaked messaging in the README.
  • ae88f61e00: The register methods passed to createBackendPlugin and createBackendModule now have dedicated BackendPluginRegistrationPoints and BackendModuleRegistrationPoints arguments, respectively. This lets us make it clear on a type level that it's not possible to pass in extension points as dependencies to plugins (should only ever be done for modules). This has no practical effect on code that was already well behaved.
  • Updated dependencies

0.4.0-next.2

Minor Changes

  • e716946103: BREAKING: Split out the hook for both lifecycle services so that the first parameter of addShutdownHook is the hook function, and the second is the options.
  • 0ff03319be: BREAKING: The plugin ID option passed to createBackendPlugin is now pluginId, rather than just id. This is to make it match createBackendModule more closely.
  • 71a5ec0f06: BREAKING: Switched out LogMeta type for JsonObject.
  • 610d65e143: Switched BackendFeature to be an opaque type.

Patch Changes

0.3.2-next.1

Patch Changes

0.3.2-next.0

Patch Changes

0.3.0

Minor Changes

  • 8e06f3cf00: Moved loggerToWinstonLogger to @backstage/backend-common.
  • ecbec4ec4c: Updated all factory function creators to accept options as a top-level callback rather than extra parameter to the main factory function.

Patch Changes

  • 6cfd4d7073: Added RootLifecycleService and rootLifecycleServiceRef, as well as added a logger option to the existing LifecycleServiceShutdownHook.
  • ecc6bfe4c9: Added ServiceFactoryOrFunction type, for use when either a ServiceFactory or () => ServiceFactory can be used.
  • 5b7bcd3c5e: Added createSharedEnvironment for creating a shared environment containing commonly used services in a split backend setup of the backend.
  • 02b119ff93: Added a new rootHttpRouterServiceRef and RootHttpRouterService interface.
  • 5e2cebe9a3: Migrate UrlReader into this package to gradually remove the dependency on backend-common.
  • 843a0a158c: Added new core identity service.
  • 5437fe488f: Migrated types related to TokenManagerService, CacheService and DatabaseService into backend-plugin-api.
  • 6f02d23b01: Moved PluginEndpointDiscovery type from backend-common to backend-plugin-api.

  • 483e907eaf: The createServiceFactory function has been updated to no longer use a duplicate callback pattern for plugin scoped services. The outer callback is now replaced by an optional createRootContext method. This change was made in order to support TypeScript 4.9, but it also simplifies the API surface a bit, especially for plugin scoped service factories that don't need to create a root context. In addition, the factory and root context functions can now be synchronous.

    A factory that previously would have looked like this:

    createServiceFactory({
  service: coreServices.cache,
  deps: {
    config: coreServices.config,
    plugin: coreServices.pluginMetadata,
  },
  async factory({ config }) {
    const cacheManager = CacheManager.fromConfig(config);
    return async ({ plugin }) => {
      return cacheManager.forPlugin(plugin.getId());
    };
  },
});

    Now instead looks like this:

    createServiceFactory({
  service: coreServices.cache,
  deps: {
    config: coreServices.config,
    plugin: coreServices.pluginMetadata,
  },
  async createRootContext({ config }) {
    return CacheManager.fromConfig(config);
  },
  async factory({ plugin }, manager) {
    return manager.forPlugin(plugin.getId());
  },
});

    Although in many cases the createRootContext isn't needed, for example:

    createServiceFactory({
  service: coreServices.logger,
  deps: {
    rootLogger: coreServices.rootLogger,
    plugin: coreServices.pluginMetadata,
  },
  factory({ rootLogger, plugin }) {
    return rootLogger.child({ plugin: plugin.getId() });
  },
});

  • 16054afdec: Documented coreServices an all of its members.

  • 0e63aab311: Updated the RootLoggerService to also have an addRedactions method.
  • 62b04bb865: Updates all create* methods to simplify their type definitions and ensure they all have configuration interfaces.
  • Updated dependencies

0.3.0-next.1

Minor Changes

  • 8e06f3cf00: Moved loggerToWinstonLogger to @backstage/backend-common.

Patch Changes

  • ecc6bfe4c9: Added ServiceFactoryOrFunction type, for use when either a ServiceFactory or () => ServiceFactory can be used.
  • 02b119ff93: Added a new rootHttpRouterServiceRef and RootHttpRouterService interface.
  • 5437fe488f: Migrated types related to TokenManagerService, CacheService and DatabaseService into backend-plugin-api.
  • 16054afdec: Documented coreServices an all of its members.
  • 62b04bb865: Updates all create* methods to simplify their type definitions and ensure they all have configuration interfaces.
  • Updated dependencies

0.2.1-next.0

Patch Changes

0.2.0

Minor Changes

  • 884d749b14: BREAKING: All core service references are now exported via a single coreServices object. For example, the loggerServiceRef is now accessed via coreServices.logger instead.
  • a025190552: BREAKING: All service interfaces are now suffixed with *Service.

Patch Changes

0.2.0-next.3

Patch Changes

0.2.0-next.2

Minor Changes

  • 884d749b14: BREAKING: All core service references are now exported via a single coreServices object. For example, the loggerServiceRef is now accessed via coreServices.logger instead.

Patch Changes

0.1.5-next.1

Patch Changes

0.1.5-next.0

Patch Changes

0.1.4

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.2

Patch Changes

0.1.3-next.1

Patch Changes

0.1.3-next.0

Patch Changes

0.1.2

Patch Changes

  • 2c57c0c499: Made ApiRef.defaultFactory internal.
  • 91eed37a39: Updated createBackendPlugin and createBackendModule to properly forward lack of options.
  • 409ed984e8: Service are now scoped to either 'plugin' or 'root' scope. Service factories have been updated to provide dependency instances directly rather than factory functions.
  • eef91a2558: Simplified the ServiceFactory type and removed AnyServiceFactory.
  • 854ba37357: The createServiceFactory method has been updated to return a higher-order factory that can accept options.
  • 68513f169a: When defining a new ServiceRef you can now also include a defaultFactory, which will be used to construct instances of the service in case there is no explicit factory defined.
  • Updated dependencies

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

  • 0599732ec0: Refactored experimental backend system with new type names.
  • 34c2f5aca1: The factory returned by createBackendPlugin and createBackendModule no longer require a parameter to be passed if the options are optional.
  • Updated dependencies

0.1.1-next.0

Patch Changes

0.1.0

Minor Changes

  • 91c1d12123: Introduced new package for creating backend plugins using the new alpha backend plugin framework. This package is still considered EXPERIMENTAL and things will change without warning. Do not use this for production.

Patch Changes

0.1.0-next.0

Minor Changes

  • 91c1d12123: Introduced new package for creating backend plugins using the new alpha backend plugin framework. This package is still considered EXPERIMENTAL and things will change without warning. Do not use this for production.

Patch Changes