mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-05 19:24:39 +00:00
feat: add docs and dev plugins
This commit is contained in:
SethBurkart123
@@ -0,0 +1,550 @@
|
||||
# Developing Third-Party Plugins
|
||||
|
||||
BetterSEQTA+ supports third-party plugins, allowing developers to extend its functionality beyond what's provided by the built-in plugins. This guide covers everything you need to know about developing, distributing, and installing third-party plugins.
|
||||
|
||||
## Introduction to Third-Party Plugins
|
||||
|
||||
Third-party plugins are plugins developed outside of the main BetterSEQTA+ codebase. They can be created by anyone and distributed to users who want to extend their BetterSEQTA+ experience.
|
||||
|
||||
Unlike built-in plugins, which are included with BetterSEQTA+, third-party plugins must be installed separately by users. This allows for a wide range of extensions without bloating the core application.
|
||||
|
||||
## Plugin Structure
|
||||
|
||||
A third-party plugin is a JavaScript or TypeScript module that exports a plugin object conforming to the `Plugin` interface. It can be distributed as a single file or as a package with multiple files.
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```typescript
|
||||
// my-awesome-plugin.ts
|
||||
import { Plugin, PluginAPI, PluginSettings } from 'betterseqta-plugin-api';
|
||||
|
||||
export interface MyAwesomePluginSettings extends PluginSettings {
|
||||
enabled: {
|
||||
type: 'boolean';
|
||||
default: true;
|
||||
title: 'Enable My Awesome Plugin';
|
||||
description: 'Turn my awesome plugin on or off';
|
||||
};
|
||||
// Add more settings as needed
|
||||
}
|
||||
|
||||
export interface MyAwesomePluginStorage {
|
||||
lastRun: string;
|
||||
// Add more storage fields as needed
|
||||
}
|
||||
|
||||
const myAwesomePlugin: Plugin<MyAwesomePluginSettings, MyAwesomePluginStorage> = {
|
||||
id: 'my-awesome-plugin',
|
||||
name: 'My Awesome Plugin',
|
||||
description: 'A simple plugin for BetterSEQTA+',
|
||||
version: '1.0.0',
|
||||
author: 'Your Name',
|
||||
license: 'MIT',
|
||||
settings: {
|
||||
enabled: {
|
||||
type: 'boolean',
|
||||
default: true,
|
||||
title: 'Enable My Awesome Plugin',
|
||||
description: 'Turn my awesome plugin on or off',
|
||||
},
|
||||
// Initialize your settings here
|
||||
},
|
||||
run: (api) => {
|
||||
// Your plugin logic goes here
|
||||
console.log('My Awesome Plugin is running!');
|
||||
|
||||
// Return a cleanup function (optional but recommended)
|
||||
return () => {
|
||||
console.log('My Awesome Plugin is cleaning up!');
|
||||
// Cleanup logic goes here
|
||||
};
|
||||
},
|
||||
};
|
||||
|
||||
export default myAwesomePlugin;
|
||||
```
|
||||
|
||||
### Plugin Manifest
|
||||
|
||||
For plugins that consist of multiple files or that need additional resources, a manifest file is recommended. This file provides metadata about the plugin and points to the main plugin file.
|
||||
|
||||
```json
|
||||
// plugin.json
|
||||
{
|
||||
"id": "my-awesome-plugin",
|
||||
"name": "My Awesome Plugin",
|
||||
"description": "A simple plugin for BetterSEQTA+",
|
||||
"version": "1.0.0",
|
||||
"author": "Your Name",
|
||||
"license": "MIT",
|
||||
"main": "index.js",
|
||||
"dependencies": {
|
||||
"betterseqta-plus": "^1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development Environment
|
||||
|
||||
### Setting Up Your Development Environment
|
||||
|
||||
1. Clone the BetterSEQTA+ repository or create a new project:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/betterseqta-plus-plugin.git
|
||||
cd betterseqta-plus-plugin
|
||||
```
|
||||
|
||||
2. Initialize a new npm project:
|
||||
```bash
|
||||
npm init -y
|
||||
```
|
||||
|
||||
3. Install the necessary dependencies:
|
||||
```bash
|
||||
npm install --save-dev typescript webpack webpack-cli @types/node
|
||||
npm install --save betterseqta-plugin-api
|
||||
```
|
||||
|
||||
4. Set up TypeScript configuration:
|
||||
```json
|
||||
// tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "es2020",
|
||||
"module": "esnext",
|
||||
"moduleResolution": "node",
|
||||
"esModuleInterop": true,
|
||||
"strict": true,
|
||||
"declaration": true,
|
||||
"outDir": "dist",
|
||||
"lib": ["es2020", "dom"]
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
```
|
||||
|
||||
5. Set up webpack configuration:
|
||||
```javascript
|
||||
// webpack.config.js
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
entry: './src/index.ts',
|
||||
mode: 'production',
|
||||
module: {
|
||||
rules: [
|
||||
{
|
||||
test: /\.tsx?$/,
|
||||
use: 'ts-loader',
|
||||
exclude: /node_modules/,
|
||||
},
|
||||
],
|
||||
},
|
||||
resolve: {
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
output: {
|
||||
filename: 'index.js',
|
||||
path: path.resolve(__dirname, 'dist'),
|
||||
library: {
|
||||
type: 'umd',
|
||||
name: 'MyAwesomePlugin',
|
||||
},
|
||||
globalObject: 'this',
|
||||
},
|
||||
externals: {
|
||||
'betterseqta-plugin-api': 'betterseqta-plugin-api',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
6. Create your plugin in the `src` directory:
|
||||
```bash
|
||||
mkdir -p src
|
||||
touch src/index.ts
|
||||
```
|
||||
|
||||
7. Add build scripts to your `package.json`:
|
||||
```json
|
||||
"scripts": {
|
||||
"build": "webpack",
|
||||
"dev": "webpack --watch"
|
||||
}
|
||||
```
|
||||
|
||||
### Developing Your Plugin
|
||||
|
||||
1. Implement your plugin in `src/index.ts` following the structure shown above.
|
||||
|
||||
2. Build your plugin:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
3. For development, you can use the watch mode:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Testing Your Plugin
|
||||
|
||||
There are several ways to test your plugin during development:
|
||||
|
||||
#### Method 1: Plugin Development Mode
|
||||
|
||||
BetterSEQTA+ provides a development mode for testing plugins:
|
||||
|
||||
1. Open BetterSEQTA+ settings
|
||||
2. Navigate to the "Developer" section
|
||||
3. Enable "Plugin Development Mode"
|
||||
4. Click "Load Local Plugin" and select your plugin's directory or main file
|
||||
|
||||
#### Method 2: Manual Installation
|
||||
|
||||
You can manually install your plugin in a development environment:
|
||||
|
||||
1. Build your plugin
|
||||
2. Copy the output file to the BetterSEQTA+ plugins directory:
|
||||
```bash
|
||||
cp dist/index.js ~/.betterseqta/plugins/my-awesome-plugin/
|
||||
```
|
||||
3. Reload BetterSEQTA+
|
||||
|
||||
## Packaging and Distribution
|
||||
|
||||
### Creating a Plugin Package
|
||||
|
||||
A plugin package should include:
|
||||
|
||||
1. **The plugin code**: Compiled JavaScript file(s)
|
||||
2. **A manifest file**: `plugin.json` with metadata
|
||||
3. **Documentation**: README.md and other documentation
|
||||
4. **License**: A license file
|
||||
|
||||
Example file structure:
|
||||
```
|
||||
my-awesome-plugin/
|
||||
├── index.js # Compiled plugin code
|
||||
├── plugin.json # Plugin manifest
|
||||
├── README.md # Documentation
|
||||
└── LICENSE # License file
|
||||
```
|
||||
|
||||
### Publishing Your Plugin
|
||||
|
||||
You can publish your plugin in several ways:
|
||||
|
||||
#### 1. GitHub Repository
|
||||
|
||||
Host your plugin on GitHub:
|
||||
|
||||
1. Create a new repository
|
||||
2. Push your plugin code
|
||||
3. Create releases for new versions
|
||||
4. Users can install it using the GitHub URL
|
||||
|
||||
#### 2. npm Package
|
||||
|
||||
Publish your plugin as an npm package:
|
||||
|
||||
1. Prepare your package:
|
||||
```json
|
||||
// package.json
|
||||
{
|
||||
"name": "betterseqta-plugin-my-awesome",
|
||||
"version": "1.0.0",
|
||||
"description": "An awesome plugin for BetterSEQTA+",
|
||||
"main": "dist/index.js",
|
||||
"files": [
|
||||
"dist",
|
||||
"plugin.json",
|
||||
"README.md",
|
||||
"LICENSE"
|
||||
],
|
||||
"keywords": [
|
||||
"betterseqta",
|
||||
"plugin"
|
||||
],
|
||||
"author": "Your Name",
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
2. Build your plugin:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
3. Publish to npm:
|
||||
```bash
|
||||
npm publish
|
||||
```
|
||||
|
||||
#### 3. BetterSEQTA+ Plugin Directory
|
||||
|
||||
Submit your plugin to the official BetterSEQTA+ plugin directory:
|
||||
|
||||
1. Ensure your plugin follows all guidelines
|
||||
2. Create a pull request to add your plugin to the directory
|
||||
3. Once approved, your plugin will be available in the BetterSEQTA+ plugin browser
|
||||
|
||||
### Creating a Plugin Listing
|
||||
|
||||
Your plugin listing should include:
|
||||
|
||||
1. **Name and Description**: Clear, concise name and description
|
||||
2. **Screenshots**: Showcase your plugin in action
|
||||
3. **Features**: List of key features
|
||||
4. **Installation Instructions**: How to install your plugin
|
||||
5. **Configuration**: How to configure your plugin
|
||||
6. **Support Information**: Where users can get help
|
||||
|
||||
## Plugin Installation Guide
|
||||
|
||||
Include instructions for users to install your plugin:
|
||||
|
||||
### Method 1: Using the Plugin Browser
|
||||
|
||||
1. Open BetterSEQTA+
|
||||
2. Go to Settings → Plugins → Browse
|
||||
3. Search for "My Awesome Plugin"
|
||||
4. Click "Install"
|
||||
|
||||
### Method 2: Manual Installation
|
||||
|
||||
1. Download the plugin files
|
||||
2. Create a folder in the BetterSEQTA+ plugins directory:
|
||||
```bash
|
||||
mkdir -p ~/.betterseqta/plugins/my-awesome-plugin
|
||||
```
|
||||
3. Copy the plugin files to the folder:
|
||||
```bash
|
||||
cp -r * ~/.betterseqta/plugins/my-awesome-plugin/
|
||||
```
|
||||
4. Restart BetterSEQTA+
|
||||
|
||||
### Method 3: Using npm
|
||||
|
||||
If your plugin is published on npm:
|
||||
|
||||
```bash
|
||||
npm install -g betterseqta-plugin-my-awesome
|
||||
```
|
||||
|
||||
## Best Practices for Plugin Development
|
||||
|
||||
### Security Considerations
|
||||
|
||||
1. **Respect User Privacy**: Don't collect unnecessary data
|
||||
2. **Secure Data Handling**: Encrypt sensitive data
|
||||
3. **Minimize Permissions**: Only request the permissions you need
|
||||
4. **Code Review**: Get others to review your code for security issues
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
1. **Minimize DOM Operations**: Batch DOM operations when possible
|
||||
2. **Use Event Delegation**: Instead of adding many individual event listeners
|
||||
3. **Lazy Loading**: Load resources only when needed
|
||||
4. **Throttle and Debounce**: Limit frequent events like scroll or resize
|
||||
|
||||
### User Experience
|
||||
|
||||
1. **Clear UI**: Keep your UI simple and intuitive
|
||||
2. **Consistent Design**: Follow SEQTA's design language
|
||||
3. **Responsive Feedback**: Provide feedback for user actions
|
||||
4. **Error Handling**: Gracefully handle errors and inform the user
|
||||
|
||||
### Accessibility
|
||||
|
||||
1. **Keyboard Navigation**: Ensure all features are accessible via keyboard
|
||||
2. **Screen Reader Support**: Use appropriate ARIA attributes
|
||||
3. **Color Contrast**: Ensure sufficient contrast for text
|
||||
4. **Font Size**: Allow for text resizing
|
||||
|
||||
### Maintenance
|
||||
|
||||
1. **Version Control**: Use semantic versioning
|
||||
2. **Changelog**: Maintain a changelog
|
||||
3. **Documentation**: Keep documentation up to date
|
||||
4. **Issue Tracking**: Set up an issue tracker for bug reports and feature requests
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Plugin Communication
|
||||
|
||||
Plugins can communicate with each other using the Events API:
|
||||
|
||||
```typescript
|
||||
// Plugin A: Emit an event
|
||||
api.events.emit('pluginA:dataUpdated', { data: 'some data' });
|
||||
|
||||
// Plugin B: Listen for the event
|
||||
api.events.on('pluginA:dataUpdated', (data) => {
|
||||
console.log('Data from Plugin A:', data);
|
||||
});
|
||||
```
|
||||
|
||||
### Plugin Dependencies
|
||||
|
||||
If your plugin depends on other plugins, you should specify this in your manifest:
|
||||
|
||||
```json
|
||||
// plugin.json
|
||||
{
|
||||
"id": "my-awesome-plugin",
|
||||
"name": "My Awesome Plugin",
|
||||
"dependencies": {
|
||||
"another-plugin": "^1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Your plugin's `run` method should check if the dependencies are available:
|
||||
|
||||
```typescript
|
||||
run: (api) => {
|
||||
// Check if dependencies are available
|
||||
if (!window.betterseqta.plugins.isPluginLoaded('another-plugin')) {
|
||||
console.error('My Awesome Plugin requires Another Plugin to be installed and enabled');
|
||||
return;
|
||||
}
|
||||
|
||||
// Plugin logic
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin Configuration UI
|
||||
|
||||
For complex plugins, you might want to provide a custom settings UI beyond what the automatic settings generation provides:
|
||||
|
||||
```typescript
|
||||
settings: {
|
||||
enabled: {
|
||||
type: 'boolean',
|
||||
default: true,
|
||||
title: 'Enable My Awesome Plugin',
|
||||
description: 'Turn my awesome plugin on or off',
|
||||
},
|
||||
customUI: {
|
||||
type: 'custom',
|
||||
render: (container, value, onChange) => {
|
||||
// Create a custom UI
|
||||
const div = document.createElement('div');
|
||||
div.innerHTML = `
|
||||
<h3>Custom Settings</h3>
|
||||
<p>This is a custom settings UI.</p>
|
||||
<button>Click Me</button>
|
||||
`;
|
||||
|
||||
// Add event listeners
|
||||
div.querySelector('button').addEventListener('click', () => {
|
||||
// Do something
|
||||
onChange({ clicked: true });
|
||||
});
|
||||
|
||||
// Append to container
|
||||
container.appendChild(div);
|
||||
|
||||
// Return a cleanup function
|
||||
return () => {
|
||||
// Clean up event listeners
|
||||
div.querySelector('button').removeEventListener('click', handleClick);
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Internationalization
|
||||
|
||||
For plugins with international users, consider adding support for multiple languages:
|
||||
|
||||
```typescript
|
||||
// Define translations
|
||||
const translations = {
|
||||
en: {
|
||||
title: 'My Awesome Plugin',
|
||||
description: 'A simple plugin for BetterSEQTA+',
|
||||
button: 'Click Me',
|
||||
},
|
||||
fr: {
|
||||
title: 'Mon Plugin Génial',
|
||||
description: 'Un plugin simple pour BetterSEQTA+',
|
||||
button: 'Cliquez-moi',
|
||||
},
|
||||
};
|
||||
|
||||
// Get the current language
|
||||
const language = navigator.language.split('-')[0];
|
||||
const t = translations[language] || translations.en;
|
||||
|
||||
// Use translations
|
||||
console.log(t.title);
|
||||
```
|
||||
|
||||
## Troubleshooting and FAQ
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "Plugin not found" error
|
||||
|
||||
- Make sure your plugin is installed in the correct directory
|
||||
- Check that the plugin ID in your code matches the one in the manifest
|
||||
|
||||
#### "Plugin failed to load" error
|
||||
|
||||
- Check the console for error messages
|
||||
- Ensure your plugin's code is compatible with the current version of BetterSEQTA+
|
||||
|
||||
#### "Settings not saving" issue
|
||||
|
||||
- Make sure you're using the Settings API correctly
|
||||
- Check that your settings have the correct types
|
||||
|
||||
### FAQ
|
||||
|
||||
#### Q: Can I use external libraries in my plugin?
|
||||
A: Yes, you can include external libraries. However, be mindful of the size and performance impact.
|
||||
|
||||
#### Q: How do I update my plugin?
|
||||
A: Update the code, increment the version number, and publish the new version. Users will be notified of the update.
|
||||
|
||||
#### Q: Can I monetize my plugin?
|
||||
A: There's no built-in payment system, but you can offer premium versions or accept donations.
|
||||
|
||||
#### Q: How do I debug my plugin?
|
||||
A: Use the browser's developer tools to debug your plugin. BetterSEQTA+ also provides debugging tools in the developer settings.
|
||||
|
||||
## Contributing to the Plugin Ecosystem
|
||||
|
||||
### Reporting Issues
|
||||
|
||||
If you find a bug in the plugin API, report it on the BetterSEQTA+ GitHub repository:
|
||||
|
||||
1. Go to the Issues tab
|
||||
2. Click "New Issue"
|
||||
3. Select "Plugin API Bug"
|
||||
4. Fill in the details
|
||||
|
||||
### Contributing Documentation
|
||||
|
||||
Improvements to the plugin documentation are always welcome:
|
||||
|
||||
1. Fork the repository
|
||||
2. Make your changes
|
||||
3. Submit a pull request
|
||||
|
||||
### Sharing Your Plugins
|
||||
|
||||
Share your plugins with the community:
|
||||
|
||||
1. Announce your plugin on the BetterSEQTA+ forum
|
||||
2. Create a GitHub repository for your plugin
|
||||
3. Submit your plugin to the plugin directory
|
||||
|
||||
## Conclusion
|
||||
|
||||
Developing third-party plugins for BetterSEQTA+ is a rewarding way to customize and extend the platform. By following these guidelines, you can create high-quality plugins that enhance the experience for yourself and other users.
|
||||
|
||||
Remember that the plugin ecosystem thrives on community contributions. Share your plugins, collaborate with other developers, and help make BetterSEQTA+ even better for everyone!
|
||||
Reference in New Issue
Block a user