zack3d
785032a8ad
Resolve plugin directory based on USE_FRONTEND_BACKUP so /api/plugins works with both frontend-backup and built frontend, aligning with index.ts. Ensure /app/frontend/plugins is created during non-backup Docker builds to avoid missing-directory issues at runtime. Update backup asset import reference and adjust local helper script path.
126 lines
3.5 KiB
Markdown
126 lines
3.5 KiB
Markdown
# FurryPlace Plugins System
|
|
|
|
The FurryPlace SDK provides an extensible plugin system that allows you to add custom buttons and functionality to the UI without modifying the core codebase.
|
|
|
|
## Quick Start
|
|
|
|
### Development (Local)
|
|
|
|
1. Add your plugin file to `frontend-backup/plugins/`:
|
|
```bash
|
|
# Example: Create a custom button plugin
|
|
cat > frontend-backup/plugins/my-plugin.js << 'EOF'
|
|
(function() {
|
|
function waitForSDK(callback) {
|
|
if (window.FurryPlaceSDK) {
|
|
callback();
|
|
} else {
|
|
setTimeout(() => waitForSDK(callback), 100);
|
|
}
|
|
}
|
|
|
|
waitForSDK(() => {
|
|
window.FurryPlaceSDK.registerButton({
|
|
id: 'my-button',
|
|
title: 'My Custom Button',
|
|
position: 'bottom',
|
|
icon: '<svg>...</svg>',
|
|
onClick: () => alert('Clicked!')
|
|
});
|
|
});
|
|
})();
|
|
EOF
|
|
```
|
|
|
|
2. Refresh your browser - the plugin loads automatically!
|
|
|
|
### Production (Docker)
|
|
|
|
When using `USE_FRONTEND_BACKUP=true`:
|
|
|
|
1. **Before building the Docker image**, add plugins to `frontend-backup/plugins/`
|
|
2. Build the image:
|
|
```bash
|
|
docker build --build-arg USE_FRONTEND_BACKUP=true -t furryplace .
|
|
```
|
|
3. The plugins will be included in the image automatically
|
|
|
|
When using the regular frontend build (not `USE_FRONTEND_BACKUP`):
|
|
|
|
1. Create a `frontend-src/public/plugins/` directory
|
|
2. Add your plugin files there
|
|
3. Build normally - the plugins will be copied to the final build
|
|
|
|
### Runtime Plugin Loading (Docker Volume)
|
|
|
|
You can also mount a plugins directory at runtime to add/update plugins without rebuilding:
|
|
|
|
```bash
|
|
docker run -d \
|
|
-v ./my-plugins:/app/frontend/plugins \
|
|
-e USE_FRONTEND_BACKUP=false \
|
|
furryplace
|
|
```
|
|
|
|
Or with docker-compose:
|
|
|
|
```yaml
|
|
services:
|
|
furryplace:
|
|
image: furryplace
|
|
volumes:
|
|
- ./my-plugins:/app/frontend/plugins
|
|
environment:
|
|
USE_FRONTEND_BACKUP: "false"
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Backend**: The `/api/plugins` endpoint (in `src/routes/plugins.ts`) scans the plugins directory and returns a list of `.js` files
|
|
2. **Frontend**: The SDK (`furryplace-sdk.js`) automatically fetches this list and dynamically loads each plugin
|
|
3. **Plugins**: Each plugin registers buttons or functionality using the SDK API
|
|
|
|
## Plugin Development
|
|
|
|
See the full documentation in [frontend-backup/plugins/README.md](frontend-backup/plugins/README.md) for:
|
|
- SDK API reference
|
|
- Button configuration options
|
|
- Example plugins
|
|
- Troubleshooting tips
|
|
|
|
## Environment Variables
|
|
|
|
The plugin system respects the `USE_FRONTEND_BACKUP` environment variable:
|
|
- `USE_FRONTEND_BACKUP=true` → Loads from `frontend-backup/plugins/`
|
|
- `USE_FRONTEND_BACKUP=false` → Loads from `frontend/plugins/`
|
|
|
|
This is automatically handled by the backend routes.
|
|
|
|
## Disabling Plugins
|
|
|
|
To disable a plugin without deleting it:
|
|
1. Rename it to anything that doesn't end in `.js` (e.g., `my-plugin.js.disabled`)
|
|
2. Refresh the page
|
|
|
|
The SDK only loads files ending in `.js`.
|
|
|
|
## Security Notes
|
|
|
|
- Plugins have full access to the browser's JavaScript environment
|
|
- Only load plugins from trusted sources
|
|
- Consider reviewing plugin code before deployment
|
|
- Plugins run in the same origin as your application
|
|
|
|
## Examples
|
|
|
|
Example plugins are included in `frontend-backup/plugins/example-button.js`:
|
|
- Help button with tooltip
|
|
- Debug info button
|
|
- Conditional rendering example
|
|
- External link button (Discord)
|
|
|
|
To try them out:
|
|
1. The example plugin is automatically loaded
|
|
2. Check the browser console for loading messages
|
|
3. Look for the new buttons in the UI
|