my_openplace/PLUGINS.md

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/:

   # 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:

   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:

docker run -d \
  -v ./my-plugins:/app/frontend/plugins \
  -e USE_FRONTEND_BACKUP=false \
  furryplace

Or with docker-compose:

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 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