MFE Manifest erstellen

Wie man ein mfe-manifest.json erstellt, um das eigene Microfrontend im MFE Portal zu registrieren.

12. August 2026 Christian Engel

Warum ein Manifest?

Ein mfe-manifest.json ist die einzige Datei, die du pflegen musst, um dein Microfrontend im MFE Portal sichtbar und nutzbar zu machen. Du beschreibst dein MFE einmal deklarativ – Ablageort, Integrationsart, Attribute – und bekommst dafür automatisch mehrere Dinge zurück:

Aufnahme in den MFE-Katalog. Das Portal durchsucht die GitHub-Organisation automatisch (via Code Search) nach mfe-manifest.json-Dateien und nimmt dein MFE in den zentralen Katalog auf. Ohne Pull Request am Portal, ohne manuelle Registrierung.
Automatisches Preview. Sobald dein MFE im Katalog ist, kann es im Portal live gestartet und mit verschiedenen Attributwerten und Umgebungen interaktiv getestet werden – ohne dass Konsument:innen dein Repo lokal auschecken müssen.
Automatische Integrationsdokumentation. Aus dem Manifest generiert das Portal fertige, kopierbare Integrations-Snippets für Angular, React und Salesforce (iFrame wie WebComponent). Deine Attribute, Events und URLs sind darin bereits korrekt eingesetzt – die Doku bleibt automatisch synchron mit deiner Deklaration.
Lokale Entwicklung über die Development CLI. Dasselbe Manifest treibt die Development CLI an: Damit kannst du dein MFE lokal gegen die Portal-Integration entwickeln und testen, statt Integrationscode von Hand nachzubauen.

Kurz: Das Manifest ist die Single Source of Truth für dein MFE. Du deklarierst es an einer Stelle in deinem eigenen Repository, und Katalog, Preview, Integrationsdoku und lokale Entwicklung ergeben sich daraus automatisch.

So funktioniert die Aggregation

Jedes Team pflegt seine mfe-manifest.json-Dateien dezentral im eigenen Repository. Das MFE Portal aggregiert diese Manifeste automatisch via GitHub Code Search – es gibt also keine zentrale Registry, die du aktualisieren müsstest. Neue oder geänderte Manifeste landen beim nächsten Aggregationslauf im Katalog.

Schnellstart

Enthält dein Repository genau ein MFE, erstellst du eine mfe-manifest.json im Root:

{
  "$schema": "https://mfe-portal.entwicklung.dvag/schemas/mfe-manifest.schema.json",
  "type": "bundle",
  "group": {
    "id": "mein-service",
    "name": "Mein Service",
    "description": "Alle MFEs rund um meinen Service"
  },
  "mfes": [
    {
      "id": "mein-mfe",
      "name": "Mein Microfrontend",
      "description": "Beschreibung des MFEs",
      "github": "https://github.com/dvag/mein-service",
      "hints": {
        "fullPage": false
      },
      "integrations": {
        "iFrame": {
          "src": "https://mein-mfe.%ENV%.dvag",
          "environments": ["entwicklung", "integration", "abnahme"],
          "hints": {
            "autoScaling": true,
            "salesforceCanvasAutoScaling": false
          }
        }
      }
    }
  ]
}

Nutze die $schema-Property für Autovervollständigung und Validierung in deiner IDE.

Pflichtfelder auf einen Blick

Ebene	Pflichtfelder
Gruppe	`id`, `name`
MFE	`id`, `name`, `hints.fullPage`, `integrations` (mindestens eine Integration)
iFrame-Integration	`src`, `environments`, `hints.autoScaling`, `hints.salesforceCanvasAutoScaling`
WebComponent-Integration	`src`, `environments`, `componentName`, `hints.urlRouter`

Die id eines MFEs muss katalogweit eindeutig sein – sie wird als Schlüssel für Preview-Links, Integrationsdoku und die Development CLI verwendet.

Liegen mehrere MFEs im Repository (Monorepo), solltest du die Manifeste aufteilen statt alles in eine Datei zu schreiben – siehe Monorepo-Strategien.

Manifest von GitHub Copilot erstellen lassen

