# 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](https://docs.cortex.io/streamline/plugins/creating-plugins) 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://app.gitbook.com/o/RD51qiGImxmmq8NjALb1/s/nPgS8L9MAPtoOtdWdeDp/) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/streamline/plugins/backstage-migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.