Plugins

How FeatherPanel plugins work. Install from the marketplace, a file or a URL, manage settings and visibility, and the layout, conf.yml and entry class of a plugin.

On this page

Plugins (also called addons) add backend routes, event handlers, cron jobs, CLI commands, database tables, frontend pages, sidebar entries and dashboard widgets to the panel without patching its code.

Install a plugin

Open Admin > Plugins. You can:

browse and install from the online registry (FeatherCloud marketplace), search by tag and see popular packages,
upload an .fpa package,
install from a URL.

Before installing from the registry the panel checks the package’s requirements. After install you can change the plugin’s settings, hide its frontend pages from some users, limit its server sidebar entries to certain spells, export it as a package, resync its file links or uninstall it. Each action needs admin.plugins.view or admin.plugins.manage.

Anatomy of a plugin

A plugin is a directory in backend/storage/addons/ named after its identifier:

demoshowcase/
├── conf.yml
├── DemoShowcase.php
└── Frontend/
    ├── sidebar.json
    ├── widgets.json
    └── Components/demoshowcase/dist/*.html

conf.yml

plugin:
  name: DemoStatus
  identifier: demostatus
  description: 'Status showcase'
  flags:
    - hasEvents
  version: 1.0.0
  target: v2
  author:
    - Your Name
  icon: 'https://example.com/icon.png'
  requiredConfigs: {}
  dependencies:
    - php=8.3
    - php-ext=pdo
config: {}

Key	Notes
`name`, `identifier`, `description`, `version`, `target`, `icon`	Required strings. The identifier may only contain letters, digits and `_`.
`flags`	Required list. Allowed: `hasInstallScript`, `hasRemovalScript`, `hasUpdateScript`, `developerIgnoreInstallScript`, `developerEscalateInstallScript`, `userEscalateInstallScript`, `hasEvents`.
`author`	Required list of names.
`dependencies`	Required list. Entries are `php=`, `php-ext=`, `composer=` or `plugin=`. The plugin does not load if one is missing.
`requiredConfigs`	Required. Settings the admin must fill in before the plugin works.
`plugin_cloud_id`, `minimum_panel_version`, `maximum_panel_version`	Optional.

Entry class

The entry class lives in the namespace App\Addons\<identifier>, has the same name as plugin.name, and implements App\Plugins\AppPlugin:

<?php

namespace App\Addons\demostatus;

use App\Plugins\AppPlugin;
use App\Plugins\PluginEvents;

class DemoStatus implements AppPlugin
{
    public static function processEvents(PluginEvents $event): void
    {
        // Subscribe to panel events here.
    }

    public static function pluginInstall(): void
    {
    }

    public static function pluginUninstall(): void
    {
    }
}

An optional pluginUpdate(?string $oldVersion, ?string $newVersion) method runs on updates. If the name, class and namespace do not match, the panel looks for a single AppPlugin class in the plugin root, and skips the plugin with a log entry when it finds none.

Other directories

Directory	Purpose
`Routes/`	Backend API routes
`Commands/`	Commands added to the panel CLI
`Migrations/`	SQL migrations for the plugin’s tables
`Cron/`	Jobs picked up by the cron runner, see Cron and workers
`Frontend/sidebar.json`	Pages in the `client`, `admin` and `server` sidebars
`Frontend/widgets.json`	Widgets placed on panel pages
`Frontend/Components/`	Built HTML for those pages and widgets, loaded in an iframe

Develop a plugin

Read these in order the first time, then use them as a reference:

Step	Page
1. Build a working plugin in a few minutes	Build your first plugin
2. Learn the folder layout	Plugin structure
3. Describe the plugin	Manifest (conf.yml) and Settings
4. Run code when things happen	Lifecycle and events and the event reference
5. Add an API	Routes and permissions and Middleware and router hooks
6. Add pages and widgets	Frontend and Power SDK, Widget slots and Themes and UI packs
7. Store data	Migrations and storage
8. Run background work	Cron jobs and CLI commands
9. Ship it	Packaging and publishing
When something breaks	Debugging plugins and the Plugin FAQ

Examples has complete plugins to copy from. The panel also ships its own developer docs, icanhasfeatherpanel, at /icanhasfeatherpanel/ on every panel.

Reference

Plugin events: every event you can subscribe to.
Widgets: pages and slots where widgets can appear.
API reference: the routes your frontend code can call.

Frequently asked questions

Where are plugins stored?

In backend/storage/addons/<identifier>. In the Docker backend container that is /var/www/html/storage/addons, backed by the featherpanel_addons volume, so plugins survive container updates.

What is an .fpa file?

The package format for FeatherPanel addons, a zip archive that may be password protected. Marketplace downloads and exports use it, and the admin area can install one from an upload or a URL.