Develop a Plugin

How to create and test a custom plugin for Super Productivity.

Plugins extend the app with custom UI, hooks (e.g. on task complete), and API access to tasks, projects, and counters. They run in a sandbox; iframe plugins must inline CSS and JavaScript.

Quick Steps

1. Create a folder with at least:
   • manifest.json (id, name, version, description, manifestVersion, minSupVersion)
   • plugin.js (runs on load; can register header buttons, shortcuts, hooks), or index.html for an iframe-only plugin
2. Add index.html and set iFrame: true in the manifest for custom iframe UI. If all behavior lives in index.html, plugin.js can be omitted.
3. In the app: Settings → Plugins → Load Plugin from Folder and select your plugin directory.
4. Use DevTools (F12 or Ctrl+Shift+I) to debug.

Full Documentation and Examples

The full plugin guide and API live in the repository:

docs/plugin-development.md

It covers:

• Manifest fields, plugin types (JavaScript vs iframe), and security
• Available API methods (tasks, projects, tags, counters, notifications, dialogs)
• Theme variables and UI Kit for iframe plugins
• Best practices and testing

Example plugins in the repo: packages/plugin-dev/yesterday-tasks-plugin, procrastination-buster, api-test-plugin. For UI-heavy plugins: packages/plugin-dev/boilerplate-solid-js. TypeScript API types: packages/plugin-api/src/types.ts.

Related

• [[2.11-Run-the-Development-Server]]