Publier votre extension

Apprenez à empaqueter et publier vos extensions Volt pour les partager avec la communauté.

Méthode de distribution

Les extensions Volt sont distribuées sous forme de fichiers ZIP via GitHub Releases. Le registre officiel suit les extensions disponibles et leurs URL de téléchargement.

Prérequis

Avant de publier, assurez-vous que votre extension :

A un id unique en kebab-case (ex. password-generator)
Inclut un manifest.json valide
Respecte les bonnes pratiques
A été testée en profondeur localement
Inclut un README avec les instructions d'utilisation

Structure du paquet d'extension

manifest.json

index.ts

types.ts

README.md

Configuration de manifest.json

Chaque extension doit avoir un manifest.json à la racine :

{
  "id": "my-awesome-extension",
  "name": "My Awesome Extension",
  "version": "1.0.0",
  "description": "Brève description de ce que fait votre extension",
  "author": {
    "name": "Votre nom",
    "github": "yourusername",
    "email": "you@example.com"
  },
  "main": "index.ts",
  "icon": "assets/icon.png",
  "category": "utilities",
  "keywords": ["keyword1", "keyword2"],
  "repository": "https://github.com/yourusername/my-extension",
  "homepage": "https://your-extension-site.com",
  "license": "MIT",
  "minVoltVersion": "0.4.0",
  "permissions": ["clipboard"]
}

Champs requis

Champ	Description	Exemple
`id`	Identifiant unique (kebab-case)	`"password-generator"`
`name`	Nom d'affichage	`"Password Generator"`
`version`	Version sémantique	`"1.0.4"`
`description`	Courte description	`"Générer des mots de passe sûrs"`
`main`	Fichier de point d'entrée	`"index.ts"`

Champs optionnels

Champ	Description	Valeurs
`author`	Infos de l'auteur	`{ name, github?, email? }`
`icon`	Chemin de l'icône	`"assets/icon.png"`
`category`	Catégorie du registre	`productivity`, `utilities`, `development`, `media`, `social`, `finance`, `games`, `other`
`keywords`	Mots-clés de recherche	`["password", "security"]`
`prefix`	Préfixe déclencheur	`"gh"` (déclenche sur `gh:` ou `gh` )
`minVoltVersion`	Version minimale de Volt	`"0.4.0"`
`permissions`	Permissions requises	`["clipboard", "filesystem", "network", "shell", "notifications"]`
`repository`	URL du dépôt source	`"https://github.com/user/my-ext"`
`license`	Identifiant de licence	`"MIT"`
`files`	Fichiers à empaqueter	`["index.ts", "utils/"]`

Empaqueter votre extension

Utilisez l'outil CLI officiel pour valider et empaqueter votre extension :

# Installer le CLI
npm install -g @voltlaunchrr/plugin-cli

# Valider votre extension
volt-plugin test

# Empaqueter et générer l'entrée du registre
volt-plugin publish

Cela crée un fichier {id}-v{version}.zip et affiche le JSON d'entrée du registre à ajouter à registry.json.

Préparez vos fichiers

Assurez-vous que tous les fichiers nécessaires sont dans votre répertoire d'extension :

my-extension/
├── manifest.json      # Requis
├── index.ts           # Point d'entrée (depuis manifest.main)
├── types.ts           # Définitions de types
├── README.md          # Documentation
└── utils/             # Fichiers de support
    └── helpers.ts

Créez une archive ZIP

Empaquetez votre extension sous forme de ZIP en suivant la convention de nommage :

{extension-id}-v{version}.zip

Exemple : password-generator-v1.0.4.zip

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

cd my-extension
zip -r ../my-extension-v1.0.0.zip .

Important

Le ZIP doit contenir les fichiers à la racine, PAS à l'intérieur d'un dossier. À l'extraction, manifest.json doit être directement accessible.

Testez votre paquet

Avant de publier, testez que votre ZIP fonctionne :

Extrayez le ZIP dans un dossier de test
Vérifiez que manifest.json est à la racine
Vérifiez que tous les fichiers référencés dans le manifeste existent

Publier sur GitHub Releases

Créez un dépôt GitHub

Créez un nouveau dépôt pour votre extension sur GitHub.

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/my-extension.git
git push -u origin main

Créez un tag Git

Taggez votre release avec la version :

# Format : {extension-id}-v{version}
git tag my-extension-v1.0.0
git push origin my-extension-v1.0.0

Créez une GitHub Release

Allez sur votre dépôt sur GitHub
Cliquez sur Releases → Create a new release
Sélectionnez votre tag (ex. my-extension-v1.0.0)
Définissez le titre : My Extension v1.0.0
Ajoutez des notes de release décrivant les changements
Uploadez votre fichier ZIP en tant qu'asset
Publiez la release

Votre URL de téléchargement sera :

https://github.com/yourusername/my-extension/releases/download/my-extension-v1.0.0/my-extension-v1.0.0.zip

Releases automatisées avec GitHub Actions

Créez .github/workflows/release.yml pour automatiser les releases :

name: Release Extension

