Volt LogoVolt
Extension Development

Workflow de développement

Configurez votre environnement local pour les extensions Volt

Workflow de développement

Apprenez à configurer votre environnement local pour développer et tester des extensions Volt.

Mise en place du projet

Créez le répertoire de l'extension

Utilisez l'outil CLI pour générer une nouvelle extension :

# Installez le CLI si ce n'est pas déjà fait
npm install -g @voltlaunchrr/plugin-cli

# Générez une nouvelle extension avec un questionnaire interactif
volt-plugin init my-extension
cd my-extension

Le CLI demande : ID d'extension, nom d'affichage, description, auteur, catégorie, permissions (cases à cocher), préfixe déclencheur et mots-clés.

Il génère manifest.json, src/index.ts, package.json et tsconfig.json, puis installe automatiquement les dépendances via votre gestionnaire de paquets détecté (bun > pnpm > npm).

mkdir my-extension
cd my-extension

Initialisez la structure du projet

Créez les fichiers essentiels :

manifest.json
index.ts
types.ts
manifest.json
{
  "id": "my-extension",
  "name": "My Extension",
  "version": "1.0.0",
  "description": "Ma super extension",
  "author": { "name": "Votre nom" },
  "main": "index.ts",
  "category": "utilities",
  "minVoltVersion": "0.4.0",
  "permissions": []
}

Installez le SDK (pour les types et le support IDE)

Installez le SDK officiel pour obtenir les définitions de types complètes et l'autocomplétion :

npm install @voltlaunchrr/plugin-api
bun add @voltlaunchrr/plugin-api
pnpm add @voltlaunchrr/plugin-api

Cela fournit automatiquement tous les types Plugin, PluginContext, PluginResult et PluginResultType.

Définitions de types

Le SDK (@voltlaunchrr/plugin-api) exporte tous les types nécessaires :

index.ts
import {
  Plugin,
  PluginContext,
  PluginResult,
  PluginResultType,
} from '@voltlaunchrr/plugin-api';

Si vous préférez ne pas installer le SDK, vous pouvez aussi définir les types localement. Voir la Référence API pour les définitions d'interface complètes.

Tests locaux

Méthode 1 : Mode dev (recommandé)

Comme Raycast !

Liez directement votre dossier d'extension à Volt pour un test instantané avec hot reload. Aucun packaging requis !

Ouvrez les paramètres de Volt

  1. Appuyez sur Ctrl+Espace pour ouvrir Volt
  2. Tapez settings et appuyez sur Entrée
  3. Allez dans l'onglet Extensions

Liez votre extension

  1. Cliquez sur « Lier une extension de dev »
  2. Sélectionnez le dossier de votre extension (ex. D:\dev\my-extension)
  3. Votre extension est chargée instantanément avec un badge DEV !

Testez et itérez

  • Tapez votre mot-clé déclencheur pour tester
  • Modifiez votre code et sauvegardez
  • Appuyez sur Ctrl+R pour rafraîchir Volt
  • Les changements sont immédiatement visibles !

Commandes du mode dev :

CommandeDescription
Lier une extension de devLier un dossier local
Délier une extension de devSupprimer une extension de dev
Rafraîchir l'extension de devRecharger depuis le disque

Hot reload

Les extensions de dev relisent automatiquement manifest.json à chaque requête, donc les changements de métadonnées sont instantanés. Pour les changements de code, utilisez Rafraîchir ou Ctrl+R.

Méthode 2 : Installation depuis un ZIP

Pour tester la version finale empaquetée :

Empaquetez votre extension

Créez un fichier ZIP contenant les fichiers de votre extension :

Compress-Archive -Path .\* -DestinationPath ..\my-extension-v1.0.0.zip
zip -r ../my-extension-v1.0.0.zip .

Installez dans Volt

  1. Ouvrez Volt
  2. Allez dans ParamètresExtensions
  3. Cliquez sur Installer depuis un fichier
  4. Sélectionnez votre fichier ZIP

Testez votre extension

Tapez votre mot-clé déclencheur dans Volt pour tester l'extension.

Méthode 3 : Installation directe du dossier

Pour l'installation manuelle (avancée) :

Trouvez le répertoire d'extensions

Volt stocke les extensions dans le répertoire de données de l'app :

%APPDATA%\volt\extensions\
~/Library/Application Support/volt/extensions/
~/.config/volt/extensions/

Copiez votre extension

Copiez directement votre dossier d'extension :

# Exemple pour Windows
cp -r ./my-extension "$env:APPDATA/volt/extensions/"

Mettez à jour installed.json

Ajoutez votre extension dans installed.json du répertoire extensions :

