packages/plugin-dev/README.md
This directory contains tools and examples for developing plugins for Super Productivity.
# Build all plugins
npm run build
# Install dependencies for all plugins
npm run install:all
# Clean build artifacts
npm run clean:dist
# List available plugins
npm run list
Copy the example plugin:
cp -r example-plugin my-plugin
cd my-plugin
Install dependencies:
npm install
Update plugin metadata:
manifest.json with your plugin detailspackage.json with your plugin name and descriptionStart development:
npm run dev
Build for production:
npm run build
my-plugin/
├── package.json # NPM package configuration
├── tsconfig.json # TypeScript configuration
├── webpack.config.js # Build configuration
├── manifest.json # Plugin manifest (metadata)
├── src/
│ └── index.ts # Main plugin code
├── assets/
│ ├── index.html # Optional UI (for iframe plugins)
│ └── icon.svg # Plugin icon
├── scripts/
│ └── package.js # Script to create plugin.zip
└── dist/ # Build output
├── plugin.js # Compiled plugin code
├── manifest.json # Copied manifest
└── plugin.zip # Packaged plugin
For rapid development within the Super Productivity repo:
# Build and install to local Super Productivity
npm run install-local
# This copies your built plugin to:
# ../../../src/assets/my-plugin/
Then run Super Productivity in development mode to test your plugin.
Keep the plugin building automatically as you make changes:
npm run dev
Ensure your code is type-safe:
npm run typecheck
Check code quality:
npm run lint
The plugin receives a global PluginAPI object with these capabilities:
cfg - Current app configuration (theme, platform, version)registerMenuEntry() - Add menu itemsregisterHeaderButton() - Add header buttonsregisterSidePanelButton() - Add side panel buttonsregisterShortcut() - Register keyboard shortcutsshowIndexHtmlAsView() - Display plugin UIgetTasks() - Get all tasksgetArchivedTasks() - Get archived tasksgetCurrentContextTasks() - Get current project/tag tasksupdateTask() - Update a taskaddTask() - Create new taskgetAllProjects() - Get all projectsgetAllTags() - Get all tagsshowSnack() - Display snack bar notificationsnotify() - Show system notificationsopenDialog() - Open custom dialogspersistDataSynced() - Save plugin dataloadSyncedData() - Load saved datatranslate(key, params?) - Get translated textformatDate(date, format) - Format dates with localegetCurrentLanguage() - Get current language codeSee PLUGIN_I18N.md for the complete i18n guide.
Register handlers for lifecycle events:
taskComplete - Task marked as donetaskUpdate - Task modifiedtaskDelete - Task removedcurrentTaskChange - Active task changedlanguageChange - App language changedfinishDay - End of day// Register a task complete handler
PluginAPI.registerHook('taskComplete', async (task) => {
console.log('Task completed:', task);
PluginAPI.showSnack({
msg: `Great job completing: ${task.title}`,
type: 'SUCCESS',
});
});
// Add a keyboard shortcut
PluginAPI.registerShortcut({
id: 'my-action',
label: 'My Plugin Action',
onExec: async () => {
const tasks = await PluginAPI.getTasks();
console.log(`You have ${tasks.length} tasks`);
},
});
// Use translations (if plugin has i18n support)
const greeting = PluginAPI.translate('MESSAGES.GREETING');
const taskCount = PluginAPI.translate('TASK_COUNT', { count: tasks.length });
const dueDate = PluginAPI.formatDate(task.dueDate, 'short');
npm run build
npm run package
This creates dist/plugin.zip ready for distribution.
Your plugin ZIP must contain:
manifest.json - Plugin metadataplugin.js - Main plugin codeOptional files:
index.html - UI for iframe pluginsicon.svg - Plugin iconi18n/*.json - Translation files for multi-language supportname: Build Plugin
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- run: npm ci
- run: npm run build
- run: npm run package
- uses: softprops/action-gh-release@v1
with:
files: dist/plugin.zip
.zip file from your releasesYou can also publish your plugin source to npm:
package.json with your npm scopenpm run buildnpm publishUsers would need to build it themselves or you can include the built files.
# Build your plugin
npm run build
# Copy to Super Productivity assets
npm run install-local
# Run Super Productivity in dev mode
cd ../../.. && npm start
npm run packageplugin.zip fileconsole.log() in your plugin codeimport type { TaskData, ProjectData } from '@super-productivity/plugin-api';
// Type-safe task handling
async function processTask(task: TaskData): Promise<void> {
if (task.projectId) {
const projects = await PluginAPI.getAllProjects();
const project = projects.find((p) => p.id === task.projectId);
if (project) {
console.log(`Task "${task.title}" belongs to project "${project.title}"`);
}
}
}
// Type-safe hook registration
PluginAPI.registerHook('taskUpdate', (data: unknown) => {
const task = data as TaskData;
processTask(task);
});
persistDataSynced() for plugin stateminSupVersionnpm run typecheck to see all errors@super-productivity/plugin-api is installeddist/ and rebuildboilerplate-solid-js demonstrates:
example-plugin demonstrates:
procrastination-buster demonstrates:
packages/plugin-api/README.md