From 7a2761b7ce262a6105a11b7e756056facd789cdd Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 4 Mar 2026 11:39:29 +0100
Subject: [PATCH] docs(catalog-graph): update README for new frontend system as
 default

Add new frontend system installation as the default path with package
discovery. Move old frontend system wiring to an "Old Frontend System"
section. Update README-alpha.md to be an extension reference rather
than experimental documentation.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
---
 plugins/catalog-graph/README-alpha.md |   6 +-
 plugins/catalog-graph/README.md       | 112 ++++++++++++++------------
 2 files changed, 64 insertions(+), 54 deletions(-)

diff --git a/plugins/catalog-graph/README-alpha.md b/plugins/catalog-graph/README-alpha.md
index 6242e9cc39..90481caca6 100644
--- a/plugins/catalog-graph/README-alpha.md
+++ b/plugins/catalog-graph/README-alpha.md
@@ -1,8 +1,6 @@
-# Catalog Graph
+# Catalog Graph - Extension Reference
 
-> [!WARNING]
-> This documentation is made for those using the experimental new Frontend system.
-> If you are not using the new frontend system, please go [here](./README.md).
+This page contains detailed documentation for all extensions provided by the `@backstage/plugin-catalog-graph` plugin. For general information about the plugin, see the [README](./README.md).
 
 The Catalog graph plugin helps you to visualize the relations between entities, like ownership, grouping or API relationships.
 It comes with these features:
diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md
index b411d4d868..38ea902271 100644
--- a/plugins/catalog-graph/README.md
+++ b/plugins/catalog-graph/README.md
@@ -1,8 +1,5 @@
 # catalog-graph
 
-> Disclaimer:
-> If you are looking for documentation on the experimental new frontend system support, please go [here](./README-alpha.md).
-
 Welcome to the catalog graph plugin! The catalog graph visualizes the relations
 between entities, like ownership, grouping or API relationships.
 
@@ -23,58 +20,25 @@ The plugin comes with these features:
 - `EntityRelationsGraph`:
   A react component that can be used to build own customized entity relation graphs.
 
-## Usage
+## Installation
 
-To use the catalog graph plugin, you have to add some things to your Backstage app:
+```sh
+# From your Backstage root directory
+yarn --cwd packages/app add @backstage/plugin-catalog-graph
+```
 
-1. Add a dependency to your `packages/app/package.json`:
-   ```sh
-   # From your Backstage root directory
-   yarn --cwd packages/app add @backstage/plugin-catalog-graph
-   ```
-2. Add the `CatalogGraphPage` to your `packages/app/src/App.tsx`:
+Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins).
 
-   ```typescript
-   <FlatRoutes>
-     …
-     <Route path="/catalog-graph" element={<CatalogGraphPage />} />…
-   </FlatRoutes>
-   ```
+To enable the entity relations graph card on the catalog entity page, add the following configuration:
 
-   You can configure the page to open with some initial filters:
+```yaml
+# app-config.yaml
+app:
+  extensions:
+    - entity-card:catalog-graph/relations
+```
 
-   ```typescript
-   <Route
-     path="/catalog-graph"
-     element={
-       <CatalogGraphPage
-         initialState={{
-           selectedKinds: ['component', 'domain', 'system', 'api', 'group'],
-         }}
-       />
-     }
-   />
-   ```
-
-3. Bind the external routes of the `catalogGraphPlugin` in your `packages/app/src/App.tsx`:
-
-   ```typescript
-   bindRoutes({ bind }) {
-     …
-     bind(catalogGraphPlugin.externalRoutes, {
-       catalogEntity: catalogPlugin.routes.catalogEntity,
-     });
-     …
-   }
-   ```
-
-4. Add `EntityCatalogGraphCard` to any entity page that you want in your `packages/app/src/components/catalog/EntityPage.tsx`:
-
-   ```typescript
-   <Grid item md={6} xs={12}>
-     <EntityCatalogGraphCard variant="gridItem" height={400} />
-   </Grid>
-   ```
+For the full list of available extensions and their configuration options, see the [README-alpha.md](./README-alpha.md).
 
 ### Customizing the UI
 
@@ -177,6 +141,54 @@ import {
   }),
 ```
 
+## Old Frontend System
+
+If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app.
+
+1. Add the `CatalogGraphPage` to your `packages/app/src/App.tsx`:
+
+   ```typescript
+   <FlatRoutes>
+     …
+     <Route path="/catalog-graph" element={<CatalogGraphPage />} />…
+   </FlatRoutes>
+   ```
+
+   You can configure the page to open with some initial filters:
+
+   ```typescript
+   <Route
+     path="/catalog-graph"
+     element={
+       <CatalogGraphPage
+         initialState={{
+           selectedKinds: ['component', 'domain', 'system', 'api', 'group'],
+         }}
+       />
+     }
+   />
+   ```
+
+2. Bind the external routes of the `catalogGraphPlugin` in your `packages/app/src/App.tsx`:
+
+   ```typescript
+   bindRoutes({ bind }) {
+     …
+     bind(catalogGraphPlugin.externalRoutes, {
+       catalogEntity: catalogPlugin.routes.catalogEntity,
+     });
+     …
+   }
+   ```
+
+3. Add `EntityCatalogGraphCard` to any entity page that you want in your `packages/app/src/components/catalog/EntityPage.tsx`:
+
+   ```typescript
+   <Grid item md={6} xs={12}>
+     <EntityCatalogGraphCard variant="gridItem" height={400} />
+   </Grid>
+   ```
+
 ## Development
 
 Run `yarn` in the root of this plugin to install all dependencies and then `yarn start` to run a [development version](./dev/index.tsx) of this plugin.