{
  "extensions": [
    {
      "id": "my-extension",
      "name": "My Extension",
      "version": "1.0.0",
      "enabled": true,
      "installedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Rechargez Volt

Redémarrez Volt ou utilisez la commande reload pour charger votre extension.

Débogage

DevTools du navigateur

Volt s'exécute dans une webview Tauri, qui prend en charge Chrome DevTools :

Activez les DevTools

Dans les builds de développement, appuyez sur F12 ou Ctrl+Maj+I pour ouvrir les DevTools.

Affichez la sortie de la console

Vos instructions console.log() apparaîtront dans l'onglet Console.

canHandle(context: PluginContext): boolean {
  console.log('Requête reçue :', context.query);
  return context.query.startsWith('my ');
}

Déboguez les erreurs

Vérifiez la Console pour toute erreur dans le code de votre extension.

Techniques de débogage courantes

class MyPlugin implements Plugin {
  // ...

  canHandle(context: PluginContext): boolean {
    // Debug : logge chaque requête
    console.log("[MyPlugin] canHandle appelé avec :", context.query);

    const result = context.query.startsWith("my ");
    console.log("[MyPlugin] résultat canHandle :", result);

    return result;
  }

  match(context: PluginContext): PluginResult[] {
    console.log("[MyPlugin] match appelé");

    try {
      // Votre logique de correspondance
      const results = this.generateResults(context);
      console.log("[MyPlugin] résultats générés :", results);
      return results;
    } catch (error) {
      console.error("[MyPlugin] erreur dans match :", error);
      return [];
    }
  }

  async execute(result: PluginResult): Promise<void> {
    console.log("[MyPlugin] execute appelé avec :", result);

    try {
      // Votre logique d'exécution
      await this.performAction(result);
      console.log("[MyPlugin] action exécutée avec succès");
    } catch (error) {
      console.error("[MyPlugin] erreur dans execute :", error);
      window.VoltAPI.notify("Une erreur est survenue", "error");
    }
  }
}

Processus de chargement d'une extension

Comprendre comment Volt charge les extensions aide au débogage :

1. Volt démarre

2. Le backend lit installed.json

3. Pour chaque extension activée :
   a. Lire tous les fichiers source (.ts, .js, .json)
   b. Bundler les fichiers en un seul JavaScript
   c. Transformer TypeScript → JavaScript (via Sucrase)
   d. Transformer imports/exports vers le système de modules
   e. Exécuter le bundle
   f. Récupérer l'export par défaut (votre classe Plugin)
   g. Instancier et enregistrer dans le Plugin Registry

4. L'extension est prête à traiter les requêtes

Points clés

Transformation TypeScript

Votre TypeScript est automatiquement compilé en JavaScript. Aucune étape de build requise. Cependant, seule la syntaxe TypeScript est prise en charge — pas les APIs Node.js.

  • Point d'entrée : le fichier spécifié dans manifest.main
  • Export par défaut : doit être une classe implémentant Plugin
  • Pas de Node.js : uniquement APIs navigateur (pas de fs, path, etc.)
  • Web Crypto : utilisez crypto.getRandomValues() au lieu du crypto de Node

Dépannage

Conseils de développement

1. Commencez simple

Démarrez avec une extension minimale et ajoutez des fonctionnalités de manière incrémentale :

class MinimalPlugin implements Plugin {
  id = "minimal";
  name = "Minimal";
  description = "Une extension minimale";
  enabled = true;

  canHandle(context: PluginContext): boolean {
    return context.query === "test";
  }

  match(context: PluginContext): PluginResult[] {
    return [
      {
        id: "1",
        type: window.VoltAPI.types.PluginResultType.Info,
        title: "Ça marche !",
        score: 100,
      },
    ];
  }

  execute(): void {
    window.VoltAPI.notify("Exécuté !", "success");
  }
}

export default MinimalPlugin;

2. Utilisez des logs descriptifs

const LOG_PREFIX = "[MyExtension]";

console.log(`${LOG_PREFIX} Initialisation…`);
console.log(`${LOG_PREFIX} Requête : "${context.query}"`);
console.error(`${LOG_PREFIX} Erreur :`, error);

3. Gérez les erreurs avec élégance

match(context: PluginContext): PluginResult[] {
  try {
    return this.generateResults(context);
  } catch (error) {
    console.error('Erreur lors de la génération des résultats :', error);
    return [{
      id: 'error',
      type: window.VoltAPI.types.PluginResultType.Info,
      title: 'Une erreur est survenue',
      subtitle: 'Voir la console pour les détails',
      icon: '⚠️',
      score: 0
    }];
  }
}

4. Testez les cas limites

  • Requête vide
  • Requêtes très longues
  • Caractères spéciaux
  • Entrée Unicode
  • Frappe rapide (debouncing)

Utiliser les templates d'extensions

Clonez les templates officiels pour démarrer rapidement :

# Clonez le dépôt volt-extensions
git clone https://github.com/VoltLaunchr/volt-extensions.git

# Copiez un template
cp -r volt-extensions/templates/typescript-plugin ./my-extension

# Commencez à développer
cd my-extension

Les templates incluent :

  • Template TypeScriptmanifest.json, package.json, tsconfig.json, src/index.ts préconfigurés
  • Template Rust — Squelette minimal de plugin backend Rust pour les opérations système

Le dépôt contient aussi des exemples prêts pour la production :

  • Calculatrice — Plugin multi-handler complexe avec parseurs, convertisseurs et UI React
  • Générateur de mot de passe — Génération crypto-sécurisée avec liste de mots EFF Diceware
  • Recherche web — Recherche multi-moteur simple en un seul fichier

Référence des commandes CLI

CommandeDescription
volt-plugin initGénérer une nouvelle extension avec prompts interactifs
volt-plugin testValider manifeste, interface plugin et types TypeScript
volt-plugin publishEmpaqueter en ZIP et produire le JSON d'entrée du registre

volt-plugin test vérifie :

  1. Validité de manifest.json (champs requis, ID en kebab-case, version semver)
  2. Interface plugin (les méthodes canHandle, match, execute existent)
  3. Compilation TypeScript (tsc --noEmit)

Sort avec le code 1 en cas d'échec.

Sortie de volt-plugin publish :

  1. Valide le manifeste
  2. Crée {id}-v{version}.zip
  3. Affiche une entrée JSON pour registry.json
  4. Affiche les instructions de soumission

Étapes suivantes

On this page