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. Plugins are executable code and are not strongly sandboxed from the app. Only install or develop from sources you trust. See 2.21-Manage-Plugins for the user-facing trust model.

Build One with an AI Chat

No coding setup needed: open Help → Build your own plugin (or Settings → Plugins → Build one with AI).

1. Describe what the plugin should do and copy the generated prompt into an AI chat.
2. Paste the AI's whole answer back. The app packs and installs it after the usual install warning.
3. If it fails to load, Copy error for your AI gives the chat what it needs to fix it; paste the fixed answer to replace the plugin.

Quick Steps

1. Copy the plugin starter to a folder of your own (its README has the commands). It contains:
   • manifest.json (id, name, version, description, manifestVersion, minSupVersion)
   • plugin.js (runs on load; can register header buttons, shortcuts, hooks)
2. Set a unique id and name in manifest.json and edit plugin.js. For custom iframe UI, add index.html and set iFrame: true in the manifest. If all behavior lives in index.html, plugin.js can be omitted.
3. Run node scripts/pack.mjs to package the files as plugin.zip with manifest.json at its root.
4. In the app, open Settings → Plugins → Choose Plugin File and select the ZIP. Uploading again with the same id replaces the plugin.
5. Use DevTools (F12 or Ctrl+Shift+I) to debug.

Test on a separate instance, not your real data, for example test-app.super-productivity.com.

Security

Host-side plugin.js code runs in the app renderer, not in a security sandbox. Iframe plugins use a filtered API as their intended interface, but they are same-origin with the host and that interface is not a hard security boundary. Desktop plugins requesting nodeExecution can run native code only after an explicit native consent dialog; granting it gives the plugin full access under your user account.

Read the full guide's Security Considerations before distributing a plugin.

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, published on npm as @super-productivity/plugin-api.

Related

• 2.21-Manage-Plugins
• 2.11-Run-the-Development-Server