Du musst das Manifest nicht von Hand schreiben. Copilot kann den Code analysieren und das Manifest daraus ableiten – es braucht dafür nur zwei Referenzen: das JSON Schema und diesen Guide.

Öffne Copilot Chat im Agent-Modus in deinem Repository. Je nachdem, was du vorhast, passt einer der folgenden Prompts.

Ein einzelnes MFE anlegen oder aktualisieren

Der häufigste Fall: Du arbeitest an genau einer App und willst deren Manifest erzeugen oder nach einer Änderung nachziehen.

Öffne dazu den Einstiegspunkt der App im Editor – also die Datei, in der das Custom Element registriert bzw. die App gebootet wird (typischerweise main.ts). Copilot nimmt die aktive Datei als Kontext und weiß damit automatisch, um welche App es geht.

Erstelle bzw. aktualisiere das mfe-manifest.json für die App, zu der die
aktuell geöffnete Datei gehört.

Als Referenz:
- JSON Schema: https://mfe-portal.entwicklung.dvag/schemas/mfe-manifest.schema.json
- Anleitung:   https://mfe-portal.entwicklung.dvag/guides/mfe-manifest

Lies beide URLs zuerst ein.

Ermittle ausgehend von der geöffneten Datei das Projektverzeichnis der App
(das Verzeichnis mit der zugehörigen package.json). Betrachte ausschließlich
diese App - andere MFEs im Repository sind nicht Teil der Aufgabe. Das
Manifest gehört in dieses Projektverzeichnis, nicht ins Repository-Root.
Nenn mir zur Sicherheit den ermittelten Pfad, bevor du schreibst.

Existiert dort bereits ein Manifest, aktualisiere es und behalte gepflegte
Angaben wie contact, documentation, jira_url und links unverändert bei.
Existiert noch keines, lege ein neues an:
- Gibt es im Repository bereits eine Gruppendatei (type "group"), verwende
  type "mfe" und referenziere deren id über das Feld "group".
- Gibt es noch keine, schlage mir eine passende Gruppe vor, bevor du schreibst.

Analysiere den Code der App:
- Wird sie als WebComponent (Custom Element) und/oder als iFrame ausgeliefert?
- Wie lautet der Custom-Element-Tag?
- Welche Attribute bzw. Query-Parameter liest sie beim Start aus?
- Welche Events sendet sie über die MFE-Bridge oder als DOM CustomEvent?
- Implementiert sie das Save-Protokoll der MFE-Bridge?
- Nutzt sie einen URL-basierten Router?

Erzeuge das Manifest mit $schema-Property, sinnvollen title- und
description-Texten sowie testDefault-Werten für alle Attribute.

Frag mich bei allem nach, was du aus dem Code nicht sicher ableiten kannst
(z. B. Umgebungs-URLs oder Ansprechpartner).

Ein ganzes Repository erstmalig erfassen

Für das initiale Onboarding, wenn noch gar keine Manifeste existieren:

Erstelle die mfe-manifest.json Dateien für dieses Repository.

Als Referenz:
- JSON Schema: https://mfe-portal.entwicklung.dvag/schemas/mfe-manifest.schema.json
- Anleitung:   https://mfe-portal.entwicklung.dvag/guides/mfe-manifest

Lies beide URLs zuerst ein.

Prüfe dann, wie viele Microfrontends dieses Repository enthält:
- Bei genau einem MFE: eine einzelne Manifest-Datei im Repository-Root.
- Bei mehreren MFEs (Monorepo): eine Gruppendatei (type "group") im Root und
  pro MFE ein eigenes Manifest (type "mfe") im jeweiligen Projektverzeichnis,
  das die Gruppe über das Feld "group" referenziert.

Zeig mir zuerst die gefundenen MFEs und die geplante Dateiaufteilung,
bevor du Dateien schreibst.

Analysiere für jedes gefundene MFE den zugehörigen Code:
- Wird es als WebComponent (Custom Element) und/oder als iFrame ausgeliefert?
- Wie lautet der Custom-Element-Tag?
- Welche Attribute bzw. Query-Parameter liest es beim Start aus?
- Welche Events sendet es über die MFE-Bridge oder als DOM CustomEvent?
- Implementiert es das Save-Protokoll der MFE-Bridge?
- Nutzt es einen URL-basierten Router?

