Installation

License: Dual-license

---

These instructions assume you have a backstage application and you are working in it's directly.

Configuring your EventCatalog for Backstage

You will need a license key to use the backstage integration.

You can get a 14 day trial license key from EventCatalog Cloud.

Once you have a license key for Backstage, you will need to build and deploy your EventCatalog with the license key set.

Example:

Build and deploy your EventCatalog with a license key

EVENTCATALOG_LICENSE_KEY_BACKSTAGE=your-license-key npm run build 

This will enable you to use EventCatalog within backstage.

Configuring Backstage to use EventCatalog

1. Install the plugin on Backstage

yarn add @eventcatalog/backstage-plugin-eventcatalog

2. Setting up the app-config.yml

Backstage and EventCatalog have different ways to create resources. For example backstage supports components, APIS, domains, systems etc, and EventCatalog supports resources (domains, services and messages (queries, commands and events)).

When you configure the plugin you need to map Backstage information to EventCatalog information, so the plugin knows which EventCatalog page to render.

You need to add plugin configuration to your app-config.yaml file (read configuration for more details)

# eventcatalog namespace
eventcatalog:
  # URL of your catalog (has to be public, if private please raise and issue and we can fix his)
  URL: "https://demo.eventcatalog.dev"
  # map your services (Components type="Service") to EventCatalog services
  services:
    # The name of the service in backstage
    - backstage-name: "backend-service"
      # The id of the service in EventCatalog
      eventcatalog-id: "InventoryService"
      # (optional) the filter value for your discovery table embed
      eventcatalog-page-discovery-default-filter: "Inventory Service"
    - backstage-name: "backend-service2"
      eventcatalog-id: "Orders"
      eventcatalog-version: "1.0.0"
  # map your APIS (kind: API) to EventCatalog
  apis:
    - backstage-name: "example-grpc-api"
      eventcatalog-id: "NotificationService"

The EventCatalog plugin will read these values and map your pages to the correct EventCatalog pages.

3. Using the components

Assumes a new Backstage installation, install guides my vary.

Tabbed pages

import { EventCatalogDocumentationEntityPage } from "@eventcatalog/backstage-plugin-eventcatalog";

The EventCatalogDocumentationEntityPage components, is a full page component that you can assign to any EntityLayout.Route.

// Will create a new tab called "Docs" and route called /eventcatalog. This will embed the docs for that
// entity in your page. Using the info from the app-config to map your Backstage ID to EventCatalog ID
<EntityLayout.Route path="/eventcatlaog" title="Docs">
  <EventCatalogDocumentationEntityPage page='docs' />
</EntityLayout.Route>

// Will create a new tab called "Visualzer" and route called /eventcatalog-visualizer.
// This will embed the EventCatalog visualiser to your Backstage entity
<EntityLayout.Route path="/eventcatlaog-visualizer" title="Visualzer">
  <EventCatalogDocumentationEntityPage page='visualiser' />
</EntityLayout.Route>

Card components

These components can be added to your pages as Cards, that can live inside the Backstage Grid System.

import {
  EventCatalogEntityVisualiserCard,
  EventCatalogEntityMessageCard,
} from "@eventcatalog/backstage-plugin-eventcatalog";

<Grid container spacing={3} alignItems="stretch">
  <Grid item md={6}>
    <!-- Backstage card -->
    <EntityAboutCard variant="gridItem" />
  </Grid>
  <Grid item md={6}>
    <!-- Adds the visualizer to a grid item in Backstage -->
    <EventCatalogEntityVisualiserCard />
  </Grid>
  <Grid item md={6} xs={12}>
    <!-- Adds the explore (messages) to a grid item in Backstage -->
    <EventCatalogEntityMessageCard />
  </Grid>
</Grid>;

---

Demo

If you want to learn how the code works in a basic demo you can see our demo on GitHub.