Plugins entwickeln

Diese Seite richtet sich an alle, die eigene Plugins für FediSuite bauen oder verstehen möchten, wie das Plugin-System von innen funktioniert. Der Scaffold-Generator übernimmt die Grundarbeit, und die Beispiele auf dieser Seite zeigen, was wohin gehört. Die eigentliche Logik Deines Plugins schreibst Du selbst.

Für ein einfaches Plugin reichen grundlegende JavaScript-Kenntnisse. Der Server-Teil eines Plugins ist ein ES-Modul, das eine Funktion register(context) exportiert.

Der empfohlene Weg zum eigenen Plugin ist der Scaffold-Generator. Er ist Teil der FediSuite-Anwendung (scripts/create-plugin-scaffold.mjs, aufgerufen über npm run plugins:create) und legt mit einem Befehl eine lauffähige Plugin-Struktur an: plugin.json, server/index.js, Sprachdateien, bei Bedarf Web-Seiten und eine README. Du fängst also nicht bei null an.

Variante 1: im laufenden App-Container

Öffne eine Shell im App-Container und führe den Befehl im Verzeichnis /app aus. Dort öffnet docker compose exec die Shell standardmäßig. Ohne --target entsteht das Plugin unter plugins/<id>, im Container also in /app/plugins und damit im gemounteten Ordner ./plugins auf dem Host:

# Shell im App-Container öffnen
docker compose exec app sh

# Scaffold im Hauptverzeichnis der Anwendung ausführen
npm run plugins:create -- \
  --id mein-plugin \
  --name "Mein Plugin" \
  --author "Dein Name" \
  --presets admin-page

Plugin scaffold created successfully.
Path: /app/plugins/mein-plugin
Plugin ID: mein-plugin
Presets: admin-page

Variante 2: aus dem Quellcode-Repository

Mit Node.js auf dem Rechner klonst Du das Hauptrepository FediSuite-Docker-Image ↗ (öffnet in neuem Tab) und gibst mit --target den Zielordner an. Das Ziel darf noch nicht existieren:

git clone https://forge.chrislo.de/FediSuite/FediSuite-Docker-Image.git
cd FediSuite-Docker-Image
npm run plugins:create -- \
  --id mein-plugin \
  --name "Mein Plugin" \
  --author "Dein Name" \
  --presets admin-page \
  --target /pfad/zu/fedisuite/plugins/mein-plugin

Verfügbare Presets

Jedes Preset legt den passenden Baustein samt Beispieltexten an und trägt Capability und Berechtigungen in die plugin.json ein. Presets lassen sich kombinieren: --presets app-page,dashboard-widget

Jedes Plugin ist ein Ordner direkt im plugins/-Verzeichnis. FediSuite erkennt ein Plugin daran, dass in diesem Ordner unmittelbar eine plugin.json liegt, tiefer verschachtelte Ordner werden nicht durchsucht. Der Ordnername entspricht üblicherweise der Plugin-ID, maßgeblich ist aber die id in der plugin.json.

mein-plugin/
├── plugin.json       ← Pflicht
└── server/
    └── index.js      ← Pflicht

mein-plugin/
├── plugin.json
├── README.md
├── server/
│   └── index.js
├── i18n/
│   ├── de.json
│   ├── en.json
│   ├── es.json
│   ├── fr.json
│   └── it.json
└── web/             ← nur bei admin-page / app-page
    ├── manifest.json
    ├── admin-main.html
    └── main.js

Die plugin.json ist die wichtigste Datei eines Plugins. Sie liegt im Stammverzeichnis des Plugin-Ordners und sagt FediSuite, wer das Plugin ist, was es mitbringt und welche Berechtigungen es braucht. Fehlt ein Pflichtfeld oder ist die Datei ungültig, wird das Plugin nicht geladen und mit dem Status „Fehler“ angezeigt.

So sieht das Manifest aus, das das Scaffold mit --presets admin-page erzeugt:

{
  "id": "mein-plugin",
  "name": "Mein Plugin",
  "version": "1.0.0",
  "pluginApiVersion": 1,
  "description": "A FediSuite plugin scaffold for Mein Plugin.",
  "i18nDir": "./i18n",
  "displayNameKey": "meta.name",
  "descriptionKey": "meta.description",
  "author": "Dein Name",
  "license": "GPL-3.0-or-later",
  "capabilities": [
    "admin.section"
  ],
  "requiredPermissions": [
    "admin.sections",
    "web.runtime",
    "api.routes"
  ],
  "webEntry": "./web/manifest.json",
  "serverEntry": "./server/index.js"
}

In der plugin.json stehen zwei Felder, die leicht zu verwechseln sind: capabilities und requiredPermissions.

Welche Capability gehört zu welcher Berechtigung?

Weitere Berechtigungen, die unabhängig vom Plugin-Typ gelten:

Die Datei server/index.js ist das Herzstück jedes Plugins. FediSuite importiert sie beim Start des Plugins und ruft die exportierte Funktion register(context) auf. Sie darf async sein. Gibt sie eine Funktion zurück, ruft FediSuite diese beim Deaktivieren auf, damit das Plugin aufräumen kann. Dasselbe leistet context.onDispose(callback), auch mehrfach.

Das minimale Gerüst:

export function register(context) {
  // Hier registrierst Du alles, was das Plugin in FediSuite einbindet.
  // Der context-Parameter ist Deine Schnittstelle zu FediSuite.
}

Was ist context?

context ist die offizielle Schnittstelle des Plugins zu FediSuite. Über ihn registrierst Du die Funktionen Deines Plugins. Jede Registrierung prüft die passende Berechtigung aus der plugin.json. Die Methoden mit dem Präfix registerSimple… und registerMarkdown… sind Komfort-Helfer für den Normalfall, die Methoden ohne diese Präfixe geben Dir volle Kontrolle über die Definition.

Die folgenden Beispiele zeigen, wie die wichtigsten Plugin-Typen in server/index.js registriert werden. Sie entsprechen dem, was das Scaffold erzeugt.

Texte, deren Name auf Key endet (titleKey, descriptionKey und so weiter), nehmen einen Schlüssel aus den Sprachdateien des Plugins entgegen, zum Beispiel 'adminSections.main.title'. Alternativ geht dasselbe mit context.ref('adminSections.main.title', 'Fallback-Text'). Mehr dazu im Abschnitt „Mehrsprachigkeit“.

export function register(context) {
  context.registerMarkdownAdminPage({
    id: 'main',
    titleKey: 'adminSections.main.title',
    descriptionKey: 'adminSections.main.description',
    badgeKey: 'adminSections.main.badge',
    markdownKey: 'adminSections.main.markdown',
  });
}

export function register(context) {
  context.registerMarkdownAppPage({
    id: 'main',
    titleKey: 'appSections.main.title',
    navLabelKey: 'appSections.main.navLabel',
    descriptionKey: 'appSections.main.description',
    markdownKey: 'appSections.main.markdown',
  });
}

export function register(context) {
  context.registerSimpleDashboardWidget({
    id: 'main',
    tab: 'interactions',   // optional, Standard: 'overview'
    titleKey: 'dashboardWidgets.main.title',
    descriptionKey: 'dashboardWidgets.main.description',
    badgeKey: 'dashboardWidgets.main.badge',
    statusLabelKey: 'dashboardWidgets.main.stats.statusLabel',
    statusValueKey: 'dashboardWidgets.main.stats.statusValue',
  });
}