Erzeuge daraus die Manifeste mit $schema-Property, sinnvollen title- und
description-Texten sowie testDefault-Werten für alle Attribute.

Frag mich bei allem nach, was du aus dem Code nicht sicher ableiten kannst
(z. B. Umgebungs-URLs oder Ansprechpartner).

Ergebnis im Portal ausprobieren

Ein Manifest liest sich schnell plausibel und funktioniert trotzdem nicht. Statt Zeile für Zeile zu prüfen, nimmst du es besser direkt in Betrieb: Die Development CLI startet einen lokalen Preview-Server, der alle Manifeste deines Projekts einsammelt, validiert und aggregiert.

npx @dvag/mfe-portal preview

Der Server läuft auf localhost:9999 und beobachtet deine Manifeste – jede Änderung an der Datei wird sofort übernommen. Öffne dann die Preview-Seite des Portals:

https://mfe-portal.entwicklung.dvag/preview

Dort erscheint dein MFE genau so, wie es später im Katalog aussehen wird – inklusive interaktivem Preview und automatisch generierter Integrationsdokumentation. Das ist der eigentliche Test:

Wird das MFE überhaupt geladen und gerendert?
Greifen die testDefault-Werte, oder bleibt die Ansicht leer?
Stimmen die environments und die dahinterliegenden URLs?
Passt hints.fullPage zum tatsächlichen Platzbedarf?
Liest sich die generierte Integrationsdoku so, wie ein integrierendes Team sie braucht?

Willst du gegen deinen lokalen Dev-Server statt gegen eine deployte Umgebung testen, ergänze --dev:

npx @dvag/mfe-portal preview --dev mein-mfe --wc http://localhost:5173/bundle.js

Alle Optionen sind unter Development CLI beschrieben.

Was der Preview nicht prüfen kann

Ein paar Angaben kann weder Copilot noch der Preview-Server verifizieren – die musst du selbst kontrollieren:

Kontakte und Links — contact, documentation und jira_url kennt Copilot in der Regel nicht.
Beim Aktualisieren — wurden bestehende, manuell gepflegte Felder überschrieben? Ein Blick in den Diff lohnt sich.
Beschreibungstexte — description und title landen unverändert im Katalog und in der Integrationsdoku.

Die folgenden Abschnitte erklären die einzelnen Manifest-Bausteine im Detail – nützlich, um das generierte Ergebnis zu verstehen und nachzuschärfen.

Manifest-Typen

Es gibt genau drei Manifest-Typen. Welchen du nutzt, hängt davon ab, wie viele MFEs in deinem Repository liegen.

`bundle` — Gruppe und MFEs in einer Datei

Gruppe und alle zugehörigen MFEs in einer einzigen Datei. Geeignet, solange ein Team alle MFEs des Repositories verantwortet:

{
  "type": "bundle",
  "group": { "id": "mein-service", "name": "Mein Service" },
  "mfes": [
    { "id": "mfe-a", "name": "MFE A", "hints": { "fullPage": false }, "integrations": {} }
  ]
}

`group` — Nur die Gruppe

Deklariert eine MFE-Gruppe ohne MFE-Definitionen. Die MFEs werden in separaten Dateien deklariert – die empfohlene Aufteilung für Monorepos:

{
  "type": "group",
  "id": "mein-service",
  "name": "Mein Service",
  "description": "Alle MFEs rund um meinen Service"
}

`mfe` — Einzelnes MFE

Definiert ein einzelnes MFE und ordnet es über das Feld group einer Gruppe zu. Die MFE-Felder stehen dabei direkt auf oberster Ebene:

{
  "type": "mfe",
  "group": "mein-service",
  "id": "mein-mfe",
  "name": "Mein Microfrontend",
  "hints": { "fullPage": false },
  "integrations": { }
}

Wird group weggelassen, wird das MFE automatisch einer eigenen Gruppe zugeordnet.

Integrationstypen definieren

