Developing Plugins

This page is for anyone who wants to build their own plugins for FediSuite or understand how the plugin system works internally. The scaffold generator takes care of the groundwork, and the examples on this page show what goes where. You write the actual logic of your plugin yourself.

Basic JavaScript knowledge is enough for a simple plugin. The server side of a plugin is an ES module that exports a function register(context).

The recommended way to your own plugin is the scaffold generator. It is part of the FediSuite application (scripts/create-plugin-scaffold.mjs, run through npm run plugins:create) and creates a working plugin structure with one command: plugin.json, server/index.js, language files, web pages if needed and a README. You do not start from scratch.

Option 1: inside the running app container

Open a shell in the app container and run the command in the /app directory, which is where docker compose exec opens the shell by default. Without --target, the plugin is created under plugins/<id>, which inside the container is /app/plugins and therefore the mounted ./plugins folder on the host:

# Open a shell in the app container
docker compose exec app sh

# Run the scaffold in the application's main directory
npm run plugins:create -- \
  --id my-plugin \
  --name "My Plugin" \
  --author "Your Name" \
  --presets admin-page

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

Option 2: from the source repository

With Node.js on your machine, clone the main repository FediSuite-Docker-Image ↗ (opens in new tab) and pass the target folder with --target. The target must not exist yet:

git clone https://forge.chrislo.de/FediSuite/FediSuite-Docker-Image.git
cd FediSuite-Docker-Image
npm run plugins:create -- \
  --id my-plugin \
  --name "My Plugin" \
  --author "Your Name" \
  --presets admin-page \
  --target /path/to/fedisuite/plugins/my-plugin

Available presets

Each preset creates the matching building block with example texts and enters the capability and permissions in plugin.json. Presets can be combined: --presets app-page,dashboard-widget

Every plugin is a folder directly inside the plugins/ directory. FediSuite recognizes a plugin by a plugin.json lying directly in that folder. Deeper nested folders are not searched. The folder name usually matches the plugin ID, but the id in plugin.json is what counts.

my-plugin/
├── plugin.json       ← required
└── server/
    └── index.js      ← required

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

The plugin.json is the most important file of a plugin. It sits in the root of the plugin folder and tells FediSuite who the plugin is, what it brings and which permissions it needs. If a required field is missing or the file is invalid, the plugin is not loaded and is shown with the status "Failed".

This is the manifest the scaffold generates with --presets admin-page:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "pluginApiVersion": 1,
  "description": "A FediSuite plugin scaffold for My Plugin.",
  "i18nDir": "./i18n",
  "displayNameKey": "meta.name",
  "descriptionKey": "meta.description",
  "author": "Your 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"
}

The plugin.json has two fields that are easy to mix up: capabilities and requiredPermissions.

Which capability belongs to which permission?

Further permissions that apply regardless of the plugin type:

The server/index.js file is the heart of every plugin. FediSuite imports it when the plugin starts and calls the exported function register(context). It may be async. If it returns a function, FediSuite calls it when the plugin is disabled so the plugin can clean up. context.onDispose(callback) does the same and can be used several times.

The minimal skeleton:

export function register(context) {
  // Register everything the plugin adds to FediSuite here.
  // The context parameter is your interface to FediSuite.
}

What is context?

context is the plugin's official interface to FediSuite. You use it to register your plugin's features. Every registration checks the matching permission from the plugin.json. The methods prefixed with registerSimple… and registerMarkdown… are convenience helpers for the common case. The methods without these prefixes give you full control over the definition.

The following examples show how the most important plugin types are registered in server/index.js. They match what the scaffold generates.

Texts whose name ends in Key (titleKey, descriptionKey and so on) accept a key from the plugin's language files, for example 'adminSections.main.title'. The same works with context.ref('adminSections.main.title', 'Fallback text'). More in the "Multilingual support" section.

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