on:
  push:
    tags:
      - "*-v*"

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get extension info
        id: info
        run: |
          echo "id=$(jq -r '.id' manifest.json)" >> $GITHUB_OUTPUT
          echo "version=$(jq -r '.version' manifest.json)" >> $GITHUB_OUTPUT

      - name: Create ZIP
        run: |
          zip -r ${{ steps.info.outputs.id }}-v${{ steps.info.outputs.version }}.zip . \
            -x ".git/*" -x ".github/*" -x "node_modules/*"

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ steps.info.outputs.id }}-v${{ steps.info.outputs.version }}.zip
          generate_release_notes: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Soumission au registre officiel

Pour rendre votre extension découvrable dans le navigateur d'extensions de Volt :

Forkez le dépôt d'extensions

Forkez VoltLaunchr/volt-extensions

Ajoutez votre extension à registry.json

Éditez registry.json et ajoutez votre extension :

{
  "version": "1.0.3",
  "lastUpdated": "2026-04-14T04:45:00Z",
  "extensions": [
    // ... extensions existantes (github, notion, password-generator) ...
    {
      "manifest": {
        "id": "my-extension",
        "name": "My Extension",
        "version": "1.0.0",
        "description": "Brève description",
        "author": {
          "name": "Votre nom",
          "github": "yourusername"
        },
        "main": "index.ts",
        "prefix": "my",
        "category": "utilities",
        "keywords": ["keyword1", "keyword2"],
        "minVoltVersion": "0.4.0",
        "permissions": ["clipboard"]
      },
      "downloadUrl": "https://github.com/yourusername/my-extension/releases/download/my-extension-v1.0.0/my-extension-v1.0.0.zip",
      "downloads": 0,
      "stars": 0,
      "verified": false,
      "featured": false,
      "createdAt": "2026-04-16T12:00:00Z",
      "updatedAt": "2026-04-16T12:00:00Z"
    }
  ]
}

Champs de l'entrée du registre :

Champ	Description
`manifest`	Objet manifest.json complet
`downloadUrl`	URL de téléchargement GitHub release (.zip/.tar.gz)
`downloads`	Compteur de téléchargements (commence à 0)
`stars`	Nombre d'étoiles utilisateur
`verified`	Revu pour la sécurité par les mainteneurs
`featured`	Mis en avant dans la Boutique
`createdAt`	Date de soumission (ISO 8601)
`updatedAt`	Date de dernière mise à jour (ISO 8601)

Soumettez une pull request

Créez une PR avec vos changements. Incluez :

Lien vers le dépôt de votre extension
Brève description des fonctionnalités
Captures d'écran si pertinent

Modèle de README

Incluez un README complet avec votre extension :

# My Extension

> Phrase d'accroche brève décrivant votre extension

## Fonctionnalités

- Fonctionnalité 1
- Fonctionnalité 2
- Fonctionnalité 3

## Installation

Installez depuis le navigateur d'extensions de Volt ou manuellement :

1. Téléchargez la dernière release
2. Ouvrez Paramètres Volt → Extensions
3. Cliquez sur « Installer depuis un fichier » et sélectionnez le ZIP

## Utilisation

Déclenchez l'extension en tapant :

- `keyword` — Utilisation de base
- `keyword option` — Avec une option

### Exemples

```
keyword 16        → Fait quelque chose avec 16
keyword custom    → Fait quelque chose de personnalisé
```

## Configuration

| Option    | Défaut  | Description |
| --------- | ------- | ----------- |
| `option1` | `true`  | Description |

## Prérequis

- Volt v0.4.0 ou supérieur

## Licence

MIT © Votre nom

Versioning

Suivez le Semantic Versioning :

Type de changement	Bump de version	Exemple
Corrections de bugs	PATCH	`1.0.0` → `1.0.1`
Nouvelles fonctionnalités (compatibles)	MINOR	`1.0.0` → `1.1.0`
Breaking changes	MAJOR	`1.0.0` → `2.0.0`

Mettre à jour votre extension

Mettez à jour la version

Incrémentez la version dans manifest.json :

{
  "version": "1.1.0"
}

Créez une nouvelle release

git add .
git commit -m "Release v1.1.0"
git tag my-extension-v1.1.0
git push origin main --tags

Mettez à jour le registre

Soumettez une PR pour mettre à jour downloadUrl et la version dans registry.json.

Lignes directrices communautaires

Soyez réactif aux issues et aux retours
Gardez votre README à jour
Ajoutez un CHANGELOG.md pour suivre les changements
Respectez le Code de conduite
Testez en profondeur avant de publier des mises à jour

Dépannage

Extension qui ne se charge pas ?

Problèmes courants et solutions :

Problème	Solution
Extension n'apparaît pas	Vérifiez que `manifest.json` est un JSON valide
Erreur « Invalid manifest »	Vérifiez que tous les champs requis sont présents
L'extension plante	Vérifiez la console du navigateur pour les erreurs
Le ZIP ne s'installe pas	Vérifiez que les fichiers sont à la racine, pas dans un sous-dossier

Support

Documentation

Docs complètes de développement d'extensions

Exemples

Implémentations de référence

Issues GitHub

Signalez un bug ou demandez une fonctionnalité

Guide de publication