Tag 11: Ein eigenes Plugin
Ziel: Du baust mit
yarn newein Backend- und ein Frontend-Pluginbereitschaft, das auf jeder Component-Seite zeigt, wer im Owner-Team heute Bereitschaft hat. · Dauer: ca. 120 min · Voraussetzung: Tag 10
Briefing
- Ein Plugin besteht meist aus zwei Paketen: das
Backend-Plugin liefert eine REST-API unter
/api/<pluginId>, das Frontend-Plugin liefert Extensions für die App. yarn newerzeugt beide Pakete unterplugins/und trägt sie gleich in Backend und App ein.- Das Frontend fragt das Backend über
fetchApi– mit dem Token des angemeldeten Users. Ohne Token antwortet jedes Plugin-Backend mit 401. - Die Bereitschaftsliste steht in der Konfiguration, nicht im Code.
Entity-Seite sendungs-api (spec.owner: team-sendung)
└─ entity-card:bereitschaft/heute ──fetchApi──► GET /api/bereitschaft/heute
?team=team-sendung
◄── {"person":"user:default/ben.kraus", …}
app-config.local.yaml: bereitschaft.teams.team-sendung: [anna.berger, …]
Drill 1: Ein Backend-Plugin erzeugen
Ausgangslage ist das Ende von Tag 10. Für dieses Kapitel genügen
sendungs-api, tracking-web und die
Organisation aus Tag 4 im Katalog; Kubernetes muss nicht laufen. Der
Generator ruft am Ende selbst yarn install und
yarn lint --fix auf.
source ~/backstage-lab/setup/env.sh
cd ~/backstage-lab/portal
yarn newWähle im Menü mit den Pfeiltasten backend-plugin und
gib als ID bereitschaft ein. Erwartet (gekürzt; die
Fragezeilen können je nach Version abweichen):
? What do you want to create? backend-plugin - A new backend plugin
? Enter the ID of the plugin [required] bereitschaft
templating plugins/bereitschaft-backend ✔
backend adding @internal/backstage-plugin-bereitschaft-backend ✔
executing yarn install ✔
executing yarn lint --fix ✔
Tipp: Ohne Rückfragen, z. B. in Skripten:
yarn new --select backend-plugin --option pluginId=bereitschaft. Beide Flags stehen inyarn new --help.
Der Paketname folgt dem Muster
@internal/backstage-plugin-<id>-backend. Der
Generator hat ihn schon im Backend eingetragen:
git diff packages/backend/src/index.ts | grep '^+b'
find plugins/bereitschaft-backend/src -type f | sortErwartet:
+backend.add(import('@internal/backstage-plugin-bereitschaft-backend'));
plugins/bereitschaft-backend/src/index.ts
plugins/bereitschaft-backend/src/plugin.test.ts
plugins/bereitschaft-backend/src/plugin.ts
plugins/bereitschaft-backend/src/router.test.ts
plugins/bereitschaft-backend/src/router.ts
plugins/bereitschaft-backend/src/services/TodoListService.ts
plugins/bereitschaft-backend/src/setupTests.ts
Die Vorlage ist eine kleine Todo-API (/todos). Du
ersetzt sie in Drill 2 durch die Bereitschaft.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Router und Konfiguration
Der Router kennt nur eine Route. wer() wählt reihum,
jeden Tag ist die nächste Person dran. Fehler wirfst du als
InputError (400) oder NotFoundError (404) aus
@backstage/errors – das Backend macht daraus eine
JSON-Fehlerantwort.
cd ~/backstage-lab/portal/plugins/bereitschaft-backend
rm -r src/services
cat > src/router.ts <<'EOF'
import { InputError, NotFoundError } from '@backstage/errors';
import express from 'express';
import Router from 'express-promise-router';
/** Team-Name → Liste der User-Namen (aus bereitschaft.teams) */
export type Teams = Record<string, string[]>;
/** Reihum: jeden Tag ist die nächste Person dran. */
export function wer(personen: string[], datum: Date): string {
const tag = Math.floor(datum.getTime() / 86_400_000);
return personen[tag % personen.length];
}
export function createRouter(options: { teams: Teams }): express.Router {
const router = Router();
router.get('/heute', async (req, res) => {
const team = req.query.team;
if (typeof team !== 'string' || team === '') {
throw new InputError('Parameter team fehlt');
}
const personen = options.teams[team];
if (!personen?.length) {
throw new NotFoundError(`Keine Bereitschaft für ${team}`);
}
const datum = new Date();
res.json({
team,
datum: datum.toISOString().slice(0, 10),
person: `user:default/${wer(personen, datum)}`,
});
});
return router;
}
EOFDas Plugin holt sich per Dependency Injection die Konfiguration,
einen Logger und den httpRouter, der alles unter
/api/bereitschaft einhängt:
cat > src/plugin.ts <<'EOF'
import {
coreServices,
createBackendPlugin,
} from '@backstage/backend-plugin-api';
import { createRouter, Teams } from './router';
/**
* bereitschaftPlugin backend plugin
*
* @public
*/
export const bereitschaftPlugin = createBackendPlugin({
pluginId: 'bereitschaft',
register(env) {
env.registerInit({
deps: {
config: coreServices.rootConfig,
logger: coreServices.logger,
httpRouter: coreServices.httpRouter,
},
async init({ config, logger, httpRouter }) {
const teams = config.getOptional<Teams>('bereitschaft.teams') ?? {};
logger.info(`Bereitschaft für ${Object.keys(teams).length} Teams`);
httpRouter.use(createRouter({ teams }));
},
});
},
});
EOFDer Schlüssel bereitschaft ist frei gewählt. Hänge ihn
als eigenen Top-Level-Block an die local-Datei an (die User stammen aus
kranich/org, Tag 4):
cat ~/backstage-lab/code/tag11/bereitschaft.yaml \
>> ~/backstage-lab/portal/app-config.local.yaml
tail -4 ~/backstage-lab/portal/app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
grep -a 'Bereitschaft für' ~/backstage-lab/portal.log | sed 's/\x1b\[[0-9;]*m//g'Erwartet:
bereitschaft:
teams:
team-sendung: [anna.berger, ben.kraus]
team-web: [chris.dietz, thomas.zachmann]
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
2026-10-13T07:31:08.373Z bereitschaft info Bereitschaft für 2 Teams
Die Testdateien der Vorlage passen nicht mehr zum Code. Du ersetzt
sie in Drill 7; yarn start stört das nicht.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Aufruf per API – und warum 401
curl -s "$BACKSTAGE/api/bereitschaft/heute?team=team-sendung" \
| jq -c '.error | {name, message}'
bs 'bereitschaft/heute?team=team-sendung' | jq
bs 'bereitschaft/heute?team=team-xyz' -w '%{http_code}\n'Erwartet (die Person wechselt täglich; bs nutzt
curl -f und gibt beim 404 nur den Statuscode aus):
{"name":"AuthenticationError","message":"Missing credentials"}
{
"team": "team-sendung",
"datum": "2026-10-13",
"person": "user:default/ben.kraus"
}
404
Warum? Im neuen Backend-System gilt für jede Route die
Standard-Policy des httpRouter: Nur Anfragen mit gültigem
Token kommen durch – entweder ein User-Token aus dem Login oder ein
Service-Token. bs schickt den statischen Lab-Token aus
backend.auth.externalAccess, das Backend sieht den
Service-Principal lab-cli. Ein falscher Token liefert
Illegal token, ebenfalls 401.
Sicherheit: Öffnen lässt sich eine Route nur bewusst im Plugin, z. B.
httpRouter.addAuthPolicy({ path: '/health', allow: 'unauthenticated' }). Wer zusätzlich nur User zulassen will, prüft im Handlerawait httpAuth.credentials(req, { allow: ['user'] })– so macht es die Todo-Vorlage.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein Frontend-Plugin erzeugen
cd ~/backstage-lab/portal
yarn newWähle frontend-plugin und wieder die ID
bereitschaft. Erwartet (gekürzt):
? What do you want to create? frontend-plugin - A new frontend plugin
? Enter the ID of the plugin [required] bereitschaft
templating plugins/bereitschaft ✔
app adding import ✔
executing yarn install ✔
executing yarn lint --fix ✔
„adding import” ist ein Überbleibsel aus dem alten Frontend-System:
App.tsx bleibt unverändert. Der Generator trägt das Paket
nur als Abhängigkeit der App ein:
git diff packages/app/package.json | grep bereitschaft
grep -n 'packages: all' app-config.yamlErwartet:
+ "@internal/backstage-plugin-bereitschaft": "workspace:^",
6: packages: all
Das reicht: app.packages: all lässt die CLI alle
Frontend-Plugins aus den Abhängigkeiten von packages/app
automatisch einbinden (Feature-Discovery). Die Vorlage bringt eine Seite
mit, ein PageBlueprint auf Pfad
/bereitschaft.
~/backstage-lab/setup/portal.sh restart- Öffne
http://localhost:3000/bereitschaft. - Erwartet: die Seite „Welcome to bereitschaft!” wie in der Abbildung.
Die zwei Einträge sind Beispieldaten – die Seite fragt
/todos, das gibt es seit Drill 2 nicht mehr.
Tipp: Explizit statt automatisch:
app.packagesakzeptiert stattallauchinclude:/exclude:mit Paketnamen. Mitexclude: ['@internal/backstage-plugin-bereitschaft']taucht das Plugin erst auf, wenn du es inApp.tsximportierst und unterfeatureseinträgst.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Die Entity-Karte
Die Karte braucht zwei weitere Pakete:
plugin-catalog-react (Blueprint, useEntity,
EntityRefLink) und catalog-model
(parseEntityRef).
cd ~/backstage-lab/portal/plugins/bereitschaft
yarn add @backstage/plugin-catalog-react @backstage/catalog-model
jq -r '.dependencies | keys[]' package.jsonErwartet:
@backstage/catalog-model
@backstage/core-components
@backstage/frontend-plugin-api
@backstage/plugin-catalog-react
@backstage/theme
@backstage/ui
react-use
Beide Pakete hat die App schon installiert, yarn add
lädt nichts nach; die Ranges (^3.2.3, ^1.10.1)
passen zu Backstage 1.55.
Die Seite der Vorlage fliegt raus, das Plugin bekommt stattdessen ein
EntityCardBlueprint. Der Filter
{ kind: 'component' } sorgt dafür, dass die Karte nur auf
Component-Seiten erscheint.
rm -r src/components/TodoPage src/components/TodoList src/routes.ts
cat > src/plugin.tsx <<'EOF'
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
import { EntityCardBlueprint } from '@backstage/plugin-catalog-react/alpha';
export const bereitschaftCard = EntityCardBlueprint.make({
name: 'heute',
params: {
filter: { kind: 'component' },
loader: () =>
import('./components/BereitschaftCard').then(m => <m.BereitschaftCard />),
},
});
export const bereitschaftPlugin = createFrontendPlugin({
pluginId: 'bereitschaft',
extensions: [bereitschaftCard],
});
EOFDie Komponente liest spec.owner der aktuellen Entity.
parseEntityRef macht aus team-sendung und
group:default/team-sendung (OwnerPicker, Tag 5) denselben
Namen. plugin://bereitschaft/… löst fetchApi
über die discoveryApi zur Backend-URL auf und hängt den
Token des Users an.
mkdir -p src/components/BereitschaftCard
cat > src/components/BereitschaftCard/BereitschaftCard.tsx <<'EOF'
import { InfoCard, Progress, WarningPanel } from '@backstage/core-components';
import { fetchApiRef, useApi } from '@backstage/frontend-plugin-api';
import { parseEntityRef } from '@backstage/catalog-model';
import { EntityRefLink, useEntity } from '@backstage/plugin-catalog-react';
import { Text } from '@backstage/ui';
import useAsync from 'react-use/esm/useAsync';
type Bereitschaft = { team: string; datum: string; person: string };
export const BereitschaftCard = () => {
const { entity } = useEntity();
const { fetch } = useApi(fetchApiRef);
const owner = String(entity.spec?.owner ?? '');
const team = parseEntityRef(owner, { defaultKind: 'group' }).name;
const { value, loading, error } = useAsync(async () => {
const res = await fetch(`plugin://bereitschaft/heute?team=${team}`);
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
return (await res.json()) as Bereitschaft;
}, [fetch, team]);
return (
<InfoCard title="Bereitschaft">
{loading && <Progress />}
{error && <WarningPanel title={`Kein Plan für ${team}`} />}
{value && (
<Text as="p">
Heute ({value.datum}) für {team}:{' '}
<EntityRefLink entityRef={value.person} />
</Text>
)}
</InfoCard>
);
};
EOF
echo "export { BereitschaftCard } from './BereitschaftCard';" \
> src/components/BereitschaftCard/index.ts~/backstage-lab/setup/portal.sh restart- Öffne im Katalog
sendungs-apiund scrolle im Tab Overview nach unten. - Erwartet: unter den API-Karten die Karte
Bereitschaft mit „Heute (…) für team-sendung:” und dem
verlinkten Namen.
EntityRefLinkzeigt dendisplayNameder User-Entity, also „Ben Kraus” stattben.kraus. - Öffne die API
sendungs-api. Erwartet: keine Bereitschaftskarte – der Filter wirkt.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Die Karte konfigurieren
Die Extension-ID setzt sich aus Art, Plugin-ID und Name zusammen:
entity-card:bereitschaft/heute. Wie jede Extension (Tag 9)
lässt sie sich in app-config.yaml konfigurieren.
EntityCardBlueprint kennt die Optionen filter
und type; type: info schiebt die Karte in die
rechte Spalte. Hänge in app-config.yaml als letzten Eintrag
unter app.extensions an (Einrückung wie die übrigen
Einträge, Vorlage in code/tag11/app-extensions.yaml):
# Tag 11: Bereitschaftskarte in die rechte Spalte
- entity-card:bereitschaft/heute:
config:
type: info~/backstage-lab/setup/portal.sh restart- Lade die Entity-Seite von
sendungs-apineu. - Erwartet: die Karte steht jetzt oben rechts über About, wie in der Abbildung.
- Öffne in der Sidebar App-Struktur und wähle den Tab Detailed.
- Erwartet: unter
page:catalog/entity→entity-content:catalog/overview→ cards stehtentity-card:bereitschaft/heuteals erste Karte, wie in der Abbildung.
Warum in app-config.yaml und nicht im Code? So
entscheidet der Plattform-Betrieb, wo die Karte sitzt oder ob sie für
bestimmte Entities aus ist – ohne neuen Build.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Tests, Typen, Lint
Die generierten Tests prüfen noch die Todo-API. Für das Backend
ersetzt du sie durch einen Unit-Test des Routers (ohne Backend, mit
supertest) und einen Plugin-Test mit
startTestBackend, der auch die Auth-Policy prüft:
cd ~/backstage-lab/portal
cat > plugins/bereitschaft-backend/src/router.test.ts <<'EOF'
import { mockErrorHandler } from '@backstage/backend-test-utils';
import express from 'express';
import request from 'supertest';
import { createRouter, wer } from './router';
const teams = { 'team-sendung': ['anna.berger', 'ben.kraus'] };
describe('createRouter', () => {
const app = express().use(createRouter({ teams })).use(mockErrorHandler());
it('liefert die Bereitschaft eines Teams', async () => {
const res = await request(app).get('/heute?team=team-sendung');
expect(res.status).toBe(200);
expect(res.body.person).toMatch(
/^user:default\/(anna\.berger|ben\.kraus)$/,
);
});
it('antwortet 400 ohne team und 404 für unbekannte Teams', async () => {
expect((await request(app).get('/heute')).status).toBe(400);
expect((await request(app).get('/heute?team=team-xyz')).status).toBe(404);
});
});
describe('wer', () => {
it('wechselt jeden Tag', () => {
const p = ['a', 'b'];
const montag = wer(p, new Date('2026-10-12T08:00:00Z'));
expect(wer(p, new Date('2026-10-13T08:00:00Z'))).not.toBe(montag);
});
});
EOF
cat > plugins/bereitschaft-backend/src/plugin.test.ts <<'EOF'
import {
mockCredentials,
mockServices,
startTestBackend,
} from '@backstage/backend-test-utils';
import request from 'supertest';
import { bereitschaftPlugin } from './plugin';
describe('bereitschaftPlugin', () => {
it('liest die Teams aus der Config und verlangt Auth', async () => {
const { server } = await startTestBackend({
features: [
bereitschaftPlugin,
mockServices.rootConfig.factory({
data: { bereitschaft: { teams: { 'team-web': ['chris.dietz'] } } },
}),
],
});
const url = '/api/bereitschaft/heute?team=team-web';
const res = await request(server).get(url).expect(200);
expect(res.body.person).toBe('user:default/chris.dietz');
await request(server)
.get(url)
.set('Authorization', mockCredentials.none.header())
.expect(401);
});
});
EOFstartTestBackend behandelt Anfragen ohne Header als
angemeldeten Mock-User; mockCredentials.none simuliert den
anonymen curl aus Drill 3. Für das Frontend liegt der Test
der Karte im Begleitcode. Er rendert die Karte mit einer Fake-Entity und
einer fetch-Attrappe und prüft die aufgerufene URL:
cp ~/backstage-lab/code/tag11/frontend/src/components/BereitschaftCard/*.test.tsx \
plugins/bereitschaft/src/components/BereitschaftCard/
grep -n 'apis:\|mountedRoutes\|toHaveBeenCalledWith' -A1 \
plugins/bereitschaft/src/components/BereitschaftCard/BereitschaftCard.test.tsxErwartet:
27: apis: [[fetchApiRef, { fetch }]],
28: mountedRoutes: { '/catalog/:namespace/:kind/:name': entityRouteRef },
29- },
--
33: expect(fetch).toHaveBeenCalledWith(
34- 'plugin://bereitschaft/heute?team=team-sendung',
mountedRoutes braucht EntityRefLink, sonst
bricht der Test mit
No path for routeRef{type=absolute,id=catalog:entity} ab.
Jetzt alles prüfen:
CI=true yarn test plugins/bereitschaft
yarn tsc && echo "✔ tsc"
yarn --cwd plugins/bereitschaft lint && yarn --cwd plugins/bereitschaft-backend lintErwartet (gekürzt, Pfade abgeschnitten):
PASS @internal/backstage-plugin-bereitschaft-backend …/router.test.ts
PASS @internal/backstage-plugin-bereitschaft-backend …/plugin.test.ts
PASS @internal/backstage-plugin-bereitschaft …/plugin.test.ts
PASS @internal/backstage-plugin-bereitschaft …/BereitschaftCard.test.tsx
Test Suites: 4 passed, 4 total
Tests: 6 passed, 6 total
✔ tsc
CI=true schaltet den Watch-Modus ab, das Muster
plugins/bereitschaft trifft beide Pakete. Lint ohne Ausgabe
heißt: keine Befunde. Das Root-Skript yarn lint prüft nur
Änderungen seit origin/master – im Lab ohne Remote nimm die
Paket-Skripte oder yarn lint:all.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
mkdir -p ~/backstage-lab/tag11
cp ~/backstage-lab/code/tag11/kontrolle.sh ~/backstage-lab/tag11/
bash ~/backstage-lab/tag11/kontrolle.shDas Skript prüft die Dateien im Portal (Eintrag im Backend, Abhängigkeit der App, Filter, Extension-Konfiguration) und die API mit und ohne Token. Ein Auszug:
t "Ohne Token: 401" \
"[ \$(curl -s -o /dev/null -w '%{http_code}' \
\$BACKSTAGE/api/bereitschaft/heute?team=team-sendung) = 401 ]"
t "Mit Lab-Token: Person aus team-sendung" \
"bs 'bereitschaft/heute?team=team-sendung' |
jq -e '.person | test(\"anna.berger|ben.kraus\")'"Erwartet:
✔ Backend-Plugin in packages/backend/src/index.ts
✔ Frontend-Plugin als Abhängigkeit von packages/app
✔ Karte nutzt EntityCardBlueprint mit Filter kind=component
✔ Karte in app-config.yaml als info konfiguriert
✔ Ohne Token: 401
✔ Mit Lab-Token: Person aus team-sendung
✔ Unbekanntes Team: 404
Challenge
Die Karte soll zusätzlich die Telefonnummer der Person zeigen. Die
Nummern stehen in der Konfiguration unter
bereitschaft.telefon, je User-Name eine.
Hinweis: Das Frontend kann
bereitschaft.* nicht lesen (Config ist dort nur mit
@visibility frontend sichtbar) – liefere die Nummer im
Backend mit.
Lösung
Die geänderten Dateien liegen in code/tag11/challenge/.
Die Kernzeilen:
// router.ts – neue, optionale Option und ein Feld mehr in der Antwort
export function createRouter(options: {
teams: Teams;
telefon?: Record<string, string>;
}): express.Router {
// …
const name = wer(personen, datum);
res.json({
team,
datum: datum.toISOString().slice(0, 10),
person: `user:default/${name}`,
telefon: options.telefon?.[name],
});
// plugin.ts
const telefon =
config.getOptional<Record<string, string>>('bereitschaft.telefon') ??
{};
httpRouter.use(createRouter({ teams, telefon }));
// BereitschaftCard.tsx – Typ um telefon?: string ergänzen, dann:
{value?.telefon && <Text as="p">Telefon: {value.telefon}</Text>}telefon ist optional, damit router.test.ts
unverändert kompiliert. Der Konfig-Block ist zwei Leerzeichen eingerückt
und gehört unter bereitschaft: – er funktioniert per
>> nur, wenn dieser Block am Ende der Datei
steht.
cd ~/backstage-lab/portal
C=~/backstage-lab/code/tag11/challenge
cp $C/router.ts $C/plugin.ts plugins/bereitschaft-backend/src/
cp $C/BereitschaftCard.tsx plugins/bereitschaft/src/components/BereitschaftCard/
cat $C/telefon.yaml >> app-config.local.yaml
yarn tsc && CI=true yarn test plugins/bereitschaft 2>&1 | grep '^Tests:'
~/backstage-lab/setup/portal.sh restart
bs 'bereitschaft/heute?team=team-web' | jqErwartet:
Tests: 6 passed, 6 total
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{
"team": "team-web",
"datum": "2026-10-13",
"person": "user:default/thomas.zachmann",
"telefon": "+49 40 5550-202"
}
Auf der Entity-Seite von tracking-web zeigt die Karte
jetzt die Nummer, wie in der Abbildung.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Eigene Plugins gehören in ein eigenes Repo oder einen
Monorepo-Ordner mit CI:
yarn tsc,yarn test,yarn lintundyarn buildals Gate vor jedem Merge. - Wiederverwendbare Plugins veröffentlichst du in eine interne
npm-Registry (
--scope,publishConfig);@internal/…ist nur für den Monorepo gedacht. - Bereitschaftsdaten kommen in der Praxis aus PagerDuty oder Opsgenie. Dafür gibt es Community-Plugins – vor dem Selberbauen im Plugin-Verzeichnis nachsehen.
- Eine eigene Config braucht ein Schema (
config.d.tsim Plugin), sonst fehlt die Validierung beim Start, und Secrets darin müssen mit@visibility secretmarkiert sein. - Jede neue Route ist Angriffsfläche: Auth-Policy nie pauschal öffnen,
Eingaben validieren (die Vorlage nutzt
zod), schreibende Routen an Permissions koppeln (Tag 12).