Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 9: Die App anpassen

Ziel: Du machst aus dem Vorlagen-Portal das Kranich Entwicklerportal: Startseite, Widgets, Navigation, Logo, Theme und Entity-Seite – überwiegend per Konfiguration. · Dauer: ca. 90 min · Voraussetzung: Tag 8

Briefing

  • Das neue Frontend-System baut die App als Baum aus Extensions. Jede Extension hat eine ID <art>:<plugin>/<name> (z. B. page:home, entity-card:catalog/about) und hängt an einem Eingang ihres Elternknotens.
  • Plugins liefern Extensions mit. app.extensions in der Konfiguration schaltet sie ab, konfiguriert sie, hängt sie um und legt ihre Reihenfolge fest – ohne Code.
  • Code brauchst du nur für neue Extensions: Logo, Sidebar-Aufbau, eigenes Theme. Sie liegen als Module in packages/app/src/modules/.
  • app.extensions ist eine Liste. Eine zweite Config-Datei ersetzt sie komplett.
app/root
└─ children ─► app/layout
               ├─ nav ─────► app/nav ── content ─► nav-content:app
               └─ content ─► app/routes
                             └─ routes ─┬─► page:home ── widgets ─► home-page-widget:…
                                        ├─► page:catalog ── filters
                                        └─► page:catalog/entity
                                            └ contents ► entity-content:catalog/overview
                                                         └ cards ► entity-card:…

Drill 1: Der Extension-Baum

