# @rootly/backstage-plugin-common

> Common components for Rootly plugins for Backstage

Latest version **1.6.0** (published 2026-10-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @rootly/backstage-plugin-common
pnpm add @rootly/backstage-plugin-common
yarn add @rootly/backstage-plugin-common
bun add @rootly/backstage-plugin-common
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.6.0 |
| Published | 2026-10-11 |
| First published | 2024-08-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22 |
| Dependencies | 2 |
| Unpacked size | 224.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Maintainers | alex-rootly, quentin-rootly |
| Keywords | backstage, plugin, rootly |

## Links

- npm: https://www.npmjs.com/package/@rootly/backstage-plugin-common
- Repository: https://github.com/rootlyhq/backstage-plugin-common
- Issues: https://github.com/rootlyhq/backstage-plugin-common/issues
- npm.io page: https://npm.io/package/@rootly/backstage-plugin-common

## Dependencies (2)

- [qs](https://npm.io/package/qs.md) ^6.16.0
- [@backstage/catalog-model](https://npm.io/package/@backstage/catalog-model.md) ^1.10.1

## Recent versions

- 1.6.0 (latest) — 2026-10-11
- 1.5.0 — 2026-10-11
- 1.4.1 — 2026-07-30
- 1.4.0 — 2026-06-03
- 1.3.0 — 2026-05-01
- 1.2.0 — 2026-04-24
- 1.1.1 — 2026-04-11
- 1.1.0 — 2025-10-08
- 1.0.0 — 2025-06-11
- 1.0.0-beta.6 — 2024-10-26
- 1.0.0-beta.5 — 2024-09-10
- 1.0.0-beta.4 — 2024-09-10
- 1.0.0-beta.3 — 2024-08-29
- 1.0.0-beta.2 — 2024-08-28

## README

# Rootly plugin for Backstage

[![npm version](https://badge.fury.io/js/@rootly%2Fbackstage-plugin-common.svg)](https://badge.fury.io/js/@rootly%2Fbackstage-plugin-common)
[![License](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/MIT)

The Rootly plugin is a frontend plugin that displays Rootly services, incidents in Backstage. The plugin includes three components that can be integrated into Backstage:

- The `RootlyPage` routable extension component which produces a standalone page with the following capabilities:

  - View and search a list of entities
  - View and search a list of services
  - View and search a list of functionalities
  - View and search a list of teams
  - View and search a list of incidents
  - View and search a list of catalog entities (with catalog selector)

- The `RootlyOverviewCard` component which produces a summary of your entity with incidents over last 30 days and ongoing incidents. Also supports catalog entities with name, description, and properties display.

- The `RootlyIncidentsPage` component which produces a dedicated page within your entity with details about ongoing and past incidents.

You can link and import entities in rootly services, functionalities, teams, and catalog entities through Backstage Web UI or through annotations.

## Installation

### Creating an Rootly API key

Because of the features provided by the plugin, an API key with full access to your Rootly domain is required.

- Read access on services is needed to list services, write access to link entities to services.
- Read access on functionalities is needed to list functionalities, write access to link entities to functionalities.
- Read access on incidents needed to list incidents.

1. Go to `Profile` -> `Manage API Keys`.

2. Click on `Generate New API Key` button.

3. Copy the key.

   ![Creating Api Key](./docs/rootly-creating-api-key.png)

### Backstage Setup

Add the plugin to your frontend app:

```bash
yarn add --cwd packages/app @rootly/backstage-plugin
```

Add the plugin to your backend app:

```bash
yarn add --cwd packages/backend @rootly/backstage-plugin-entity-processor
```

Configure the plugin in `app-config.yaml`. The proxy endpoint described below will allow the frontend
to authenticate with Rootly without exposing your API key to users.

```yaml
# app-config.yaml

# Rootly single-organization configuration example
rootly:
  rootly-main:
    proxyPath: /rootly/api
    apiHost: https://rootly.com # Optional. Defaults to https://rootly.com

# Rootly multi-organizations example
rootly:
  rootly-main:
    isDefault: true
    proxyPath: /rootly/api
  rootly-sandbox:
    proxyPath: /rootly-sandbox/api

...

proxy:
  endpoints:
    '/rootly/api':
      target: 'https://api.rootly.com'
      headers:
        Authorization: Bearer ${ROOTLY_MAIN_TOKEN}
    '/rootly-sandbox/api':
      target: 'https://api.rootly.com'
      headers:
        Authorization: Bearer ${ROOTLY_SANDBOX_TOKEN}
```

### Annotations

Available annotations are the following:

```yaml
rootly.com/organization-id: rootly # Optional if you use Rootly multi organizations.
rootly.com/service-id: 7a328a08-6701-445e-a1ad-ca2fb913ed1e # Use service-id or service-slug. Not both.
rootly.com/service-name: ElastiSearch Staging
rootly.com/service-slug: elasticsearch-staging # Use service-id or service-slug. Not both.
rootly.com/service-auto-import: enabled # This will auto import the entity as a rootly service if we don't find any.
rootly.com/functionality-id: 7a328a08-694f4e1b-abbc-4cf7-bba0-a403df30ed88 # Use functionality-id or functionality-slug. Not both.
rootly.com/functionality-name: Login
rootly.com/functionality-slug: login # Use functionality-id or functionality-slug. Not both.
rootly.com/functionality-auto-import: enabled # This will auto import the entity as a rootly functionality if we don't find any.
rootly.com/team-id: 39e77dcc-e056-4849-9dda-a362b2413e5c # Use team-id or team-slug. Not both.
rootly.com/team-slug: infrastucture # Use team-id or team-slug. Not both.
rootly.com/team-name: Infrastucture # Use team-id or team-slug. Not both.
rootly.com/team-slug: infrastucture # Use team-id or team-slug. Not both.
rootly.com/team-auto-import: enabled # This will auto import the entity as a rootly team if we don't find any.
rootly.com/catalog-entity-id: 7a328a08-6701-445e-a1ad-ca2fb913ed1e # Use catalog-entity-id or catalog-entity-slug. Not both.
rootly.com/catalog-entity-name: Enterprise
rootly.com/catalog-entity-slug: enterprise # Use catalog-entity-id or catalog-entity-slug. Not both.
rootly.com/catalog-entity-auto-import: enabled # This will auto import the entity as a rootly catalog entity if we don't find any.
rootly.com/catalog-id: 7a328a08-6701-445e-a1ad-ca2fb913ed1e # Required for auto-import. The catalog to create the entity in.
rootly.com/catalog-slug: customer-tier # Alternative to catalog-id. The catalog slug to find or create.
rootly.com/catalog-description: Customer pricing tiers # Optional. Description for the catalog when auto-creating.
```

#### Attribute pass-through annotations

You can set any Rootly API attribute on services, functionalities, teams, and catalog entities using the `attr` prefix:

```yaml
rootly.com/service-attr-<api_attribute>: "value"
rootly.com/functionality-attr-<api_attribute>: "value"
rootly.com/team-attr-<api_attribute>: "value"
rootly.com/catalog-entity-attr-<api_attribute>: "value"
```

Value coercion rules:
- `"true"` / `"false"` → boolean
- Values starting with `[` or `{` → parsed as JSON (arrays, objects)
- Everything else → plain string

Example:

```yaml
annotations:
  rootly.com/service-slug: my-service
  rootly.com/service-auto-import: enabled
  rootly.com/service-attr-color: "#FF5733"
  rootly.com/service-attr-notify_emails: '["oncall@company.com","team@company.com"]'
  rootly.com/service-attr-slack_channels: '[{"id":"C01ABC123","name":"oncall-channel"}]'
  rootly.com/service-attr-show_uptime: "true"
  rootly.com/service-attr-github_repository_name: "myorg/my-service"
```

Hardcoded fields (`name`, `description`, `backstage_id`, `pagerduty_id`, `owner_group_ids`) always take precedence and cannot be overridden via pass-through annotations.

#### Custom catalog property annotations

You can populate custom catalog properties (metadata fields) on services and catalog entities:

```yaml
rootly.com/service-property-<slug_or_id>: "value"
rootly.com/catalog-entity-property-<slug_or_id>: "value"
```

The key after the prefix is the catalog property slug or UUID. The value is passed as-is to the Rootly API.

Example:

```yaml
annotations:
  rootly.com/service-slug: my-service
  rootly.com/service-property-impact-level: "critical"
  rootly.com/service-property-slack-channel: '{"id":"C01FE4P7458","name":"service-channel"}'
```

#### Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: elasticsearch-staging
  description: |
    elasticsearch-staging
  annotations:
    github.com/project-slug: backstage/backstage
    backstage.io/techdocs-ref: dir:.
    lighthouse.com/website-url: https://rootly.com
    rootly.com/service-slug: elasticsearch-staging
    pagerduty.com/service-id: <sample-service-service-id>
spec:
  type: grpc
  owner: guests
  lifecycle: experimental
```

#### Catalog Entity Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: enterprise-tier
  description: Enterprise customer tier
  annotations:
    rootly.com/catalog-entity-slug: enterprise-tier
    rootly.com/catalog-entity-auto-import: enabled
    rootly.com/catalog-slug: customer-tier
    rootly.com/catalog-description: Customer pricing tiers
spec:
  type: service
  owner: guests
  lifecycle: production
```

### Global

#### `RootlyPage` component

![Rootly page](./docs/rootly-global-page.png)

Expose the Rootly global page:

```jsx
// packages/app/src/App.tsx
import { RootlyPage } from '@rootly/backstage-plugin';

// ...
const AppRoutes = () => (
  <FlatRoutes>
    // ...
    <Route path="/rootly" element={<RootlyPage />} />
    //{' '}
    <Route
      path="/rootly-sandbox"
      element={<RootlyPage organizationId="rootly-sandbox" />}
    />
    // ...
  </FlatRoutes>
);
```

Add a link to the sidebar:

```jsx
// packages/app/src/components/Root/Root.tsx
import ExtensionIcon from '@material-ui/icons/ExtensionIcon';

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      // ...
      <SidebarItem icon={ExtensionIcon} to="rootly" text="Rootly" />
      // <SidebarItem icon={ExtensionIcon} to="rootly-sandbox" text="Rootly Sandbox" />
      // ...
    </Sidebar>
  </SidebarPage>
);
```

### Entity

#### `RootlyOverviewCard` component

![Rootly overview page](./docs/rootly-entity-overview.png)

```jsx
// packages/app/src/components/catalog/EntityPage.tsx
import {
  RootlyOverviewCard,
  isRootlyAvailable,
} from '@rootly/backstage-plugin';

// For a service
const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    // ...
    <EntitySwitch>
      <EntitySwitch.Case if={isRootlyAvailable}>
        <Grid item sm={6}>
          <RootlyOverviewCard />
        </Grid>
      </EntitySwitch.Case>
    </EntitySwitch>
    // ...
  </Grid>
);
```

#### `RootlyIncidentsPage` component

![Rootly incidents page](./docs/rootly-incidents-page.png)

```jsx
// packages/app/src/components/catalog/EntityPage.tsx
import { RootlyIncidentsPage } from '@rootly/backstage-plugin';

// ...
const websiteEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>

    // ...

    <EntityLayout.Route path="/docs" title="Docs">
      <EntityTechdocsContent />
    </EntityLayout.Route>

    <EntityLayout.Route path="/rootly" title="Rootly">
      <EntitySwitch.Case if={isRootlyAvailable}>
        <Grid item sm={6}>
          <RootlyIncidentsPage />
        </Grid>
        // Rootly Multi Organization
        // <Grid item sm={6}>
        //   <RootlyIncidentsPage organizationId="rootly-sandbox" />
        // </Grid>
      </EntitySwitch.Case>
    </EntityLayout.Route>
  </EntityLayout>
);

// ...
const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>

    // ...

    <EntityLayout.Route path="/docs" title="Docs">
      <EntityTechdocsContent />
    </EntityLayout.Route>

    <EntityLayout.Route path="/rootly" title="Rootly">
      <RootlyIncidentsPage />
      // Rootly Multi Organization
      // <Grid item sm={6}>
      //   <RootlyIncidentsPage organizationId="rootly-sandbox" />
    </EntityLayout.Route>
  </EntityLayout>
);

//...
const systemPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <>
        {overviewContent}
        <Grid container spacing={3} alignItems="stretch">
          {entityWarningContent}
          <Grid item md={6}>
            <EntityAboutCard variant="gridItem" />
          </Grid>
          <Grid item md={6} xs={12}>
            <EntityCatalogGraphCard variant="gridItem" height={400} />
          </Grid>
          <Grid item md={6}>
            <EntityHasComponentsCard variant="gridItem" />
          </Grid>
          <Grid item md={6}>
            <EntityHasApisCard variant="gridItem" />
          </Grid>
          <Grid item md={6}>
            <EntityHasResourcesCard variant="gridItem" />
          </Grid>
        </Grid>
      </>
    </EntityLayout.Route>
    
    // ...

    <EntityLayout.Route path="/rootly" title="Rootly">
      // Make sure to add rootly.com/organization-id annotation to all the components part of this system
      <RootlyIncidentsPage />
  </EntityLayout>
);
```

## Configuring the Entity Processor ( required )

You can enable the entity processor in your Backstage instance by injecting the dependency in the backend system in `packages/backend/src/index.ts`.

```jsx
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

...

backend.add(import('@rootly/backstage-plugin-entity-processor'));

backend.start();
```

## License

This library is under the [MIT](LICENSE) license.

---
_Source: https://npm.io/package/@rootly/backstage-plugin-common · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
