Plugin API Reference

Complete API documentation for Volt plugins.

Frontend Plugin API

Plugin Interface

The main interface that all plugins must implement:

interface Plugin {
  id: string;
  name: string;
  description: string;
  enabled: boolean;
  canHandle(context: PluginContext): boolean;
  match(
    context: PluginContext
  ): Promise<PluginResult[]> | PluginResult[] | null;
  execute(result: PluginResult): Promise<void> | void;
}

Plugin Properties

`id: string`

Unique identifier for the plugin. Used internally to identify the plugin.

Recommended format: kebab-case (e.g., my-awesome-plugin)

id = "web-search";

`name: string`

Display name of the plugin shown in the UI.

name = "Web Search";

`description: string`

Short description of what the plugin does.

description = "Search the web directly from Volt";

`enabled: boolean`

Whether the plugin is currently enabled and can process queries.

enabled = true;

Plugin Methods

`canHandle(context: PluginContext): boolean`

Determines if this plugin should handle the current query.

Parameters:

context: Current plugin context containing query and metadata

Returns: boolean - True if the plugin can handle this query

Example:

canHandle(context: PluginContext): boolean {
  return context.query.startsWith('search ');
}

`match(context: PluginContext): Promise<PluginResult[]>`

Generates results for the query.

Parameters:

context: Current plugin context

Returns: Promise<PluginResult[]> - Array of results to display

Example:

async match(context: PluginContext): Promise<PluginResult[]> {
  const query = context.query.replace('search ', '');

  return [
    {
      id: '1',
      title: `Search for "${query}"`,
      subtitle: 'Open in browser',
      icon: '🔍',
      type: PluginResultType.WebSearch,
      action: () => {
        window.open(`https://google.com/search?q=${encodeURIComponent(query)}`);
      },
    },
  ];
}

`execute(result: PluginResult): Promise<void>`

Executes the selected result.

Parameters:

result: The plugin result to execute

Returns: Promise<void>

Example:

async execute(result: PluginResult): Promise<void> {
  if (result.action) {
    await result.action();
  }
}

Types

PluginContext

Context information passed to plugin methods:

interface PluginContext {
  query: string; // User's search query
  timestamp: number; // When the query was made
  metadata?: {
    [key: string]: any; // Additional metadata
  };
}

PluginResult

Result object returned by plugins:

interface PluginResult {
  id: string; // Unique identifier
  title: string; // Main title
  subtitle?: string; // Optional subtitle
  icon?: string; // Icon (emoji or URL)
  type: PluginResultType; // Result type
  action?: () => void | Promise<void>; // Action to execute
  metadata?: {
    [key: string]: any; // Additional data
  };
}

PluginResultType

Types of results plugins can return:

enum PluginResultType {
  Calculator = "calculator",
  WebSearch = "websearch",
  SystemCommand = "systemcommand",
  Timer = "timer",
  SystemMonitor = "systemmonitor",
  Steam = "steam",
  Game = "game",
  Clipboard = "clipboard",
  Emoji = "emoji",
  Info = "info",
}

Backend API (Rust)

VoltPluginAPI Trait

Implement this trait for backend plugins:

pub trait VoltPluginAPI {
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn scan(&self) -> Result<Vec<PluginResult>, PluginError>;
    fn execute(&self, action: &str) -> Result<(), PluginError>;
}

Example Backend Plugin

use volt_plugin_api::{VoltPluginAPI, PluginResult, PluginError};

pub struct MyBackendPlugin;

impl VoltPluginAPI for MyBackendPlugin {
    fn name(&self) -> &str {
        "My Backend Plugin"
    }

    fn version(&self) -> &str {
        "1.0.0"
    }

    fn scan(&self) -> Result<Vec<PluginResult>, PluginError> {
        Ok(vec![
            PluginResult {
                id: String::from("1"),
                title: String::from("System Info"),
                subtitle: Some(String::from("View system information")),
                icon: Some(String::from("💻")),
                result_type: String::from("info"),
            },
        ])
    }

    fn execute(&self, action: &str) -> Result<(), PluginError> {
        println!("Executing action: {}", action);
        Ok(())
    }
}

Tauri Commands

Available Tauri commands for plugin communication:

`get_plugin_config(plugin_id: string)`

Get configuration for a specific plugin.

import { invoke } from "@tauri-apps/api/core";

const config = await invoke("get_plugin_config", { pluginId: "my-plugin" });

`set_plugin_config(plugin_id: string, config: any)`

Save plugin configuration.

await invoke("set_plugin_config", {
  pluginId: "my-plugin",
  config: { enabled: true, apiKey: "xxx" },
});

Events System

Subscribing to Events

import { listen } from "@tauri-apps/api/event";

const unlisten = await listen("plugin-update", (event) => {
  console.log("Plugin updated:", event.payload);
});

// Cleanup
unlisten();

Available Events

plugin-update: Fired when a plugin is updated
plugin-enabled: Fired when a plugin is enabled
plugin-disabled: Fired when a plugin is disabled
plugin-error: Fired when a plugin encounters an error

Helper Functions

`registerPlugin(plugin: Plugin)`

import { registerPlugin } from "@/lib/plugins/registry";

registerPlugin(new MyAwesomePlugin());

`unregisterPlugin(pluginId: string)`

Unregister a plugin.

import { unregisterPlugin } from "@/lib/plugins/registry";

unregisterPlugin("my-plugin");

For more examples and best practices, check out the Plugin Examples section.

API Reference

On this page