Ausgangslage ist das Ende von Tag 8. Der Katalog liegt noch auf /, die Startseite mit Widgets auf /home.

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
mkdir -p ~/backstage-lab/tag09 && cd ~/backstage-lab/tag09
  1. Öffne http://localhost:3000, klicke auf Enter und unten in der Sidebar auf Visualizer.
  2. Die Ansicht Tree zeigt den ganzen Baum als Grafik, Detailed jeden Knoten mit seinen Ausgaben (React Element, Utility API, Route Path, Route Ref).
  3. Klicke auf Text und scrolle zu <app/routes>.
  4. Erwartet: der Baum als eingerückter Text wie in der Abbildung. Unter routes [ hängen alle Seiten, unter page:catalog die Filter der Katalogseite.
Extension-Baum in der Text-Ansicht des Visualizers ab app/root

Hier findest du jede ID, die du gleich in app.extensions brauchst. Etwas weiter unten stehen page:catalog/entity mit allen Karten der Entity-Seite und page:home mit den Widgets. Ganz unten blendet Show Disabled abgeschaltete Extensions grau ein.

Tipp: Die IDs ergeben sich aus dem Code: HomePageWidgetBlueprint mit name: 'toolkit' im Plugin home wird zu home-page-widget:home/toolkit. Im installierten Paket findest du sie z. B. mit grep -n "name:" node_modules/@backstage/plugin-home/dist/alpha.esm.js.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Wo app.extensions wirkt

Was gilt gerade? config:print zeigt die zusammengeführte Konfiguration aller app-config*.yaml, mit --frontend nur den Teil, den der Browser sieht.

cd ~/backstage-lab/portal
yarn backstage-cli config:print --frontend --format json 2>/dev/null \
  | jq -r '.app.extensions[] | keys[0]'

Erwartet:

page:catalog
home-page-widget:home/toolkit
home-page-widget:home/world-clock
page:home

Das sind die vier Einträge aus app-config.yaml der Vorlage. Jetzt ein Experiment: Du willst nur lokal Register Existing Component abschalten und trägst dafür einen Eintrag in app-config.local.yaml ein. Weil dort schon app.title steht, setzt du den Schlüssel mit yq, statt einen zweiten Block app: anzuhängen.

yq -i '.app.extensions = [{"page:catalog-import": false}]' app-config.local.yaml
yarn backstage-cli config:print --frontend --format json 2>/dev/null \
  | jq -c '.app.extensions'
~/backstage-lab/setup/portal.sh restart

Erwartet:

[{"page:catalog-import":false}]
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
  1. Lade http://localhost:3000 neu.
  2. Erwartet: Register Existing Component fehlt in der Sidebar – aber / zeigt jetzt ERROR 404: PAGE NOT FOUND.

Warum? @backstage/config führt Objekte Schlüssel für Schlüssel zusammen, bei Listen gewinnt die Datei mit Vorrang komplett. Die eine Zeile aus der local-Datei hat alle vier Einträge aus app-config.yaml verdrängt: page:catalog liegt wieder auf seinem Standardpfad /catalog, page:home auf /home, und auf / liegt nichts mehr. Das kennst du schon von catalog.locations (Tag 3).

Die Regel für dieses Buch: Die Gestaltung der App gehört in app-config.yaml (wird eingecheckt, gilt für alle), app-config.local.yaml bleibt für Lab-Werte und Secrets. Experiment zurückdrehen:

yq -i 'del(.app.extensions)' app-config.local.yaml
grep -c 'extensions' app-config.local.yaml

Erwartet:

0

Tipp: yq (mikefarah, brew install yq) schreibt die Datei neu und macht dabei aus { seconds: 20 } ein {seconds: 20} – inhaltlich dasselbe.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die Startseite auf /

Ein Entwicklerportal begrüßt mit einer Startseite, nicht mit einer Tabelle. Zuerst die Karte Getting Started: Sie ist kein Plugin, sondern ein Widget im App-Modul modules/home. Ersetze ihren Inhalt:

cat > ~/backstage-lab/portal/packages/app/src/modules/home/homeModule.tsx <<'EOF'
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { HomePageWidgetBlueprint } from '@backstage/plugin-home-react/alpha';
import { MarkdownContent } from '@backstage/core-components';

const content = `
## Willkommen im Kranich Entwicklerportal

Alles über unsere Software an einem Ort: Services, APIs, Teams und Doku.

- **[Katalog](/catalog)** – wem gehört was, wer nutzt welche API?
- **[Neues Projekt](/create)** – Golden Paths als Software Templates
- **[Dokumentation](/docs)** – TechDocs direkt aus den Repos

Fragen? Team Plattform, [email protected]
`;

const gettingStartedWidget = HomePageWidgetBlueprint.make({
  name: 'getting-started',
  params: {
    name: 'GettingStarted',
    title: 'Erste Schritte',
    description: 'Einstieg ins Kranich Entwicklerportal',
    components: async () => ({
      Content: () => <MarkdownContent content={content} />,
    }),
  },
});

export const homeModule = createFrontendModule({
  pluginId: 'home',
  extensions: [gettingStartedWidget],
});
EOF

name: 'GettingStarted' ist der Name, unter dem das Layout das Widget referenziert.

Die neue Liste für app.extensions liegt im Begleitcode. Der Anfang mit Startseite, Layout und Widgets:

- page:home:
    config:
      path: /
      defaultConfig:
        - component: HomePageSearchBar
          column: 0
          row: 0
          width: 12
          height: 2
          deletable: false
        - component: GettingStarted
          column: 0
          row: 2
          width: 6
          height: 5
        - component: HomePageToolkit
          column: 6
          row: 2
          width: 6
          height: 3
        # … HomePageWorldClock (Spalte 6, Zeile 5), HomePageStarredEntities (Zeile 7)
- home-page-widget:home/toolkit:
    config:
      tools:
        - url: http://127.0.0.1:3300/kranich
          label: Forgejo
          icon: externalLink
        - url: /create
          label: Neues Projekt
          icon: scaffolder
        # … TechDocs (/docs) und Backstage-Doku
- home-page-widget:home/world-clock:
    config:
      clockConfigs:
        - label: Berlin
          timeZone: Europe/Berlin
        - label: UTC
          timeZone: UTC

page:catalog taucht nicht mehr auf, der Katalog liegt damit auf seinem Standardpfad /catalog. Die Schlüssel defaultConfig, tools und clockConfigs stehen im configSchema der Extensions in @backstage/plugin-home/dist/alpha.esm.js; die Icon-Namen (scaffolder, techdocs, docs, externalLink, …) sind die Standard-Icons der App.

Das Skript extensions-setzen.sh ersetzt den Block unter app.extensions in app-config.yaml durch eine Datei und legt vorher eine Sicherung an:

cd ~/backstage-lab/portal
bash ~/backstage-lab/code/tag09/extensions-setzen.sh \
  ~/backstage-lab/code/tag09/app-extensions.yaml
yarn backstage-cli config:print --frontend --format json 2>/dev/null \
  | jq -r '.app.extensions[] | keys[0]'
~/backstage-lab/setup/portal.sh restart

Erwartet:

✔ app.extensions aus app-extensions.yaml übernommen (Sicherung: app-config.yaml.bak)
page:home
home-page-widget:home/toolkit
home-page-widget:home/world-clock
home-page-widget:home/random-joke
page:app-visualizer
entity-card:catalog/about
entity-card:catalog-graph/relations
entity-card:org/ownership
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
  1. Öffne http://localhost:3000 (Fenster mindestens ca. 1500 px breit).
  2. Erwartet: die Startseite wie in der Abbildung – Suche, Erste Schritte, Toolkit mit dem Forgejo-Link und World Clocks mit Berlin und UTC.
  3. Klicke in der Sidebar auf Catalog. Die Adresszeile zeigt jetzt http://localhost:3000/catalog.
Kranich-Startseite mit Erste Schritte, Toolkit und Weltuhren

Die Abbildung zeigt schon Logo und Theme aus Drill 5 und 6. Das Raster hat 12 Spalten erst ab der Breakpoint-Breite lg (1280 px Inhalt), darunter 10 oder weniger – dann rutschen Widgets um.

Achtung: defaultConfig gilt nur, bis jemand die Seite über EDIT umbaut. Danach speichert Backstage das Layout pro User (Bucket home.customHomepage); neue Defaults sieht er erst nach Restore defaults im Bearbeiten-Modus.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Abschalten, umbenennen, umsortieren

Der Rest von app-extensions.yaml kommt ganz ohne Code aus:

# Witze-Widget ruft eine externe API auf – im Firmennetz unerwünscht
- home-page-widget:home/random-joke: false
# Navigation: Seitentitel umbenennen
- page:app-visualizer:
    config:
      title: App-Struktur
# Entity-Seite: About zuerst, darunter der Beziehungsgraph in der rechten Spalte
- entity-card:catalog/about: true
- entity-card:catalog-graph/relations:
    config:
      type: info
      title: Beziehungen
      height: 280
# Gruppen-Seiten: indirekte Ownership von Anfang an
- entity-card:org/ownership:
    config:
      initialRelationAggregation: aggregated

Vier Mechanismen, alle aus dem installierten Code:

Eintrag Wirkung Quelle
- <id>: false Extension abschalten readAppExtensionsConfig
config.title Seitentitel und Sidebar-Text PageBlueprint
config.type: info Karte in die rechte Spalte EntityCardBlueprint
Reihenfolge der Liste genannte Extensions zuerst resolveAppNodeSpecs
  1. Klicke unten in der Sidebar auf App-Struktur (vorher Visualizer), dann auf Text, scrolle ans Ende und schalte Show Disabled ein.
  2. Erwartet: home-page-widget:home/random-joke steht grau unter page:home wie in der Abbildung.
Abgeschaltetes Random-Joke-Widget grau im Extension-Baum
  1. Öffne im Katalog sendungs-api.
  2. Erwartet: rechts About, darunter die Karte Beziehungen mit Team Sendung und der API wie in der Abbildung. Vorher stand der Graph unten in der linken Spalte.
Entity-Seite mit About und Beziehungen in der rechten Spalte
  1. Öffne über Owner die Gruppe Team Sendung, dann IT (Parent Group). Ownership zeigt jetzt sofort die Summe der Teams – der Schalter Include indirect ownership steht schon an (Tag 4, Drill 5).

Achtung: Ein Tippfehler in einer ID bricht nichts, er wird nur ignoriert. Die Browser-Konsole meldet dann INVALID_EXTENSION_CONFIG_KEY: Extension home-page-widget:home/randomjoke does not exist. Bleibt eine Änderung wirkungslos, schau zuerst dort nach.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Sidebar und Logo

Die Reihenfolge der Sidebar steht nicht in der Config, sondern in modules/nav/Sidebar.tsx: nav.take('page:…') setzt einen Eintrag an genau diese Stelle, nav.rest({ sortBy: 'title' }) sortiert den Rest alphabetisch. Docs soll direkt unter Create stehen:

cd ~/backstage-lab/portal/packages/app/src/modules/nav
sed -i '' "s|^\( *\){nav.take('page:scaffolder')}$|&\n\1{nav.take('page:techdocs')}|" \
  Sidebar.tsx
grep -n "nav.take('page:" Sidebar.tsx

Erwartet:

25:      nav.take('page:search'); // Using search modal instead
26:      nav.take('page:notifications'); // Using NotificationsSidebarItem manually …
36:            {nav.take('page:home')}
37:            {nav.take('page:catalog')}
38:            {nav.take('page:scaffolder')}
39:            {nav.take('page:techdocs')}
54:            {nav.take('page:app-visualizer')}
55:            {nav.take('page:user-settings')}

Die Texte der Einträge kommen dagegen aus den Seiten selbst – deshalb hat in Drill 4 config.title gereicht. Jetzt das Logo: SidebarLogo.tsx zeigt LogoFull bei ausgeklappter und LogoIcon bei eingeklappter Sidebar. Beide ersetzt du durch ein schlichtes SVG mit Kranich-Bildmarke:

cat > LogoIcon.tsx <<'EOF'
import { makeStyles } from '@material-ui/core';

const useStyles = makeStyles({
  svg: { width: 'auto', height: 28 },
});

// Bildmarke: blaues Quadrat, stilisierter Kranich, rote Krone
export const KranichMark = () => (
  <g>
    <rect width="40" height="40" rx="8" fill="#1d4e89" />
    <path
      d="M9 30 L20 21 L31 9 L24 22 L33 24 L20 25 Z"
      fill="#ffffff"
    />
    <circle cx="31" cy="9" r="3.5" fill="#c8102e" />
  </g>
);

export const LogoIcon = () => {
  const classes = useStyles();
  return (
    <svg
      className={classes.svg}
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 40 40"
    >
      <KranichMark />
    </svg>
  );
};
EOF
cat > LogoFull.tsx <<'EOF'
import { makeStyles } from '@material-ui/core';
import { KranichMark } from './LogoIcon';

const useStyles = makeStyles({
  svg: { width: 'auto', height: 30 },
});

// Bildmarke plus Schriftzug „Kranich" für die ausgeklappte Sidebar
export const LogoFull = () => {
  const classes = useStyles();
  return (
    <svg
      className={classes.svg}
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 170 40"
    >
      <KranichMark />
      <text
        x="48"
        y="29"
        fill="#ffffff"
        fontFamily="Helvetica, Arial, sans-serif"
        fontSize="26"
        fontWeight="bold"
      >
        Kranich
      </text>
    </svg>
  );
};
EOF

yarn start übersetzt Frontend-Code beim Speichern neu – kein Neustart nötig.

  1. Lade das Portal neu.
  2. Erwartet: oben links die Bildmarke mit dem Schriftzug Kranich, darunter Home, Catalog, Create, Docs – wie in der Abbildung der Startseite in Drill 3.
  3. Klicke auf das Logo. Es verlinkt auf /, also jetzt auf die Startseite.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Hell, dunkel, Kranich

  1. Klicke unten in der Sidebar auf Settings.
  2. Unter Appearance wählst du DARK, LIGHT oder AUTO (folgt dem Betriebssystem). Klicke auf DARK.
  3. Erwartet: die ganze App wird dunkel wie in der Abbildung. Die Wahl speichert der Browser (localStorage, Schlüssel theme).
Appearance-Karte in den Settings mit gewähltem Dark-Theme

Die beiden Themes sind Extensions des Plugins app: theme:app/light und theme:app/dark. Ein drittes Theme ist eine weitere Extension aus ThemeBlueprint (@backstage/plugin-app-react). Die Farben baut createUnifiedTheme aus @backstage/theme. Das Paket ist bereits installiert, aber nicht als Abhängigkeit der App eingetragen:

cd ~/backstage-lab/portal
yarn --cwd packages/app add @backstage/theme@^0.7.3
jq '.dependencies["@backstage/theme"]' packages/app/package.json

Erwartet (gekürzt, kann je nach Version abweichen):

➤ YN0000: · Done in 3s 512ms
"^0.7.3"

Die Version ^0.7.3 steht schon in yarn.lock, deshalb lädt yarn nichts nach.

mkdir -p packages/app/src/modules/theme
cat > packages/app/src/modules/theme/index.tsx <<'EOF'
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { ThemeBlueprint } from '@backstage/plugin-app-react';
import PaletteIcon from '@material-ui/icons/Palette';
import {
  UnifiedThemeProvider,
  createUnifiedTheme,
  genPageTheme,
  palettes,
  shapes,
} from '@backstage/theme';

// Kranich-Farben: Nachtblau, Kranich-Blau und das Rot der Krone
const kranichTheme = createUnifiedTheme({
  palette: {
    ...palettes.light,
    primary: { main: '#1d4e89' },
    secondary: { main: '#c8102e' },
    navigation: {
      ...palettes.light.navigation,
      background: '#0b2545',
      indicator: '#c8102e',
      selectedColor: '#ffffff',
    },
  },
  defaultPageTheme: 'home',
  pageTheme: {
    home: genPageTheme({ colors: ['#0b2545', '#1d4e89'], shape: shapes.wave }),
  },
});

const kranichThemeExtension = ThemeBlueprint.make({
  name: 'kranich',
  params: {
    theme: {
      id: 'kranich',
      title: 'Kranich',
      variant: 'light',
      icon: <PaletteIcon />,
      Provider: ({ children }) => (
        <UnifiedThemeProvider theme={kranichTheme} children={children} />
      ),
    },
  },
});

export const themeModule = createFrontendModule({
  pluginId: 'app',
  extensions: [kranichThemeExtension],
});
EOF
cat > packages/app/src/App.tsx <<'EOF'
import { createApp } from '@backstage/frontend-defaults';
import catalogPlugin from '@backstage/plugin-catalog/alpha';
import { navModule } from './modules/nav';
import { homeModule } from './modules/home';
import { themeModule } from './modules/theme';

export default createApp({
  features: [catalogPlugin, navModule, homeModule, themeModule],
});
EOF

Das Modul gehört zum Plugin app, die neue Extension heißt also theme:app/kranich.

  1. Lade Settings neu. Unter Appearance steht jetzt KRANICH mit Paletten-Symbol. Klicke darauf.
  2. Öffne Catalog.
  3. Erwartet: nachtblaue Sidebar mit roter Markierung am aktiven Eintrag, blaue Buttons wie in der Abbildung. Die Überschrift „Kranich Logistik Catalog” kommt aus organization.name in deiner app-config.local.yaml.
Katalogseite im Kranich-Theme mit nachtblauer Sidebar

Warum ändert sich der Seitenkopf nicht? Er kommt aus der Extension component:app/core-page-layout, die PluginHeader aus @backstage/ui nutzt. Diese neue UI-Bibliothek wird über CSS-Variablen gestaltet, nicht über das MUI-Theme. createUnifiedTheme wirkt auf alle Material-UI-Komponenten (Sidebar, Buttons, Links, Karten).

Fortschritt speichern? Kostenlos registrieren

Drill 7: Prüfen vor dem Commit

Frontend-Code prüft yarn start nicht auf Typen oder fehlende Abhängigkeiten. Das erledigen Lint und Tests der App:

cd ~/backstage-lab/portal
yarn --cwd packages/app lint && echo "✔ lint"
CI=true yarn --cwd packages/app test 2>&1 | grep -E '✓|Tests:'

Erwartet:

✔ lint
    ✓ should render (19 ms)
Tests:       1 passed, 1 total

Ohne den Eintrag in package.json aus Drill 6 hätte Lint abgelehnt:

@backstage/theme must be declared in dependencies of packages/app/package.json,
run 'yarn --cwd packages/app add @backstage/theme' from the project root

Die Prüfung heißt @backstage/no-undeclared-imports. Sie verhindert, dass ein Import nur zufällig über ein anderes Paket funktioniert und beim nächsten Upgrade bricht.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Die Oberfläche lässt sich per curl kaum prüfen – das Frontend ist eine Single-Page-App. Prüfbar sind der Titel im HTML, die wirksame Konfiguration und die Dateien.

cat > ~/backstage-lab/tag09/kontrolle.sh <<'EOF'
#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 9 (✔/✘). Exit-Code = Anzahl Fehler.
source ~/backstage-lab/setup/env.sh
cd "$PORTAL" || exit 1
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
  else echo "✘ $1"; fail=$((fail+1)); fi; }
