@eventcatalog/core 4.10.13 → 4.10.14

package/dist/docs/plugins/backstage/00-overview.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+title: EventCatalog for Backstage
+description: Add EventCatalog documentation, diagrams, schemas, messages, and flows to Backstage entity pages.
+keywords:
+  - backstage
+  - developer portal
+  - integration
+---
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#licensing" />
+
+The EventCatalog Backstage plugin embeds EventCatalog views in Backstage entity pages. Developers can explore architecture documentation without leaving the software catalog they use for ownership, APIs, dependencies, and operations.
+
+![EventCatalog embedded in a Backstage entity page](/img/integrations/backstage/backstage-eventcatalog.png)
+
+## Choose where to start
+
+- New to the plugin? Follow [Embed EventCatalog in your first Backstage entity](/docs/plugins/backstage/get-started).
+- Adding a dedicated entity tab? Use [Embed EventCatalog as entity tabs](/docs/plugins/backstage/embed-entity-tabs).
+- Adding content to an existing overview? Use [Add EventCatalog cards to an overview page](/docs/plugins/backstage/add-overview-cards).
+- Need exact props or supported components? See the [component reference](/docs/plugins/backstage/components).
+- Upgrading from the legacy resource mapping? Follow [Migrate to entity annotations](/docs/plugins/backstage/migrate-to-annotations).
+
+## Supported views
+
+You can embed:
+
+- resource documentation
+- resource visualizers
+- message discovery tables
+- entity maps
+- the schema explorer
+- the Architecture Graph, focused on a resource at depth 1, 2, or 3
+- the System Context Map overview or a specific system and version
+- a flow visualizer for a specific flow and version
+
+Every page and card accepts `theme="light"` or `theme="dark"`. If you omit `theme`, EventCatalog uses the visitor's saved EventCatalog theme.
+
+## How the integration fits together
+
+The plugin reads the EventCatalog base URL from Backstage configuration and normally reads the EventCatalog resource identity from annotations on the current Backstage entity. It then renders the selected EventCatalog view in an iframe with embed mode enabled.
+
+Read [How EventCatalog embeds work](/docs/plugins/backstage/how-embeds-work) for the mapping, rendering, and sizing model.
+
+## Licensing
+
+The plugin requires an EventCatalog Scale license for commercial use. You can start a 30-day trial in [EventCatalog Cloud](https://eventcatalog.cloud) and follow [Getting a license key for integrations](/docs/development/license-keys/integrations).
+
+For license terms, see the [plugin repository](https://github.com/event-catalog/backstage-plugin-eventcatalog).

package/dist/docs/plugins/backstage/01-get-started.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 2
+sidebar_label: Get started
+title: Embed EventCatalog in your first Backstage entity
+description: Install the EventCatalog Backstage plugin and add resource documentation to an entity page.
+keywords:
+  - backstage
+  - tutorial
+  - installation
+---
+
+In this tutorial, you will connect a Backstage app to an EventCatalog instance and add an EventCatalog documentation tab to a service entity.
+
+You will need:
+
+- a Backstage app with a software catalog entity page
+- an EventCatalog instance that the user's browser can reach
+- an EventCatalog Scale license for commercial use
+
+## 1. Enable the integration in EventCatalog
+
+Add your Scale license key to the `.env` file in the EventCatalog project:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+Build and deploy EventCatalog with this environment variable. For license setup and legacy keys, see [Getting a license key for integrations](/docs/development/license-keys/integrations).
+
+## 2. Install the Backstage plugin
+
+From the root of your Backstage app, install the frontend plugin:
+
+```bash
+yarn add @eventcatalog/backstage-plugin-eventcatalog
+```
+
+## 3. Configure the EventCatalog URL
+
+Add the public base URL of your EventCatalog instance to `app-config.yaml`:
+
+```yaml title="app-config.yaml"
+eventcatalog:
+  URL: https://demo.eventcatalog.dev
+```
+
+Do not add a trailing view path such as `/docs` or `/visualiser`. The plugin builds each embed URL from this base URL.
+
+## 4. Map a Backstage entity
+
+Add EventCatalog annotations to a Backstage catalog entity. This example maps a Backstage component to version `1.0.0` of the `order-service` service in EventCatalog:
+
+```yaml title="catalog-info.yaml"
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: order-service
+  description: Handles customer orders
+  annotations:
+    eventcatalog.dev/id: order-service
+    eventcatalog.dev/version: 1.0.0
+    eventcatalog.dev/collection: services
+spec:
+  type: service
+  lifecycle: production
+  owner: team-orders
+```
+
+The annotation values must match the resource ID, version, and collection in EventCatalog.
+
+## 5. Add an EventCatalog tab
+
+Open the file that defines your catalog entity page, commonly `packages/app/src/components/catalog/EntityPage.tsx`.
+
+Import the page component:
+
+```tsx
+import { EventCatalogDocumentationEntityPage } from '@eventcatalog/backstage-plugin-eventcatalog';
+```
+
+Add a route inside the `EntityLayout` used for your service entities:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-docs" title="EventCatalog: Docs">
+  <EventCatalogDocumentationEntityPage page="docs" />
+</EntityLayout.Route>
+```
+
+## 6. Check the result
+
+Start Backstage and open the mapped service. Select **EventCatalog: Docs**.
+
+You should see the `order-service` documentation from EventCatalog fill the tab. If you see a mapping message instead, check that `eventcatalog.dev/id` is present and that the entity has been re-ingested by Backstage.
+
+You now have a working EventCatalog embed. Next, [add more entity tabs](/docs/plugins/backstage/embed-entity-tabs) or [place visualizations on the overview page](/docs/plugins/backstage/add-overview-cards).

package/dist/docs/plugins/backstage/02-embed-entity-tabs.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 3
+sidebar_label: Embed entity tabs
+title: Embed EventCatalog as entity tabs
+description: Add documentation, message, schema, map, graph, and flow tabs to Backstage entity pages.
+keywords:
+  - backstage
+  - entity tabs
+  - entity layout
+---
+
+Use full-page components inside `EntityLayout.Route` when you want an EventCatalog view to have its own Backstage entity tab.
+
+## Import the components
+
+Import the general-purpose page component and any dedicated visualization components you need:
+
+```tsx
+import {
+  EventCatalogArchitectureGraphEntityPage,
+  EventCatalogDocumentationEntityPage,
+  EventCatalogFlowEntityPage,
+  EventCatalogSystemContextMapEntityPage,
+} from '@eventcatalog/backstage-plugin-eventcatalog';
+```
+
+## Add resource views
+
+The documentation, visualizer, discovery table, entity map, and schema explorer use `EventCatalogDocumentationEntityPage`:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-docs" title="EventCatalog: Docs">
+  <EventCatalogDocumentationEntityPage page="docs" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-visualiser" title="EventCatalog: Visualiser">
+  <EventCatalogDocumentationEntityPage page="visualiser" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-messages" title="EventCatalog: Messages">
+  <EventCatalogDocumentationEntityPage page="discover" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-entity-map" title="EventCatalog: Entity Map">
+  <EventCatalogDocumentationEntityPage page="entity-map" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-schema-explorer" title="EventCatalog: Schema Explorer">
+  <EventCatalogDocumentationEntityPage page="schema-explorer" />
+</EntityLayout.Route>
+```
+
+These components use the annotations on the current entity. To show a different resource, pass `id`, `version`, and `collection` explicitly:
+
+```tsx
+<EventCatalogDocumentationEntityPage
+  page="entity-map"
+  id="ordering"
+  version="1.0.0"
+  collection="domains"
+/>
+```
+
+## Add an Architecture Graph
+
+Use `EventCatalogArchitectureGraphEntityPage` to focus the catalog-wide graph on a resource. `depth` accepts `1`, `2`, or `3` and defaults to `2`.
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-architecture" title="EventCatalog: Architecture">
+  <EventCatalogArchitectureGraphEntityPage type="service" depth={2} />
+</EntityLayout.Route>
+```
+
+The resource ID comes from the current entity unless you pass `id`. `type` is the singular alias for `collection`; for example, `type="service"` maps to `services`.
+
+## Add a System Context Map
+
+Omit the props to show the catalog-wide overview:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-system-context" title="EventCatalog: System Context">
+  <EventCatalogSystemContextMapEntityPage />
+</EntityLayout.Route>
+```
+
+To show one system, provide its ID and version:
+
+```tsx
+<EventCatalogSystemContextMapEntityPage
+  system="order-management-system"
+  version="1.0.0"
+/>
+```
+
+On a mapped Backstage `System` entity, the component can read the system ID and version from annotations instead.
+
+## Add a flow
+
+A flow embed requires a flow ID and version:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-flow" title="EventCatalog: Flow">
+  <EventCatalogFlowEntityPage flow="checkout-saga" version="1.0.0" />
+</EntityLayout.Route>
+```
+
+You can instead annotate a Backstage entity with the flow ID, version, and `flows` collection, then omit the `flow` and `version` props.
+
+For every supported prop and page value, see the [component reference](/docs/plugins/backstage/components).

package/dist/docs/plugins/backstage/03-add-overview-cards.md

@@ -0,0 +1,79 @@
+---
+sidebar_position: 4
+sidebar_label: Add overview cards
+title: Add EventCatalog cards to an overview page
+description: Place EventCatalog diagrams, tables, schemas, and flows in a Backstage overview grid.
+keywords:
+  - backstage
+  - cards
+  - overview
+---
+
+Use the card components to place EventCatalog views alongside existing Backstage cards. The components fill their parent, so give each grid item an explicit height.
+
+## Import the cards
+
+```tsx
+import {
+  EventCatalogEntityArchitectureGraphCard,
+  EventCatalogEntityEntityMapCard,
+  EventCatalogEntityFlowCard,
+  EventCatalogEntityMessageCard,
+  EventCatalogEntitySchemaExplorerCard,
+  EventCatalogEntitySystemContextMapCard,
+  EventCatalogEntityVisualiserCard,
+} from '@eventcatalog/backstage-plugin-eventcatalog';
+```
+
+## Add cards to the overview grid
+
+Add the cards to the `Grid` used by your entity overview. Choose heights that suit each visualization:
+
+```tsx
+const overviewContent = (
+  <Grid container spacing={3} alignItems="stretch">
+    <Grid item xs={12} style={{ height: 700 }}>
+      <EventCatalogEntityFlowCard
+        flow="checkout-saga"
+        version="1.0.0"
+      />
+    </Grid>
+
+    <Grid item xs={12} style={{ height: 800 }}>
+      <EventCatalogEntityArchitectureGraphCard
+        type="service"
+        depth={2}
+      />
+    </Grid>
+
+    <Grid item xs={12} md={6} style={{ height: 600 }}>
+      <EventCatalogEntityVisualiserCard />
+    </Grid>
+
+    <Grid item xs={12} md={6} style={{ height: 600 }}>
+      <EventCatalogEntityMessageCard />
+    </Grid>
+  </Grid>
+);
+```
+
+The resource-oriented cards read the current entity's EventCatalog annotations. Components that select a global or specific view also accept explicit props:
+
+```tsx
+<EventCatalogEntityEntityMapCard
+  id="ordering"
+  version="1.0.0"
+  collection="domains"
+/>
+
+<EventCatalogEntitySystemContextMapCard
+  system="order-management-system"
+  version="1.0.0"
+/>
+
+<EventCatalogEntitySchemaExplorerCard />
+```
+
+To make a card span the whole overview width, use `xs={12}`. To arrange two cards side by side on medium screens, give each item `xs={12} md={6}`.
+
+See [Control embed theme and size](/docs/plugins/backstage/control-theme-and-size) if an iframe does not fill its card.

package/dist/docs/plugins/backstage/04-control-theme-and-size.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 5
+sidebar_label: Theme and sizing
+title: Control an embed's theme and size
+description: Select a light or dark EventCatalog theme and make embeds fill their Backstage containers.
+keywords:
+  - backstage
+  - theme
+  - iframe height
+---
+
+Every EventCatalog page and card component accepts a `theme` prop.
+
+## Select a theme
+
+Set `theme` to `light` or `dark`:
+
+```tsx
+<EventCatalogDocumentationEntityPage page="docs" theme="dark" />
+
+<EventCatalogEntityArchitectureGraphCard
+  type="service"
+  depth={2}
+  theme="light"
+/>
+```
+
+When `theme` is omitted, the embedded page uses the visitor's saved EventCatalog theme. The explicit prop affects that embed; it does not overwrite the visitor's saved preference.
+
+To make every EventCatalog view in a Backstage app consistent, pass the same theme to each page and card component.
+
+## Give cards an explicit height
+
+The plugin iframe uses `height: 100%`, which means its height is inherited from its parent. Set the height on the Backstage grid item or another wrapping element:
+
+```tsx
+<Grid item xs={12} style={{ height: 800 }}>
+  <EventCatalogEntityArchitectureGraphCard
+    type="service"
+    depth={2}
+    theme="dark"
+  />
+</Grid>
+```
+
+Avoid percentage heights unless every ancestor has a defined height. A fixed height, viewport-relative height, or layout-controlled height gives the iframe a concrete area to fill:
+
+```tsx
+<Grid item xs={12} style={{ height: 'calc(100vh - 240px)', minHeight: 600 }}>
+  <EventCatalogEntitySchemaExplorerCard theme="dark" />
+</Grid>
+```
+
+Full-page components automatically fill the height made available by the `EntityLayout.Route`. If a custom route wrapper collapses, give that wrapper an explicit height too.

package/dist/docs/plugins/backstage/05-migrate-to-annotations.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 6
+sidebar_label: Migrate legacy mappings
+title: Migrate legacy resource mappings to entity annotations
+description: Replace pre-1.0 Backstage app configuration mappings with EventCatalog entity annotations.
+keywords:
+  - backstage
+  - migration
+  - annotations
+---
+
+Plugin versions before 1.0 mapped Backstage names to EventCatalog IDs in `app-config.yaml`:
+
+```yaml title="app-config.yaml"
+eventcatalog:
+  URL: https://demo.eventcatalog.dev
+  services:
+    - backstage-name: order-service
+      eventcatalog-id: order-service
+      eventcatalog-version: 1.0.0
+```
+
+Move each resource mapping to the matching Backstage entity:
+
+```yaml title="catalog-info.yaml"
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: order-service
+  annotations:
+    eventcatalog.dev/id: order-service
+    eventcatalog.dev/version: 1.0.0
+    eventcatalog.dev/collection: services
+spec:
+  type: service
+  lifecycle: production
+  owner: team-orders
+```
+
+Keep only the EventCatalog base URL in `app-config.yaml`:
+
+```yaml title="app-config.yaml"
+eventcatalog:
+  URL: https://demo.eventcatalog.dev
+```
+
+Re-ingest the entity in Backstage, then open an EventCatalog tab or card and verify that it resolves the expected resource. Repeat for every legacy `services` and `apis` mapping.
+
+See the [configuration reference](/docs/plugins/backstage/configuration) for annotation defaults and supported collections.

package/dist/docs/plugins/backstage/06-configuration.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 7
+sidebar_label: Configuration reference
+title: Backstage plugin configuration reference
+description: Reference for the EventCatalog base URL and Backstage entity annotations.
+keywords:
+  - backstage
+  - app-config
+  - annotations
+---
+
+## Backstage app configuration
+
+Configure one EventCatalog base URL in Backstage:
+
+```yaml title="app-config.yaml"
+eventcatalog:
+  URL: https://demo.eventcatalog.dev
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `eventcatalog.URL` | string | Yes | Base URL of the EventCatalog instance. The browser displaying Backstage must be able to reach it. |
+
+Configure the EventCatalog origin, without an EventCatalog page path such as `/docs`, `/discover`, or `/visualiser`.
+
+## Entity annotations
+
+Add these annotations to a Backstage catalog entity:
+
+```yaml
+metadata:
+  annotations:
+    eventcatalog.dev/id: order-service
+    eventcatalog.dev/version: 1.0.0
+    eventcatalog.dev/collection: services
+```
+
+| Annotation | Required | Default | Description |
+| --- | --- | --- | --- |
+| `eventcatalog.dev/id` | Yes for resource views | None | EventCatalog resource ID. |
+| `eventcatalog.dev/version` | No | Latest resource page where supported | EventCatalog resource version. Entity maps, specific system context maps, and flows should provide a version. |
+| `eventcatalog.dev/collection` | No | Inferred for Backstage services, APIs, and domains | EventCatalog collection containing the resource. |
+
+Supported collections include:
+
+- `agents`
+- `commands`
+- `containers`
+- `data-products`
+- `domains`
+- `entities`
+- `events`
+- `flows`
+- `queries`
+- `services`
+- `systems`
+- `teams`
+
+For a Backstage `Component` with `spec.type: service`, and for a Backstage `API`, the inferred collection is `services`. For a Backstage `Domain`, it is `domains`. Other entity kinds should set `eventcatalog.dev/collection` explicitly.
+
+## Prop overrides
+
+Component props override annotations. For example, this always displays the `ordering` domain even when the current Backstage entity maps to another resource:
+
+```tsx
+<EventCatalogDocumentationEntityPage
+  page="entity-map"
+  id="ordering"
+  version="1.0.0"
+  collection="domains"
+/>
+```
+
+`type` is an alias for `collection` and accepts singular or plural values. Known singular resource types are converted to their plural collection, so `type="service"` resolves to `services`.
+
+## EventCatalog license configuration
+
+For commercial use, set the Scale license key in the EventCatalog deployment rather than the Backstage app:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+Existing Backstage-specific keys can continue to use `EVENTCATALOG_LICENSE_KEY_BACKSTAGE`, but new deployments should use `EVENTCATALOG_SCALE_LICENSE_KEY`. See [Getting a license key for integrations](/docs/development/license-keys/integrations).

package/dist/docs/plugins/backstage/07-components.md

@@ -0,0 +1,129 @@
+---
+sidebar_position: 8
+sidebar_label: Component reference
+title: Backstage plugin component reference
+description: Reference for all EventCatalog Backstage page and card components and their props.
+keywords:
+  - backstage
+  - react components
+  - props
+---
+
+Import components from `@eventcatalog/backstage-plugin-eventcatalog`.
+
+## Full-page components
+
+Use these components as children of `EntityLayout.Route`.
+
+### `EventCatalogDocumentationEntityPage`
+
+The general-purpose page component.
+
+```tsx
+<EventCatalogDocumentationEntityPage page="docs" />
+```
+
+Supported `page` values:
+
+| Value | Embedded view | Resource selection |
+| --- | --- | --- |
+| `docs` | Resource documentation | Current mapping or `id`, `version`, and `collection` props |
+| `visualiser` | Resource visualizer | Current mapping or override props |
+| `discover` | Discovery table for the mapped collection | Current mapping or override props |
+| `entity-map` | Resource entity map | Current mapping or override props; provide a version |
+| `schema-explorer` | Catalog schema explorer | Global catalog view, rendered from a mapped entity page |
+| `architecture-graph` | Catalog Architecture Graph | Prefer `EventCatalogArchitectureGraphEntityPage` |
+| `system-context-map` | System Context Map | Prefer `EventCatalogSystemContextMapEntityPage` |
+| `flow` | Flow visualizer | Prefer `EventCatalogFlowEntityPage` |
+
+### `EventCatalogArchitectureGraphEntityPage`
+
+Displays `/visualiser/graph` and focuses the graph on the selected resource.
+
+```tsx
+<EventCatalogArchitectureGraphEntityPage
+  type="service"
+  depth={2}
+/>
+```
+
+The graph accepts `depth={1 | 2 | 3}` and defaults to `2`. The Architecture Graph currently uses the latest version of each resource, so `version` does not change its graph data.
+
+### `EventCatalogSystemContextMapEntityPage`
+
+Displays the catalog-wide System Context Map when no system is selected:
+
+```tsx
+<EventCatalogSystemContextMapEntityPage />
+```
+
+Pass `system` and `version` to display one system's context:
+
+```tsx
+<EventCatalogSystemContextMapEntityPage
+  system="order-management-system"
+  version="1.0.0"
+/>
+```
+
+`id` is accepted as an alias for `system`. A mapped Backstage `System` entity can supply both values through annotations.
+
+### `EventCatalogFlowEntityPage`
+
+Displays a flow visualizer. A flow ID and version are required.
+
+```tsx
+<EventCatalogFlowEntityPage
+  flow="checkout-saga"
+  version="1.0.0"
+/>
+```
+
+`id` is accepted as an alias for `flow`.
+
+## Card components
+
+Card components render the same embeds and fill the dimensions of their parent container.
+
+| Component | View | Selection props |
+| --- | --- | --- |
+| `EventCatalogEntityVisualiserCard` | Resource visualizer | Current entity mapping |
+| `EventCatalogEntityMessageCard` | Discovery table | Current entity mapping |
+| `EventCatalogEntityEntityMapCard` | Entity map | Current mapping or `id`, `version`, and `collection` |
+| `EventCatalogEntitySchemaExplorerCard` | Schema explorer | Global view |
+| `EventCatalogEntityArchitectureGraphCard` | Architecture Graph | Current mapping or `id`, `type`/`collection`, and `depth` |
+| `EventCatalogEntitySystemContextMapCard` | System Context Map | Overview, or `system`/`id` and `version` |
+| `EventCatalogEntityFlowCard` | Flow visualizer | `flow`/`id` and `version`, or current entity mapping |
+
+Set a concrete height on the parent grid item. See [Control embed theme and size](/docs/plugins/backstage/control-theme-and-size).
+
+## Shared props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Entity annotation | Override the EventCatalog resource ID. Also aliases `system` and `flow` on their dedicated components. |
+| `version` | `string` | Entity annotation | Override the EventCatalog version. |
+| `collection` | `string` | Entity annotation or inferred value | Override the EventCatalog collection. |
+| `type` | `string` | None | Alias for `collection`; singular known types are converted to plural collections. |
+| `theme` | `'light' \| 'dark'` | Saved EventCatalog theme | Force the color theme for this embed. |
+
+## Specialized props
+
+| Prop | Component | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `page` | `EventCatalogDocumentationEntityPage` | `EventCatalogPage` | `docs` | Select the embedded EventCatalog view. |
+| `depth` | Architecture Graph components | `1 \| 2 \| 3` | `2` | Number of relationship hops around the focused resource. |
+| `system` | System Context Map components | `string` | None | EventCatalog system ID. Omit for the overview. |
+| `flow` | Flow components | `string` | Entity annotation | EventCatalog flow ID. |
+
+## Exported types
+
+The package exports these public types:
+
+- `EventCatalogArchitectureGraphDepth`
+- `EventCatalogArchitectureGraphEntityPageProps`
+- `EventCatalogDocumentationEntityPageProps`
+- `EventCatalogEmbedTheme`
+- `EventCatalogEmbedThemeProps`
+- `EventCatalogFlowEntityPageProps`
+- `EventCatalogSystemContextMapEntityPageProps`