Plugin System Overview

What Plugins Can Provide

Architecture Overview

The plugin system is built around a central PluginManager singleton that handles the entire lifecycle. Plugins are stored in localStorage and loaded on app startup.

Plugin File Format (.vbplugin)

A .vbplugin file is simply a JSON file containing a PluginDefinition object. Everything the plugin needs—code, metadata, styles, and documentation—is bundled into this single file.

{
  "pluginApiVersion": "1.0",
  "metadata": { ... },
  "controls": [ ... ],
  "functions": [ ... ],
  "styles": "CSS string",
  "helpContent": "HTML string"
}

Complete Type Reference

Below is the full TypeScript interface reference for every object in the plugin system. These types define the contract between your plugin and WebVB Studio.

interface PluginDefinition {
  pluginApiVersion: '1.0';       // Must be "1.0"
  metadata: PluginMetadata;       // Required: name, id, version, author
  controls?: PluginControlDef[];  // Optional: custom controls
  functions?: PluginFunctionDef[];// Optional: custom functions
  styles?: string;                // Optional: CSS to inject
  helpContent?: string;           // Optional: HTML documentation
}

interface PluginPropertyDef {
  id: string;            // Property key, e.g. "Value", "MaxStars"
  label: string;         // Display label in Properties panel
  type: 'text' | 'number' | 'boolean' | 'color' | 'select' | 'textarea';
  defaultValue?: any;    // Default when control is first created
  options?: string[];    // Choices for 'select' type
  description?: string;  // Tooltip text
  category?: string;     // Group heading, e.g. "Appearance", "Behavior"
}

interface PluginEventDef {
  name: string;          // Event name, e.g. "Change", "Click", "ColorSelected"
  description?: string;  // Explains when this event fires
  params?: string[];     // Parameters passed to the handler, e.g. ["NewValue"]
}

interface InstalledPlugin {
  definition: PluginDefinition;
  status: 'active' | 'disabled' | 'error';
  installedAt: string;     // ISO 8601 date string
  error?: string;          // Error message if status is 'error'
}

Control Type Namespacing

To avoid collisions between plugins, all plugin control types are automatically namespaced. When you define a control with typeName: "StarRating" in a plugin with id: "com.webvb.starrating", the control is registered internally as:

The format is plugin:{pluginId}/{typeName}. This ensures two plugins can both define a "ColorPicker" control without conflict. Helper functions are provided:

// Build a namespaced type string
getPluginControlType("com.webvb.starrating", "StarRating")
// → "plugin:com.webvb.starrating/StarRating"

// Check if a type is from a plugin
isPluginControlType("plugin:com.webvb.starrating/StarRating")
// → true

// Parse back to components
parsePluginControlType("plugin:com.webvb.starrating/StarRating")
// → { pluginId: "com.webvb.starrating", typeName: "StarRating" }

PluginManager API

The pluginManager singleton provides the full API for managing plugins. Import it from services/PluginManager.

function usePlugins() {
  const [plugins, setPlugins] = useState(
    pluginManager.getAllPlugins()
  );
  
  useEffect(() => {
    return pluginManager.subscribe(() => {
      setPlugins(pluginManager.getAllPlugins());
    });
  }, []);
  
  return plugins;
}

Code Execution Model

Plugin code runs in a semi-sandboxed environment. Both renderer functions and custom functions are compiled using new Function(), which provides separation from the main application scope.

new Function('props', 'controlId', yourCodeString);

new Function('param1', 'param2', ..., yourJsCode);

Built-in Example Plugins

WebVB Studio includes four example plugins in the Gallery tab of the Plugin Manager. These demonstrate different plugin capabilities and serve as templates for your own plugins.

Managing Plugins (UI)

The Plugin Manager dialog (accessible from the toolbar) provides a full UI for managing plugins with four tabs:

Next Steps