# wirksame Frontend-Konfiguration (alle app-config*.yaml zusammengeführt)
cfg=$(yarn backstage-cli config:print --frontend --format json 2>/dev/null)
ext() { jq -e --arg id "$1" \
  '[.app.extensions[] | select(type == "object" and has($id)) | .[$id]][0]' <<<"$cfg"; }

t "Frontend liefert Titel Kranich Entwicklerportal" \
  "curl -sf $APP/ | grep -q '<title>Kranich Entwicklerportal</title>'"
t "Keine app.extensions in app-config.local.yaml" \
  "! grep -q '^  extensions:' app-config.local.yaml"
t "page:home liegt auf /" "ext page:home | jq -e '.config.path == \"/\"'"
t "page:catalog nicht mehr auf / umgebogen" "! ext page:catalog"
t "Random Joke abgeschaltet" \
  "ext home-page-widget:home/random-joke | jq -e '. == false'"
t "Toolkit verlinkt Forgejo" \
  "ext home-page-widget:home/toolkit | jq -e '.config.tools[] |
     select(.label == \"Forgejo\")'"
t "Weltuhr zeigt Berlin" \
  "ext home-page-widget:home/world-clock | jq -e '.config.clockConfigs[] |
     select(.timeZone == \"Europe/Berlin\")'"
t "Logo mit Schriftzug Kranich" \
  "grep -q 'Kranich' packages/app/src/modules/nav/LogoFull.tsx"
t "Kranich-Theme in App.tsx registriert" \
  "grep -q themeModule packages/app/src/App.tsx"
t "@backstage/theme als Abhängigkeit deklariert" \
  "jq -e '.dependencies[\"@backstage/theme\"]' packages/app/package.json"
exit "$fail"
EOF
bash ~/backstage-lab/tag09/kontrolle.sh

Erwartet:

✔ Frontend liefert Titel Kranich Entwicklerportal
✔ Keine app.extensions in app-config.local.yaml
✔ page:home liegt auf /
✔ page:catalog nicht mehr auf / umgebogen
✔ Random Joke abgeschaltet
✔ Toolkit verlinkt Forgejo
✔ Weltuhr zeigt Berlin
✔ Logo mit Schriftzug Kranich
✔ Kranich-Theme in App.tsx registriert
✔ @backstage/theme als Abhängigkeit deklariert

Den Titel im HTML setzt packages/app/public/index.html mit config.getOptionalString('app.title') – er stammt aus deiner local-Datei. Mit dem Experiment aus Drill 2 schlagen sechs Prüfungen fehl.

Challenge

Die Widgets Recently Visited und Most Visited gibt es schon, sie bleiben aber leer. Bring beide unter die Favoriten auf die Startseite und sorge dafür, dass sie sich füllen – nur per Konfiguration.

Hinweis: Im Visualizer stehen unter api: und app-root-element: zwei Extensions des Plugins home, die ab Werk abgeschaltet sind.

Lösung

Die Datei challenge/app-extensions.yaml ist die Liste aus Drill 3 plus zwei Layout-Einträgen und zwei eingeschalteten Extensions:

        - component: HomePageRecentlyVisited
          column: 0
          row: 10
          width: 6
          height: 4
        - component: HomePageMostVisited
          column: 6
          row: 10
          width: 6
          height: 4
# Besuchsverlauf: API und Listener sind ab Werk abgeschaltet
- api:home/visits: true
- app-root-element:home/visit-listener: true
cd ~/backstage-lab/portal
bash ~/backstage-lab/code/tag09/extensions-setzen.sh \
  ~/backstage-lab/code/tag09/challenge/app-extensions.yaml
~/backstage-lab/setup/portal.sh restart
  1. Öffne ein paar Seiten, z. B. sendungs-api, Docs und wieder sendungs-api.
  2. Klicke auf Home und scrolle nach unten.
  3. Erwartet: beide Widgets mit deinen Besuchen wie in der Abbildung.
Recently Visited und Most Visited auf der Startseite

app-root-element:home/visit-listener zeichnet jeden Seitenwechsel auf, api:home/visits speichert ihn über die Storage-API der App. Die stellt in der Vorlage api:app/user-settings-storage bereit – die Besuche liegen also pro User im Backend, nicht nur im Browser.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • app.extensions gehört in app-config.yaml und damit ins Review. Umgebungen unterscheiden sich über app-config.production.yaml – aber nur mit kompletter Liste, denn Listen werden ersetzt, nicht zusammengeführt.
  • Widgets mit externen Aufrufen (Random Joke, Wetter, Feeds) schaltest du im Firmennetz ab; die Content Security Policy (backend.csp) blockiert sie sonst ohnehin oder verlangt Ausnahmen.
  • Logo, Farben und Schrift gehören in ein kleines Theme-Modul, nicht verstreut in Komponenten. Prüfe Kontraste (WCAG) für hell und dunkel; viele Firmen geben nur ein Theme frei.
  • Der Visualizer ist ein Werkzeug für Plattform-Teams. In Produktion schaltest du ihn ab (- page:app-visualizer: false) oder lässt ihn nur intern zu.
  • Bei jedem Backstage-Upgrade (Tag 14) können Extension-IDs und configSchema sich ändern. Ein Kontrollskript wie oben fängt stille Ignorierungen ab.