mirror of
https://github.com/johannesjo/super-productivity.git
synced 2026-07-18 17:05:48 +00:00
d4d81bf511
- Add @super-productivity/plugin-api package with TypeScript definitions - Define core plugin interfaces, types, and manifest structure - Add plugin hooks system for event-driven architecture - Create plugin API type definitions and constants - Add documentation and development guidelines
149 lines
3.3 KiB
Markdown
149 lines
3.3 KiB
Markdown
# Plugin API Development Guide
|
|
|
|
## For Plugin Developers
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
npm install @super-productivity/plugin-api
|
|
```
|
|
|
|
### TypeScript Setup
|
|
|
|
Create a `tsconfig.json` in your plugin project:
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"target": "ES2020",
|
|
"module": "commonjs",
|
|
"lib": ["ES2020", "DOM"],
|
|
"strict": true,
|
|
"esModuleInterop": true,
|
|
"skipLibCheck": true,
|
|
"forceConsistentCasingInFileNames": true
|
|
},
|
|
"include": ["src/**/*"],
|
|
"exclude": ["node_modules"]
|
|
}
|
|
```
|
|
|
|
### Basic Plugin Structure
|
|
|
|
```
|
|
my-plugin/
|
|
├── src/
|
|
│ └── plugin.ts
|
|
├── dist/
|
|
│ └── plugin.js
|
|
├── manifest.json
|
|
├── index.html (optional)
|
|
├── icon.svg (optional)
|
|
├── package.json
|
|
└── tsconfig.json
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
1. **Write TypeScript code** with full type safety
|
|
2. **Compile to JavaScript** for Super Productivity
|
|
3. **Test in Super Productivity** plugin system
|
|
|
|
### Example Build Script
|
|
|
|
Add to your `package.json`:
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"build": "tsc",
|
|
"build:watch": "tsc --watch",
|
|
"dev": "tsc --watch"
|
|
},
|
|
"devDependencies": {
|
|
"@super-productivity/plugin-api": "^1.0.0",
|
|
"typescript": "^5.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Plugin Template
|
|
|
|
See `example/my-plugin.ts` for a complete TypeScript plugin example.
|
|
|
|
## For Core Developers
|
|
|
|
### Updating the API
|
|
|
|
When adding new features to the plugin system:
|
|
|
|
1. **Update `src/types.ts`** with new interfaces/types
|
|
2. **Update `src/index.ts`** to export new types
|
|
3. **Update `README.md`** with usage examples
|
|
4. **Version bump** the package
|
|
5. **Rebuild and test**
|
|
6. **Publish to npm**
|
|
|
|
### Syncing with Main Project
|
|
|
|
The main Super Productivity project should eventually import types from this package instead of maintaining local definitions:
|
|
|
|
```typescript
|
|
// Before:
|
|
import { PluginManifest } from './plugin-api.model';
|
|
|
|
// After:
|
|
import type { PluginManifest } from '@super-productivity/plugin-api';
|
|
```
|
|
|
|
### Testing Changes
|
|
|
|
1. Build the package: `npm run build`
|
|
2. Test locally: `npm link` in this directory
|
|
3. In test project: `npm link @super-productivity/plugin-api`
|
|
4. Verify types work correctly
|
|
|
|
### Release Process
|
|
|
|
1. Update version: `npm version patch|minor|major`
|
|
2. Build: `npm run build`
|
|
3. Test: `npm pack --dry-run`
|
|
4. Publish: `npm publish --access public`
|
|
|
|
## Available Types Reference
|
|
|
|
### Core Interfaces
|
|
|
|
- `PluginAPI` - Main API interface
|
|
- `PluginManifest` - Plugin configuration
|
|
- `PluginBaseCfg` - Runtime configuration
|
|
|
|
### Hook Types
|
|
|
|
- `PluginHooks` - Available hook events
|
|
- `PluginHookHandler` - Hook function signature
|
|
|
|
### Data Types
|
|
|
|
- `TaskData` - Task information
|
|
- `ProjectData` - Project information
|
|
- `TagData` - Tag information
|
|
- `PluginCreateTaskData` - Task creation data
|
|
|
|
### UI Types
|
|
|
|
- `DialogCfg` - Dialog configuration
|
|
- `DialogButtonCfg` - Dialog button configuration
|
|
- `SnackCfg` - Notification configuration
|
|
- `NotifyCfg` - System notification configuration
|
|
- `PluginMenuEntryCfg` - Menu entry configuration
|
|
- `PluginShortcutCfg` - Keyboard shortcut configuration
|
|
- `PluginHeaderBtnCfg` - Header button configuration
|
|
|
|
## Best Practices
|
|
|
|
1. **Always use TypeScript** for plugin development
|
|
2. **Import types only** to avoid runtime dependencies
|
|
3. **Follow semantic versioning** for plugin releases
|
|
4. **Test thoroughly** before publishing
|
|
5. **Document your plugins** for other developers
|