badges: use new error api. revert css layout tweak for CodeSnippet. add basic frontend test. improve doc.

Signed-off-by: Andreas Stenius <andreas.stenius@svenskaspel.se>

plugins/badges-backend/README.md

@@ -1,6 +1,7 @@
 # Badges Backend
 
-Backend plugin for serving badges. Default implementation uses
+Backend plugin for serving badges to the `@backstage/plugin-badges` plugin.
+Default implementation uses
 [badge-maker](https://www.npmjs.com/package/badge-maker) for creating the
 badges, in SVG.
 
@@ -8,10 +9,35 @@ Currently, only entity badges are implemented. i.e. badges that may have entity
 specific information in them, and as such, are served from a entity specific
 endpoint.
 
-## Setup
+## Installation
 
-The list of all badges to offer are passed as an object with badge factories to
-the badges-backend `createRouter()` during plugin registration.
+Install the `@backstage/plugin-badges-backend` package in your backend packages,
+and then integrate the plugin using the following default setup for
+`src/plugins/badges.ts`:
+
+```ts
+import {
+  createRouter,
+  createDefaultBadgeFactories,
+} from '@backstage/plugin-badges-backend';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin({
+  config,
+  discovery,
+}: PluginEnvironment) {
+  return await createRouter({
+    config,
+    discovery,
+    badgeFactories: createDefaultBadgeFactories(),
+  });
+}
+```
+
+The `createDefaultBadgeFactories()` returns an object with badge factories to
+the badges-backend `createRouter()` to forward to the default badge builder. To
+customize the available badges, provide a custom set of badge factories. See
+further down for an example of a custom badge factories function.
 
 ## Badge builder
 
@@ -28,6 +54,30 @@ as examples.
 Additional badges may be provided in your application by defining custom badge
 factories, and provide them to the badge builder.
 
+### Custom badges
+
+To provide custom badges, create a badges factories function, and use that when
+creating the badges backend router.
+
+```ts
+import type { Badge, BadgeContext, BadgeFactories } from '@backstage/plugin-badges-backend';
+export const createMyCustomBadgeFactories = (): BadgeFactories => ({
+    <custom-badge-id>: {
+        createBadge: (context: BadgeContext): Badge | null => {
+            // ...
+            return {
+                label: 'my-badge',
+                message: 'custom stuff',
+                // ...
+            };
+        },
+    },
+
+    // optional: include the default badges
+    // ...createDefaultBadgeFactories(),
+});
+```
+
 ## API
 
 The badges backend api exposes two main endpoints for entity badges. (the

plugins/badges-backend/package.json

@@ -34,6 +34,7 @@
     "@backstage/catalog-client": "^0.3.6",
     "@backstage/catalog-model": "^0.7.3",
     "@backstage/config": "^0.1.3",
+    "@backstage/errors": "^0.1.1",
     "@types/express": "^4.17.6",
     "badge-maker": "^3.3.0",
     "cors": "^2.8.5",

plugins/badges-backend/src/service/router.ts

@@ -22,6 +22,7 @@ import {
 } from '@backstage/backend-common';
 import { CatalogApi, CatalogClient } from '@backstage/catalog-client';
 import { Config } from '@backstage/config';
+import { NotFoundError } from '@backstage/errors';
 import { BadgeBuilder, DefaultBadgeBuilder } from '../lib/BadgeBuilder';
 import { BadgeContext, BadgeFactories } from '../types';
 
@@ -50,8 +51,9 @@ export async function createRouter(
     const { namespace, kind, name } = req.params;
     const entity = await catalog.getEntityByName({ namespace, kind, name });
     if (!entity) {
-      res.status(404).send(`Unknown entity`);
-      return;
+      throw new NotFoundError(
+        `No ${kind} entity in ${namespace} named "${name}"`,
+      );
     }
 
     const context: BadgeContext = {
@@ -86,8 +88,9 @@ export async function createRouter(
     const { namespace, kind, name, badgeId } = req.params;
     const entity = await catalog.getEntityByName({ namespace, kind, name });
     if (!entity) {
-      res.status(404).send(`Unknown entity`);
-      return;
+      throw new NotFoundError(
+        `No ${kind} entity in ${namespace} named "${name}"`,
+      );
     }
 
     let format =
@@ -109,11 +112,11 @@ export async function createRouter(
     });
 
     if (!data) {
-      res.status(404).send(`Unknown entity badge "${badgeId}"`);
-    } else {
-      res.setHeader('Content-Type', format);
-      res.status(200).send(data);
+      throw new NotFoundError(`Unknown badge "${badgeId}" for ${kind} entity.`);
     }
+
+    res.setHeader('Content-Type', format);
+    res.status(200).send(data);
   });
 
   router.use(errorHandler());