ContextQMD
Back to Super Productivity

Develop a Plugin

docs/wiki/2.15-Develop-a-Plugin.md

18.18.02.2 KB
Original Source

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.

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. Package the files as a ZIP with manifest.json at its root.
  4. In the app, open Settings → Plugins → Choose Plugin File and select the ZIP.
  5. Use DevTools (F12 or Ctrl+Shift+I) to debug.

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.

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