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.
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>
fromreact-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’suseApi
. - 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.