Skip to main content

Migrating Backstage plugins to Cortex

This guide covers how to migrate Backstage plugins to Cortex.

First, use the built-in plugin template in the Scaffolder to create a Cortex plugin.

In the repository, copy/paste (and merge, when appropriate) the Backstage source code into src/.

  • Favor the Cortex code if you encounter any conflicts.
  • Replace the Backstage eslint config with the Cortex config.
tip

Later you’ll have to run eslint src --fix and will likely have to manually fix some lint settings.

Delete remaining Backstage registration files like plugin.ts and index.ts. Do not delete routes.ts — that will be removed in a later step.

Remove all @backstage/ package dependencies except for @backstage/core-components. Then iterate over them (e.g. yarn remove @backstage/package-name @backstage/package-name-2).

Switch the plugin to use react-router directly instead of through the Backstage abstraction.

  • Replace Backstage route usage with react-router/react-router-dom.
  • Use <MemoryRouter> from react-router-dom for the provider.
  • Remove routes.ts.

Replace the Backstage entity usage with Cortex entity usage. This will likely be the most substantial step, as there’s no complete 1:1 mapping between the two data models. You will likely need to fetch additional data from the Cortex API as needed.

Finally, replace the data fetching layer.

  • Replace Backstage API refs with simple classes or objects.
  • Use fetch() directly instead of Backstage’s useApi.
  • Remove errorApi usage (Cortex has no equivalent).

Additional testing is recommended, as there will likely be some final clean-ups to ensure everything is working as expected.