export function register(context) {
  context.registerSimpleComposerExtension({
    id: 'main',
    displayNameKey: 'composer.main.displayName',
    descriptionKey: 'composer.main.description',
    fields: [
      {
        key: 'enabled',
        type: 'boolean',
        labelKey: 'composer.main.fields.enabled.label',
        descriptionKey: 'composer.main.fields.enabled.description',
        defaultValue: false,
      },
      {
        key: 'suffix',
        type: 'text',
        labelKey: 'composer.main.fields.suffix.label',
        descriptionKey: 'composer.main.fields.suffix.description',
        defaultValue: ' - sent with my plugin',
      },
    ],
    transformPost: async ({ post, data }) => {
      if (!data?.enabled || !String(data?.suffix || '').trim()) return {};
      return {
        content: `${String(post.content || '').trim()}${String(data.suffix)}`.trim(),
      };
    },
  });
}

export function register(context) {
  context.registerSimpleProvider({
    id: 'mein-plugin-provider',
    displayNameKey: 'providers.main.displayName',
    descriptionKey: 'providers.main.description',
    beginConnection: async ({ req }) => ({
      provider_id: 'mein-plugin-provider',
      user_id: req.user?.id || null,
      redirect_url: `${req.protocol}://${req.get('host')}/api/providers/mein-plugin-provider/callback?code=demo-code`,
      state: 'demo-state',
    }),
    handleCallback: async ({ req }) => ({
      provider_id: 'mein-plugin-provider',
      user_id: Number(req.query.user_id || 1) || 1,
      account: {
        instance_url: 'https://example.com',
        username: 'demo',
        display_name: 'Demo-Konto',
        stats_followers: 0,
        stats_following: 0,
        stats_statuses: 0,
        max_characters: 500,
        max_media_attachments: 4,
      },
      start_import: false,
    }),
    disconnect: async ({ account }) => ({
      provider_id: 'mein-plugin-provider',
      disconnected: true,
      account_id: account?.id || null,
    }),
  });
}

export function register(context) {
  context.registerSimpleAuthProvider({
    id: 'mein-plugin-login',
    displayNameKey: 'authProviders.main.displayName',
    descriptionKey: 'authProviders.main.description',
    beginLogin: async ({ req }) => {
      const baseUrl = `${req.protocol}://${req.get('host')}`;
      return {
        auth_provider_id: 'mein-plugin-login',
        redirect_url: `${baseUrl}/api/auth/providers/mein-plugin-login/callback?demo_email=plugin-login@example.com&demo_subject=demo-user`,
      };
    },
    handleCallback: async ({ req }) => ({
      identity: {
        external_subject: String(req.query.demo_subject || 'demo-user'),
        email: String(req.query.demo_email || 'plugin-login@example.com'),
        profile: { provider: 'mein-plugin-login', display_name: 'Demo-Login' },
      },
      tab: 'dashboard',
    }),
  });
}

export function register(context) {
  context.registerSimpleInsightProvider({
    id: 'mein-plugin-insights',
    displayNameKey: 'insights.main.displayName',
    tips: [
      {
        id: 'erster-tipp',
        title: 'Beispiel-Tipp',
        text: 'Dieser Tipp kommt direkt aus dem Plugin.',
        confidence: 'low',
        priority: 1,
      },
    ],
  });
}

export function register(context) {
  context.registerApiRoute({
    method: 'get',
    path: '/status',        // erreichbar unter /api/plugins/<id>/status
    auth: 'user',           // 'user' (Standard), 'admin' oder 'public'
    summary: 'Gibt den Plugin-Status zurück.',
    handler: async ({ req, res }) => {
      res.json({ plugin_id: context.plugin.plugin_id, user_id: req.user?.id || null, status: 'ok' });
    },
  });
}

Mit context.registerHook({ event, handler }) reagiert ein Plugin auf Ereignisse in FediSuite. Dafür braucht das Plugin die Berechtigung hooks und zusätzlich die Berechtigung der Gruppe, zu der das Ereignis gehört. Ein Hook darf async sein. Wirft er einen Fehler, schreibt FediSuite eine Warnung ins Log und macht weiter, ein Hook kann eine Aktion also nicht abbrechen. Hooks laufen im Prozess, in dem das Ereignis eintritt: Beiträge veröffentlicht zum Beispiel der Worker mit dem Scheduler.

