🙏 Help wanted: Deprecate old plugin backends

[jhaals]

TL;DR make sure that createRouter and other exports are marked as deprecated. For the majority of packages there should only be one default export of the backend plugin itself. The @backstage/backend-common package is deprecated so usages of that package should also be avoided.

Backstage’s new backend system is ready for general use; we are now asking for a full transition over to the new backend system, which involves stop supporting the old system. By old system we mean having exports of createRouter and related types. There should only need to be one export like this in the backend plugin’s index.ts file.

How do I help?

Run yarn backstage-repo-tools lint legacy-backend-exports in the repository to get a full report of packages that require action.

Phase 1

Ensure that plugins contain a default export

Ensure that there is a default export of the backend plugin in index.ts, see this example.

If the plugin previously had a default export in plugins/<plugin-id>/src/alpha.ts, make sure that that export is deprecated and that the default export is moved to the non-alpha index.ts instead.

Deprecate createRouter, RouterOptions and similar types.

Here’s an example of a plugin’s createRouter being deprecated.

/**
+ * @deprecated Please migrate to the new backend system as this will be removed in the future.
 * @public
 * */
export async function createRouter(
  options: RouterOptions,
): Promise<express.Router> {

Phase 2

Remove deprecated exports

Ensure that deprecations have been out for at one mainline release before proceeding with removal of all deprecated exports. Removing exports from one release to another is not recommended

The complete migration story for a backend plugin (including deprecation) is also mentioned in our docs.

If you take on migrating a backend plugin, feel free to add a comment in this issue to avoid duplicate work.

We plan to have all createRouter exports and @backstage/backend-common usages removed by the end of this year. Your help would be much appreciated!

[avila-m-6]

Hey, I have started to work on plugins/user-settings-backend in #26584

[kenilkevadiya]

Hey @Rugvip, Can I work on this issue?

[itsalam]

Just started working on the app-backend plugin. Since createRootLogger is used for much of the test cases in the plugins, should this be swapped out for what's found here, and how?

[Rugvip]

@kenilkevadiya sure! This is completely open to contributions 🙏

@itsalam that particular call that you're linking to can hopefully be removed alltogether as the side effect of it should no longer be needed. More generally the root logger can be replaced by the equivalent mock service: https://backstage.io/docs/backend-system/building-plugins-and-modules/testing/#mock-services

[jescalada]

Hello @Rugvip, I'm working on the catalog-backend-module-puppetdb, which doesn't have a /plugin directory with the plugin we would normally export by default. It has a default export in the alpha.ts file as follows:

export { default } from './module';

In this case, do we simply deprecate the alpha.ts export and add the same line to the index.ts? The index.ts file is exporting everything in the /providers and /puppet directories, and I'm not sure if we want to limit or change what gets exported to the users.

Thank you!

[knowacki23]

I believe that getting rid of @backstage/backend-common package usages would also reduce occurrences of Vulnerability (CVE-2024-21534)

There is a vulnerability with severity 9.3 in jsonpath-plus <= 10.0.7. See https://security.snyk.io/vuln/SNYK-JS-JSONPATHPLUS-7945884

@backstage/backend-common package is using @kubernetes/client-node package which is using vulnerable jsonpath-plus@npm:7.2.0

[patroswastik]

I would like to work on this

[patroswastik]

I see that the command yarn backstage-repo-tools lint legacy-backend-exports does is showing ❌ createRouter is NOT deprecated for those plugins, in which createRouter has already been deprecated. I've created an issue (#27668) with additional details about this problem.