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-extensionLe 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-extensionInitialisez la structure du projet
Créez les fichiers essentiels :
{
"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-apibun add @voltlaunchrr/plugin-apipnpm add @voltlaunchrr/plugin-apiCela 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 :
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
- Appuyez sur
Ctrl+Espacepour ouvrir Volt - Tapez
settingset appuyez sur Entrée - Allez dans l'onglet Extensions
Liez votre extension
- Cliquez sur « Lier une extension de dev »
- Sélectionnez le dossier de votre extension (ex.
D:\dev\my-extension) - 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+Rpour rafraîchir Volt - Les changements sont immédiatement visibles !
Commandes du mode dev :
| Commande | Description |
|---|---|
| Lier une extension de dev | Lier un dossier local |
| Délier une extension de dev | Supprimer une extension de dev |
| Rafraîchir l'extension de dev | Recharger 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.zipzip -r ../my-extension-v1.0.0.zip .Installez dans Volt
- Ouvrez Volt
- Allez dans Paramètres → Extensions
- Cliquez sur Installer depuis un fichier
- 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êtesPoints 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 ducryptode 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-extensionLes templates incluent :
- Template TypeScript —
manifest.json,package.json,tsconfig.json,src/index.tspré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
| Commande | Description |
|---|---|
volt-plugin init | Générer une nouvelle extension avec prompts interactifs |
volt-plugin test | Valider manifeste, interface plugin et types TypeScript |
volt-plugin publish | Empaqueter en ZIP et produire le JSON d'entrée du registre |
volt-plugin test vérifie :
- Validité de
manifest.json(champs requis, ID en kebab-case, version semver) - Interface plugin (les méthodes canHandle, match, execute existent)
- Compilation TypeScript (
tsc --noEmit)
Sort avec le code 1 en cas d'échec.
Sortie de volt-plugin publish :
- Valide le manifeste
- Crée
{id}-v{version}.zip - Affiche une entrée JSON pour
registry.json - Affiche les instructions de soumission