export function register(context) {
  context.registerHook({
    event: 'post.after_publish',
    handler: async ({ post, account, publishedId }) => {
      console.log(`Beitrag ${post.id} wurde als ${publishedId} veröffentlicht.`);
    },
  });
}

Ein Plugin beschreibt seine Einstellungen im Feld settingsSchema der plugin.json. FediSuite erzeugt daraus die Eingabemasken: die Karte „Plugin-Einstellungen“ in der Plugin-Verwaltung für die globalen Werte (nur Admins) und den Abschnitt „Plugin-Einstellungen“ unter Einstellungen → Einstellungen für die Werte pro Nutzer*in. Das Preset settings legt ein Beispiel an.

"requiredPermissions": [
  "settings.global.read",
  "settings.global.write",
  "settings.user.read",
  "settings.user.write"
],
"settingsSchema": {
  "title": { "key": "settings.title", "fallback": "Plugin settings" },
  "sections": [
    {
      "id": "general",
      "title": { "key": "settings.sections.general.title", "fallback": "General" },
      "fields": [
        {
          "key": "enabled",
          "type": "boolean",
          "label": { "key": "settings.fields.enabled.label", "fallback": "Enabled" },
          "defaultValue": true
        },
        {
          "key": "welcomeMessage",
          "type": "text",
          "label": { "key": "settings.fields.welcomeMessage.label", "fallback": "Welcome message" },
          "defaultValue": "Hello from plugin settings"
        }
      ]
    }
  ]
}

Im Code liest Du die Werte mit getSettings() und getSetting(). Ohne Bereichsangabe gilt global. Für user und account musst Du die ID mitgeben, zum Beispiel innerhalb einer Route mit req.user.id:

export function register(context) {
  context.registerApiRoute({
    method: 'get',
    path: '/greeting',
    auth: 'user',
    handler: async ({ req, res }) => {
      const global = await context.getSettings();                 // globale Werte
      const message = await context.getSetting(
        'welcomeMessage',
        'Hallo',
        { scope: 'user', userId: req.user.id },                   // Wert dieser Person
      );
      res.json({ enabled: global.enabled, message });
    },
  });
}

Mit saveSettings(werte, bereich) speicherst Du Werte aus dem Plugin heraus, dafür ist die passende write-Berechtigung nötig. Speichern Admins oder Nutzer*innen Werte in der Oberfläche, löst das den Hook settings.updated aus.

Wenn Dein Plugin eine interaktive Seite mit eigenem HTML und JavaScript braucht, stellst Du Web-Dateien bereit. FediSuite lädt die HTML-Datei und bettet sie direkt in die App ein, ohne iframe. Du brauchst keinen eigenen Server. Stylesheets werden auf den Plugin-Bereich begrenzt (Selektoren wie body oder :root gelten nur dort), relative Pfade wie ./main.js oder ./style.css werden relativ zur Seite aufgelöst, und Skripte (auch type="module") werden ausgeführt. Die CSS-Begrenzung ist keine Sicherheitsgrenze.

Das web/-Verzeichnis ist optional. Für einfache Text- oder Markdown-Inhalte brauchst Du es nicht. Ein Plugin mit webEntry braucht die Berechtigung web.runtime. FediSuite liefert nur diese Dateitypen aus: html, js, mjs, css, json, svg, txt, png, jpg, jpeg, gif, webp, ico, woff, woff2 und ttf.

web/manifest.json

Diese Datei beschreibt, welche HTML-Datei zu welcher Seite gehört. frontendApiVersion muss 1 sein. Die sectionId muss exakt mit der id übereinstimmen, die Du in server/index.js vergeben hast. entry ist ein Pfad relativ zu web/, ohne führenden Schrägstrich und ohne ...

