Getting started
Dual-license
Many folks are using Backstage for their internal developer portals. Backstage is a highly configurable platform that allows you to document your architecture in components, apis, services, domains and much more.
Backstage supports plugins, that have a frontend and backend support.
Using the EventCatalog Backstage plugin you can embed your EventCatalog information into backstage.
Core Features
The EventCatalog Backstage plugin can provide you with many features:
- 📃 Bring EventCatalog documentation into Backstage
- 📃 Custom tabs for your APIs and Services. Embed documentation, visualizations and searchable tables.
- 📊 Embed EventCatalog visualizer into your Backstage pages
- 🔎 Embed the EventCatalog discovery table to quickly find messages for your services
- ⭐ And much more...
How it works
This plugin exposes React components that you can embed on your pages to display information from EventCatalog.
Your EventCatalog has be hosted and the URL given to the app.config.yml file.
<EventCatalogDocumentationEntityPage page="docs/page/visualiser" />
- Used to embed whole pages of EventCatalog into your Backstage instance. You can add these as tabs to your pages, clicking on the tab will show the desired feature.
<EventCatalogEntityVisualiserCard />
- Used to embed a widget (Card) on your existing pages. This component will display the visualiser on your page.
<EventCatalogEntityMessageCard />
- Used to embed a widget (Card) on your existing pages. This component will display the explore (table) on your page. Great for displaying a list of messages your service produces/consumes.
Note: If you want to embed private EventCatalog instances, raise an issue on GitHub and we can explore this.
Getting started
These instructions assume you have a backstage application and you are working in it's directly.
1. Install the plugin
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.
Commercial Use
This plugin is governed by a dual-license. To ensure the sustainability of the project, you can freely make use of this software if usage is also Open Source. Otherwise for proprietary use, internal use, and private modifications you must obtain a commercial license.
To obtain a commercial license or have any questions you can email us at hello@eventcatalog.dev
.