Mindestens eine der beiden Integrationen muss vorhanden sein – beide sind ebenfalls möglich.

iFrame

"iFrame": {
  "src": "https://mfe.%ENV%.dvag",
  "environments": ["entwicklung", "integration", "abnahme"],
  "hints": {
    "autoScaling": true,
    "salesforceCanvasAutoScaling": false
  },
  "attributes": [
    {
      "key": "kundennummer",
      "title": "Kundennummer",
      "description": "Die Kundennummer des anzuzeigenden Kunden",
      "style": "queryParam",
      "type": "string",
      "required": true,
      "testDefault": "4711"
    }
  ]
}

hints.autoScaling — das MFE meldet seine Höhe über die MFE-Bridge, der Host skaliert den Frame automatisch.
hints.salesforceCanvasAutoScaling — dasselbe, aber über das Salesforce-Canvas-SDK.

WebComponent

"webComponent": {
  "src": "https://mfe.%ENV%.dvag/mfe.js",
  "environments": ["entwicklung", "integration"],
  "componentName": "dvag-mein-mfe",
  "hints": {
    "urlRouter": false
  },
  "attributes": [
    {
      "key": "kundennummer",
      "title": "Kundennummer",
      "style": "domAttribute",
      "type": "string",
      "required": true
    }
  ]
}

componentName — der Custom-Element-Tag, unter dem sich dein MFE registriert.
hints.urlRouter — das MFE nutzt einen URL-basierten Router (relevant für den Host, damit Routing-Konflikte vermieden werden).

Umgebungen und URL-Platzhalter

Im src wird %ENV% durch den jeweiligen Wert aus environments ersetzt. Falls eine Umgebung aus dem Muster ausbricht, kannst du sie gezielt überschreiben:

"srcOverrides": {
  "production": "https://mein-mfe.dvag/mfe.js"
}

Attribute

Attribute beschreiben, welche Daten das MFE beim Start entgegennimmt. Sie steuern gleichzeitig die Eingabefelder im interaktiven Preview und die generierten Integrations-Snippets.

{
  "key": "vertragsnummer",
  "title": "Vertragsnummer",
  "description": "Nummer des zu ladenden Vertrags",
  "style": "queryParam",
  "type": "string",
  "required": true,
  "array": false,
  "readonly": false,
  "testDefault": "12345"
}

Pflicht sind key, title, style, type und required.

Attribut-Styles

Der Style bestimmt, wie der Wert das MFE erreicht:

Style	Beschreibung	Geeignet für
`queryParam`	URL Query Parameter	iFrame
`domAttribute`	HTML DOM Attribut	WebComponent
`bridge`	Über die MFE-Bridge übertragen	Beide

Attribut-Typen

Der Typ bestimmt, welche Art von Wert erwartet wird – und wie das Portal das Eingabefeld im Preview darstellt:

Typ	Beschreibung
`string`	Freitext
`number`	Numerischer Wert
`boolean`	`true` / `false` – wird im Preview als Toggle dargestellt
`token-plain`	Auth-Token als Zeichenkette. Das Portal setzt das aktuelle Zugriffstoken automatisch ein
`token-callback`	Auth-Token per Callback-Funktion. Das MFE fordert das Token bei Bedarf beim Host an – bevorzugt bei langlebigen MFEs, da so auch erneuerte Tokens ankommen

Zusätzliche Schalter:

array: true — das Attribut nimmt mehrere Werte entgegen.
readonly: true — der Wert ist fest und im Preview nicht editierbar.
testDefault — Vorbelegung für den interaktiven Test im Portal. Sehr empfehlenswert, damit dein MFE ohne Vorwissen startklar ist.

Events deklarieren

Ein MFE ist selten eine Einbahnstraße – es meldet Ergebnisse zurück an den Host. Diese Events gehören ins Manifest, denn daraus entstehen die Listener-Snippets in der Integrationsdoku.

Bridge-Events

Events, die über die MFE-Bridge gesendet werden. Funktionieren für iFrame und WebComponent:

