backstage/plugins/explore

explore

Welcome to the explore plugin!

This plugin helps to visualize the domains and tools in your ecosystem.

Setup

The following sections will help you get the Explore plugin setup and running.

Backend

You need to setup the Explore backend plugin before you move forward with any of these steps if you haven't already.

Installation

Install this plugin:

# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-explore

Add the plugin to your packages/app

Add the root page that the playlist plugin provides to your app. You can choose any path for the route, but we recommend the following:

// packages/app/src/App.tsx
+ import { ExplorePage, explorePlugin } from '@backstage/plugin-explore';

...

<FlatRoutes>
  <Route path="/catalog" element={<CatalogIndexPage />} />
  <Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
    {entityPage}
  </Route>
+  <Route path="/explore" element={<ExplorePage />} />
  ...
</FlatRoutes>

You may also want to add a link to the playlist page to your application sidebar:

// packages/app/src/components/Root/Root.tsx
+import LayersIcon from '@material-ui/icons/Layers';

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
+      <SidebarItem icon={LayersIcon} to="explore" text="Explore" />
      ...
    </Sidebar>

Use search result list item for Explore Tools

When you have your packages/app/src/components/search/SearchPage.tsx file ready to make modifications, add the following code snippet to add the ToolSearchResultListItem when the type of the search results are tool.

+import { ToolSearchResultListItem } from '@backstage/plugin-explore';

const SearchPage = () => {
 ...
  <SearchResult>
    {({ results }) => (
      <List>
        {results.map(({ type, document, highlight, rank }) => {
          switch (type) {
            ...
+            case 'tools':
+              return (
+                <ToolSearchResultListItem
+                  icon={<BuildIcon />}
+                  key={document.location}
+                  result={document}
+                  highlight={highlight}
+                  rank={rank}
+                />
+              );
          }
        })}
      </List>
    )}
    ...
  </SearchResult>
...

Customization

Create a custom explore page in packages/app/src/components/explore/ExplorePage.tsx.

import {
  DomainExplorerContent,
  ExploreLayout,
} from '@backstage/plugin-explore';
import React from 'react';
import { InnserSourceExplorerContent } from './InnserSourceExplorerContent';

export const ExplorePage = () => {
  return (
    <ExploreLayout
      title="Explore the ACME corp ecosystem"
      subtitle="Browse our ecosystem"
    >
      <ExploreLayout.Route path="domains" title="Domains">
        <DomainExplorerContent />
      </ExploreLayout.Route>
      <ExploreLayout.Route path="inner-source" title="InnerSource">
        <AcmeInnserSourceExplorerContent />
      </ExploreLayout.Route>
    </ExploreLayout>
  );
};

export const explorePage = <ExplorePage />;

Now register the new explore page in packages/app/src/App.tsx.

+import { explorePage } from './components/explore/ExplorePage';

const routes = (
  <FlatRoutes>
-    <Route path="/explore" element={<ExplorePage />} />
+    <Route path="/explore" element={<ExplorePage />}>
+      {explorePage}
+    </Route>
  </FlatRoutes>
);