{
  "frontendApiVersion": 1,
  "adminPages": [
    {
      "sectionId": "main",
      "entry": "admin-main.html"
    }
  ]
}

{
  "frontendApiVersion": 1,
  "appPages": [
    {
      "sectionId": "main",
      "entry": "app-main.html"
    }
  ]
}

Das Plugin-Web-SDK

Für die Kommunikation zwischen der HTML-Seite und FediSuite gibt es ein fertiges SDK. Es kümmert sich um Authentifizierung und API-Aufrufe, Du musst weder Tokens noch HTTP-Header selbst verwalten. Alle Aufrufe gehen an die Routen, die Dein Plugin mit registerApiRoute registriert hat.

Binde das SDK in Deiner HTML-Datei ein:

<script src="/plugin-sdk/fedisuite-plugin-web.js"></script>

Danach steht window.FediSuitePluginWeb zur Verfügung. Das Grundgerüst, das auch das Scaffold erzeugt (web/main.js):

const output = document.getElementById('output');

async function boot() {
  const plugin = window.FediSuitePluginWeb;

  // Auf die Initialisierung durch FediSuite warten, vor allen anderen Aufrufen
  const context = await plugin.ready();
  // context enthält: pluginId, sectionId, sectionKind ('admin' oder 'app'), language

  try {
    // Plugin-API aufrufen (Route aus registerApiRoute oder registerStatusRoute)
    const status = await plugin.get('/status');
    output.textContent = JSON.stringify({ context, status }, null, 2);
  } catch (error) {
    output.textContent = error instanceof Error ? error.message : String(error);
  }
}

boot();

FediSuite unterstützt mehrere Sprachen. Damit Dein Plugin dazu passt, lagerst Du Titel, Beschreibungen und Inhalte in Sprachdateien im Verzeichnis i18n/ aus (in der plugin.json über i18nDir eingetragen). Der Dateiname ist der Sprachcode, zum Beispiel de.json. Jede Datei ist ein JSON-Objekt, dessen Werte ausschließlich Zeichenketten (oder Listen von Zeichenketten) sind. Zahlen und Wahrheitswerte sind nicht erlaubt.

So sieht die Sprachdatei des Scaffolds für eine Admin-Seite aus:

{
  "meta": {
    "name": "Mein Plugin",
    "description": "Kurze Beschreibung meines Plugins."
  },
  "adminSections": {
    "main": {
      "title": "Mein Plugin Admin",
      "description": "Was dieses Plugin macht.",
      "badge": "Plugin",
      "markdown": "## Willkommen\n\nHier steht der Inhalt."
    }
  }
}

Im Code übergibst Du den Schlüssel, nicht den Text. Eine Referenz mit Fallback erzeugst Du bei Bedarf mit context.ref:

// Empfohlen: Schlüssel aus der Sprachdatei
titleKey: 'adminSections.main.title'

// Gleichwertig, mit Fallback-Text für den Fall, dass der Schlüssel fehlt
titleKey: context.ref('adminSections.main.title', 'Mein Plugin')

// Möglich, aber nicht übersetzt: ein fester Text
title: 'Mein Plugin'

Liegt Dein Plugin in plugins/<id>/ und ist der Ordner eingebunden, läuft der Test immer gleich ab:

Ob ein Plugin gestartet ist, siehst Du am Status in der Plugin-Verwaltung. Bei „Fehler“ steht die Ursache in den aufgeklappten Details. Die Container-Logs nennen sie nicht. Die folgenden Meldungen kommen dort am häufigsten vor:

ls -la plugins/mein-plugin/
docker compose config | grep plugins
docker compose exec app ls /app/plugins
docker compose restart app worker1 worker2

docker compose exec app node --check /app/plugins/mein-plugin/server/index.js
python3 -m json.tool plugins/mein-plugin/plugin.json

docker compose logs app

docker compose logs app