From 79379097f7ce3167d937809bf58058f71ccd0b7a Mon Sep 17 00:00:00 2001
From: Iain Billett <iain@roadie.io>
Date: Sun, 4 Oct 2020 13:49:58 +0100
Subject: [PATCH] Update Lighthouse plugin README

Add instructions for integration with the catalog.
---
 plugins/lighthouse/README.md                  | 63 +++++++++++++++++++
 .../Cards/LastLighthouseAuditCard.tsx         | 15 +++--
 2 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/plugins/lighthouse/README.md b/plugins/lighthouse/README.md
index b5fecb85f8..19244f3cf0 100644
--- a/plugins/lighthouse/README.md
+++ b/plugins/lighthouse/README.md
@@ -57,3 +57,66 @@ Then configure the lighthouse service url in your [`app-config.yaml`](https://gi
 lighthouse:
   baseUrl: http://your-service-url
 ```
+
+### Integration with the Catalog
+
+The lighthouse plugin can be integrated into the catalog so that lighthouse audit information relating to a component
+can be displayed within that component's entity page. In order to link an Entity to its lighthouse audits the entity
+must be annotated as follows:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  # ...
+  annotations:
+    # ...
+    lighthouse.com/website-url: # A single website url e.g. https://backstage.io/
+```
+
+> NOTE: The lighthouse plugin only supports one website url per component at this time.
+
+Add a lighthouse tab to the EntityPage:
+
+```tsx
+// packages/app/src/components/catalog/EntityPage.tsx
+import { EmbeddedRouter as LighthouseRouter } from '@backstage/plugin-lighthouse';
+
+// ...
+const WebsiteEntityPage = ({ entity }: { entity: Entity }) => (
+  <EntityPageLayout>
+    // ...
+    <EntityPageLayout.Content
+      path="/lighthouse"
+      title="Lighthouse"
+      element={<LighthouseRouter entity={entity} />}
+    />
+  </EntityPageLayout>
+);
+```
+
+> NOTE: The embedded router renders page content without a header section allowing it to be rendered within a
+> catalog plugin page.
+
+Add a Lighthouse card to the overview tab on the EntityPage:
+
+```tsx
+// packages/app/src/components/catalog/EntityPage.tsx
+import {
+  LastLighthouseAuditCard,
+  isPluginApplicableToEntity as isLighthouseAvailable,
+} from '@backstage/plugin-lighthouse';
+
+// ...
+
+const OverviewContent = ({ entity }: { entity: Entity }) => (
+  <Grid container spacing={3}>
+    // ...
+    {isLighthouseAvailable(entity) && (
+      <Grid item sm={4}>
+        <LastLighthouseAuditCard />
+      </Grid>
+    )}
+  </Grid>
+);
+```
diff --git a/plugins/lighthouse/src/components/Cards/LastLighthouseAuditCard.tsx b/plugins/lighthouse/src/components/Cards/LastLighthouseAuditCard.tsx
index d82e6c5c6c..d3bc362877 100644
--- a/plugins/lighthouse/src/components/Cards/LastLighthouseAuditCard.tsx
+++ b/plugins/lighthouse/src/components/Cards/LastLighthouseAuditCard.tsx
@@ -62,7 +62,10 @@ const LighthouseAuditStatus: FC<{ audit: Audit }> = ({ audit }) => (
   </>
 );
 
-const LighthouseAuditSummary: FC<{ audit: Audit }> = ({ audit }) => {
+const LighthouseAuditSummary: FC<{ audit: Audit; dense?: boolean }> = ({
+  audit,
+  dense = false,
+}) => {
   const { url } = audit;
   const flattenedCategoryData: Record<string, React.ReactNode> = {};
   if (audit.status === 'COMPLETED') {
@@ -82,10 +85,12 @@ const LighthouseAuditSummary: FC<{ audit: Audit }> = ({ audit }) => {
     ...flattenedCategoryData,
   };
 
-  return <StructuredMetadataTable metadata={tableData} />;
+  return <StructuredMetadataTable metadata={tableData} dense={dense} />;
 };
 
-export const LastLighthouseAuditCard: FC<{}> = () => {
+export const LastLighthouseAuditCard: FC<{ dense?: boolean }> = ({
+  dense = false,
+}) => {
   const { value: website, loading, error } = useWebsiteForEntity();
 
   let content;
@@ -96,7 +101,9 @@ export const LastLighthouseAuditCard: FC<{}> = () => {
     content = null;
   }
   if (website) {
-    content = <LighthouseAuditSummary audit={website.lastAudit} />;
+    content = (
+      <LighthouseAuditSummary audit={website.lastAudit} dense={dense} />
+    );
   }
   return <InfoCard title="Lighthouse Audit">{content}</InfoCard>;
 };