Developing Plugins

This page is for anyone who wants to build their own plugins for FediSuite or understand how the plugin system works from the inside. You don't need to be an experienced developer — the scaffold tool handles most of the groundwork, and the examples on this page show you what goes where.

You don't need deep programming experience to build a simple plugin. Basic JavaScript knowledge is sufficient for most plugin types.

The fastest and recommended way to create your own plugin is the scaffold tool. It lives directly in the FediSuite application and creates a complete, immediately runnable plugin structure with a single command — including plugin.json, server/index.js, language files and a README. You don't start from a blank slate.

The scaffold tool is part of the FediSuite application itself and is therefore available in the app container — not in the plugins directory. Open a shell in the running app container and run the command there in the main directory /app:

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

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

Available presets

Each preset represents a different plugin type and sets up the appropriate basic structure. Presets can be combined: --presets app-page,dashboard-widget

Every plugin is a simple folder within the plugins/ directory. The folder name matches the plugin ID. FediSuite recognizes a plugin by finding a plugin.json file in that folder.

my-plugin/
├── plugin.json       ← required
├── server/
│   └── index.js     ← required
└── i18n/
    ├── de.json      ← required
    ├── en.json      ← required
    └── it.json      ← required

my-plugin/
├── plugin.json
├── server/
│   └── index.js
├── i18n/
│   ├── de.json
│   ├── en.json
│   └── it.json
└── web/             ← optional
    ├── manifest.json
    ├── main.html
    └── main.js

The plugin.json is the most important file of a plugin. It always lives in the root directory of the plugin folder and tells FediSuite who the plugin is, what it can do and what rights it needs. If it is missing or invalid, the plugin will not be loaded.

A complete example:

{
  "id":               "my-plugin",
  "name":             "My Plugin",
  "version":          "1.0.0",
  "pluginApiVersion": 1,
  "description":     "A short description of the plugin.",
  "author":           "Your Name",
  "license":          "GPL-3.0-or-later",
  "capabilities":    ["admin.section"],
  "requiredPermissions": ["admin.sections"],
  "serverEntry":     "./server/index.js",
  "i18nDir":          "./i18n",
  "displayNameKey":  "meta.name",
  "descriptionKey":  "meta.description"
}

In plugin.json there are two fields that are easy to confuse: capabilities and requiredPermissions.

Which capability belongs to which permission — and what do they mean?

The file server/index.js is the heart of every plugin. FediSuite calls the register(context) function it contains at startup. In this function you tell FediSuite what your plugin adds.

The minimal skeleton always looks the same:

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

What is context?

context is your official interface to FediSuite. Through it you register all features of your plugin. Think of it as a toolkit: you grab exactly the methods your plugin type needs.

Here you can see how the most important plugin types are registered in server/index.js — the simplest working example for each.

export function register(context) {
  context.registerMarkdownAdminPage({
    id:             'main',
    titleKey:       context.ref('adminSections.main.title',       'My Plugin'),
    descriptionKey: context.ref('adminSections.main.description',  'Description'),
    markdownKey:    context.ref('adminSections.main.markdown',    '## Content\nText goes here.'),
  });
}

export function register(context) {
  context.registerSimpleDashboardWidget({
    id:           'main',
    displayNameKey: context.ref('widgets.main.displayName', 'My Widget'),
  });
}

export function register(context) {
  context.registerSimpleComposerExtension({
    id:             'main',
    displayNameKey: context.ref('composer.main.displayName', 'My Extension'),
    fields: [
      { key: 'suffix', type: 'text', label: 'Appendix' },
    ],
    transformPost: async ({ post, data }) => ({
      content: `${String(post.content || '')}${String(data?.suffix || '')}`,
    }),
  });
}

export function register(context) {
  context.registerSimpleProvider({
    id:             'my-network',
    displayNameKey: context.ref('providers.main.displayName', 'My Network'),
    descriptionKey: context.ref('providers.main.description',   'Connects My Network.'),
    beginConnection: async ({ req }) => ({
      redirect_url: `${req.protocol}://${req.get('host')}/api/plugins/my-plugin/callback`,
    }),
    handleCallback: async () => ({
      user_id: 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,
      },
    }),
  });
}

export function register(context) {
  context.registerSimpleInsightProvider({
    id:             'my-insights',
    displayNameKey: context.ref('insights.main.displayName', 'My Insights'),
    tips: [
      { id: 'tip-1', title: 'First Tip', text: 'This tip comes from the plugin.' },
    ],
  });
}

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

If your plugin needs a fully interactive page with custom HTML and JavaScript elements, you can provide custom web files. FediSuite embeds these directly in the app — you don't need a separate server.

The web/ directory is optional and only needed if you really want custom HTML/JS. For simple text or Markdown content you don't need it.

web/manifest.json

This file describes which HTML files belong to which registered sections. The sectionId must match exactly the ID you assigned in server/index.js.

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

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

The Plugin Web SDK

For communication between the HTML page and FediSuite, a ready-made SDK is available. It handles authentication, API calls and embedding in the app — you don't need to manage tokens or HTTP headers yourself.

Include the SDK in your HTML file:

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

Afterwards window.FediSuitePluginWeb is available. A typical basic skeleton:

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

  // Wait until FediSuite has initialized the page (always call this first!)
  const context = await plugin.ready();
  // context contains: pluginId, sectionId, sectionKind, language

  // Call the plugin API (endpoint from registerApiRoute)
  const result = await plugin.get('/status');
  console.log(result);
}

boot();

FediSuite supports multiple languages. To keep your plugin consistent with the rest of the app, you should store all texts — titles, descriptions, content — in language files rather than hardcoding them. The directory for this is i18n/.

A typical language file looks like this:

{
  "meta": {
    "name":        "My Plugin",
    "description": "Short description of my plugin."
  },
  "adminSections": {
    "main": {
      "title":       "My Plugin",
      "description": "What this plugin does.",
      "markdown":    "## Welcome\n\nContent goes here."
    }
  }
}

In the code, instead of using the text directly, you use a reference to the key:

// ✓ Correct: use a language reference
titleKey: context.ref('adminSections.main.title', 'My Plugin')

// ✗ Wrong: text entered directly
titleKey: 'My Plugin'

Most problems when developing plugins fall into four categories. Here are the most common causes and how to quickly find them.

ls -la plugins/my-plugin/
docker compose config | grep plugins
docker compose up -d

docker compose logs app | grep -i plugin
docker compose logs app | grep -i error

docker compose logs app

docker compose logs app | grep -i plugin