export function register(context) {
  context.registerSimpleAuthProvider({
    id: 'my-plugin-login',
    displayNameKey: 'authProviders.main.displayName',
    descriptionKey: 'authProviders.main.description',
    beginLogin: async ({ req }) => {
      const baseUrl = `${req.protocol}://${req.get('host')}`;
      return {
        auth_provider_id: 'my-plugin-login',
        redirect_url: `${baseUrl}/api/auth/providers/my-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: 'my-plugin-login', display_name: 'Demo login' },
      },
      tab: 'dashboard',
    }),
  });
}

export function register(context) {
  context.registerSimpleInsightProvider({
    id: 'my-plugin-insights',
    displayNameKey: 'insights.main.displayName',
    tips: [
      {
        id: 'first-tip',
        title: 'Example tip',
        text: 'This tip comes straight from the plugin.',
        confidence: 'low',
        priority: 1,
      },
    ],
  });
}

export function register(context) {
  context.registerApiRoute({
    method: 'get',
    path: '/status',        // reachable at /api/plugins/<id>/status
    auth: 'user',           // 'user' (default), 'admin' or 'public'
    summary: 'Returns the plugin status.',
    handler: async ({ req, res }) => {
      res.json({ plugin_id: context.plugin.plugin_id, user_id: req.user?.id || null, status: 'ok' });
    },
  });
}

With context.registerHook({ event, handler }) a plugin reacts to events in FediSuite. For this, the plugin needs the hooks permission and, in addition, the permission of the group the event belongs to. A hook may be async. If it throws an error, FediSuite writes a warning to the log and carries on, so a hook cannot abort an action. Hooks run in the process where the event occurs: posts are published, for example, by the worker running the scheduler.

export function register(context) {
  context.registerHook({
    event: 'post.after_publish',
    handler: async ({ post, account, publishedId }) => {
      console.log(`Post ${post.id} was published as ${publishedId}.`);
    },
  });
}

A plugin describes its settings in the settingsSchema field of the plugin.json. FediSuite generates the input forms from it: the "Plugin settings" card in plugin management for the global values (admins only) and the "Plugin settings" section under Settings → Preferences for the per-user values. The settings preset creates an example.

"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"
        }
      ]
    }
  ]
}

In code you read the values with getSettings() and getSetting(). Without a scope, global applies. For user and account you have to pass the ID, for example inside a route with req.user.id:

export function register(context) {
  context.registerApiRoute({
    method: 'get',
    path: '/greeting',
    auth: 'user',
    handler: async ({ req, res }) => {
      const global = await context.getSettings();                 // global values
      const message = await context.getSetting(
        'welcomeMessage',
        'Hello',
        { scope: 'user', userId: req.user.id },                   // this person's value
      );
      res.json({ enabled: global.enabled, message });
    },
  });
}

With saveSettings(values, scope) you save values from within the plugin, which requires the matching write permission. When admins or users save values in the interface, that triggers the settings.updated hook.

If your plugin needs an interactive page with its own HTML and JavaScript, you provide web files. FediSuite loads the HTML file and embeds it directly into the app, without an iframe. You do not need a separate server. Stylesheets are limited to the plugin area (selectors such as body or :root only apply there), relative paths such as ./main.js or ./style.css are resolved relative to the page, and scripts (including type="module") are executed. The CSS limiting is not a security boundary.

The web/ directory is optional. For simple text or Markdown content you do not need it. A plugin with webEntry needs the web.runtime permission. FediSuite only serves these file types: html, js, mjs, css, json, svg, txt, png, jpg, jpeg, gif, webp, ico, woff, woff2 and ttf.

web/manifest.json

This file describes which HTML file belongs to which page. frontendApiVersion must be 1. The sectionId must match exactly the id you assigned in server/index.js. entry is a path relative to web/, without a leading slash and without ...

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

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

The plugin web SDK

A ready-made SDK handles communication between the HTML page and FediSuite. It takes care of authentication and API calls, so you do not have to manage tokens or HTTP headers yourself. All calls go to the routes your plugin registered with registerApiRoute.

Include the SDK in your HTML file:

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

After that, window.FediSuitePluginWeb is available. The basic skeleton, which the scaffold also generates (web/main.js):

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

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

  // Wait for FediSuite's initialization, before any other call
  const context = await plugin.ready();
  // context contains: pluginId, sectionId, sectionKind ('admin' or 'app'), language

  try {
    // Call the plugin API (route from registerApiRoute or 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 supports several languages. To fit in, you move titles, descriptions and content into language files in the i18n/ directory (entered in plugin.json through i18nDir). The file name is the language code, for example de.json. Each file is a JSON object whose values are strictly strings (or lists of strings). Numbers and booleans are not allowed.

This is what the scaffold's language file for an admin page looks like:

{
  "meta": {
    "name": "My Plugin",
    "description": "A short description of my plugin."
  },
  "adminSections": {
    "main": {
      "title": "My Plugin Admin",
      "description": "What this plugin does.",
      "badge": "Plugin",
      "markdown": "## Welcome\n\nThe content goes here."
    }
  }
}

In code you pass the key, not the text. When you need a reference with a fallback, create it with context.ref:

// Recommended: a key from the language file
titleKey: 'adminSections.main.title'

// Equivalent, with a fallback text in case the key is missing
titleKey: context.ref('adminSections.main.title', 'My Plugin')

// Possible, but not translated: a fixed text
title: 'My Plugin'

Once your plugin sits in plugins/<id>/ and the folder is mounted, testing always works the same way:

Whether a plugin has started is visible in its status in plugin management. For "Failed", the cause is in the expanded details. The container logs do not name it. These messages appear there most often:

ls -la plugins/my-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/my-plugin/server/index.js
python3 -m json.tool plugins/my-plugin/plugin.json

docker compose logs app

docker compose logs app