"bridge": {
  "events": [
    {
      "key": "vertragAusgewaehlt",
      "attributes": ["vertragsnummer", "produktart"],
      "description": "Wird ausgelöst, wenn ein Vertrag in der Liste ausgewählt wurde"
    }
  ]
}

key — der Eventname, wie er im Code verwendet wird.
attributes — die Felder, die im Event-Payload mitgeliefert werden.

DOM CustomEvents (nur WebComponent)

WebComponents können zusätzlich native CustomEvents auf ihrem Host-Element auslösen. Konsument:innen hören darauf mit element.addEventListener(...):

"customEvents": [
  {
    "name": "dvag-mfe-event",
    "key": "vertragGespeichert",
    "attributes": ["vertragsnummer"],
    "description": "Wird nach erfolgreichem Speichern ausgelöst"
  }
]

name — der DOM-Eventname für addEventListener.
key — der logische Bezeichner im event.detail (z. B. im Feld eventName).

Save-Protokoll und Bridge-Optionen

Der bridge-Block deklariert außerdem, wie sich dein MFE gegenüber dem Host verhält:

"bridge": {
  "implementsSaveProtocol": true,
  "forceMfeIdentifier": "mein-mfe",
  "events": []
}

implementsSaveProtocol — dein MFE unterstützt das Save-Protokoll der MFE-Bridge. Der Host kann dann von außen einen Speichervorgang auslösen (z. B. über einen eigenen „Speichern”-Button) und erfährt, ob ungespeicherte Änderungen vorliegen. Setze das auf true, wenn dein MFE Formulardaten bearbeitet und in einen Host-Rahmen mit eigener Speicherleiste eingebettet wird.
forceMfeIdentifier — erzwingt einen festen Bridge-Identifier statt der MFE-id. Nur nötig, wenn dein MFE-Code bereits einen abweichenden Identifier fest verdrahtet hat.

Monorepo-Strategien

Enthält dein Repository mehrere MFEs, gibt es zwei Ansätze – die Aggregation findet in beiden Fällen alle Manifeste, unabhängig davon, wo sie liegen.

Empfohlen: Aufgeteilte Manifeste (`group` + `mfe`)

Eine Gruppendatei im Root, und pro MFE ein eigenes Manifest direkt neben dem Code:

monorepo/
  mfe-manifest.json      ← type: "group" – nur die Gruppe
  apps/
    mfe-a/
      mfe-manifest.json  ← type: "mfe", group: "mein-service"
    mfe-b/
      mfe-manifest.json  ← type: "mfe", group: "mein-service"

Warum das in fast allen Fällen die bessere Wahl ist:

Ownership bleibt beim Team. Das Manifest liegt dort, wo auch der Code liegt – wer das MFE ändert, ändert auch dessen Manifest.
Weniger Merge-Konflikte. Bei einer einzigen großen Datei arbeiten alle Teams gleichzeitig in derselben Datei.
Änderungen bleiben überschaubar. Ein Pull Request verändert nur das Manifest des betroffenen MFEs.
Bessere Reviews. Im Diff ist sofort sichtbar, welches MFE betroffen ist.

Die Zuordnung erfolgt über das Feld group, das die id aus der Gruppendatei referenziert.

Alternative: Eine Datei (`bundle`)

monorepo/
  mfe-manifest.json    ← Gruppe + alle MFEs

Vertretbar bei einem einzelnen MFE oder wenn ein einziges Team alle MFEs im Repository verantwortet. Sobald mehrere Teams beteiligt sind, solltest du aufteilen.

Validierung

Das JSON Schema wird unter https://mfe-portal.entwicklung.dvag/schemas/mfe-manifest.schema.json gehostet. IDEs wie VS Code validieren automatisch, wenn die $schema-Property gesetzt ist – Tippfehler und fehlende Pflichtfelder fallen direkt im Editor auf.

Der Preview-Server der Development CLI validiert beim Start ebenfalls alle gefundenen Manifeste und meldet fehlerhafte Dateien im Terminal:

npx @dvag/mfe-portal preview

Alternativ kann die Validierung auch in der CI/CD-Pipeline erfolgen:

npx ajv validate -s mfe-manifest.schema.json -d mfe-manifest.json