Skip to main content

Migrating Backstage plugins to Cortex

This guide covers how to migrate Backstage plugins to Cortex.

Step 1: Create a Cortex plugin​

  1. In the main nav of Cortex, navigate to Tools > Scaffolder.
  2. Select the Cortex Plugin Template, then click Continue.
  3. Fill in the form, then click Create service.

Step 2: Configure the repository​

  1. 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.
      • Note: Later in this process, you will need to run eslint src --fix and may have to manually fix some lint settings.
  2. Delete the remaining Backstage registration files, such as plugin.ts and index.ts.
    • Do not delete routes.ts as that will be removed in a later step.
  3. Remove all @backstage/ package dependencies (except for @backstage/core-components) then iterate over them by running a command similar to the following: yarn remove @backstage/package-name @backstage/package-name-2.

Step 3: Switch the plugin to use react-router​

In this step, you will switch to using react-router directly instead of through the Backstage abstraction.

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

Step 4: Replace the Backstage entity usage with Cortex entity usage​

Note that there is no complete 1:1 mapping between the two data models. You will likely need to fetch additional data from the Cortex API as needed.

Step 5: Replace the data fetching layer​

  1. Replace Backstage API refs with simple classes or objects.
  2. Use fetch() directly instead of Backstage’s useApi.
  3. 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.