> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/streamline/plugins/backstage-migration.md).

# Migrating Backstage plugins to Cortex

This guide covers how to migrate Backstage plugins to Cortex.

### Step 1: Create a Cortex plugin code repository

Follow the steps in Cortex's [Creating a plugin](/streamline/plugins/creating-plugins.md) documentation to create a Cortex plugin code repository.

### 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 \`\` 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](https://docs.cortex.io/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.