Volt LogoVolt

Publishing Guide

How to publish and share your Volt extensions

Publishing Your Extension

Learn how to package and publish your Volt extensions to share with the community.

Distribution Method

Volt extensions are distributed as ZIP files via GitHub Releases. The official registry tracks available extensions and their download URLs.

Prerequisites

Before publishing, ensure your extension:

  • Has a unique id in kebab-case (e.g., password-generator)
  • Includes a valid manifest.json
  • Follows best practices
  • Has been thoroughly tested locally
  • Includes a README with usage instructions

Extension Package Structure

manifest.json
index.ts
types.ts
README.md

manifest.json Configuration

Every extension must have a manifest.json at the root:

{
  "id": "my-awesome-extension",
  "name": "My Awesome Extension",
  "version": "1.0.0",
  "description": "A brief description of what your extension does",
  "author": {
    "name": "Your Name",
    "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"]
}

Required Fields

FieldDescriptionExample
idUnique identifier (kebab-case)"password-generator"
nameDisplay name"Password Generator"
versionSemantic version"1.0.4"
descriptionShort description"Generate secure passwords"
mainEntry point file"index.ts"

Optional Fields

FieldDescriptionValues
authorAuthor info{ name, github?, email? }
iconIcon path"assets/icon.png"
categoryCategory for registryproductivity, utilities, development, media, social, finance, games, other
keywordsSearch keywords["password", "security"]
prefixTrigger prefix"gh" (triggers on gh: or gh )
minVoltVersionMinimum Volt version"0.4.0"
permissionsRequired permissions["clipboard", "filesystem", "network", "shell", "notifications"]
repositorySource repo URL"https://github.com/user/my-ext"
licenseLicense identifier"MIT"
filesFiles to package["index.ts", "utils/"]

Packaging Your Extension

Use the official CLI tool to validate and package your extension:

# Install the CLI
npm install -g @voltlaunchrr/plugin-cli

# Validate your extension
volt-plugin test

# Package and generate registry entry
volt-plugin publish

This creates a {id}-v{version}.zip file and outputs the registry entry JSON to add to registry.json.

Prepare Your Files

Ensure all necessary files are in your extension directory:

my-extension/
├── manifest.json      # Required
├── index.ts           # Entry point (from manifest.main)
├── types.ts           # Type definitions
├── README.md          # Documentation
└── utils/             # Supporting files
    └── helpers.ts

Create ZIP Archive

Package your extension as a ZIP file with the naming convention:

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

Example: 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

The ZIP should contain files at the root level, NOT inside a folder. When extracted, manifest.json should be directly accessible.

Test Your Package

Before publishing, test that your ZIP works:

  1. Extract the ZIP to a test folder
  2. Verify manifest.json is at the root
  3. Verify all files referenced in the manifest exist

Publishing to GitHub Releases

Create a GitHub Repository

Create a new repository for your extension on 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

Create a Git Tag

Tag your release with the version:

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

Create GitHub Release

  1. Go to your repository on GitHub
  2. Click Releases → Create a new release
  3. Select your tag (e.g., my-extension-v1.0.0)
  4. Set release title: My Extension v1.0.0
  5. Add release notes describing changes
  6. Upload your ZIP file as a release asset
  7. Publish the release

Your download URL will be:

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

Automated Releases with GitHub Actions

Create .github/workflows/release.yml to automate 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 }}

Submitting to the Official Registry

To make your extension discoverable in Volt's extension browser:

Fork the Extensions Repository

Fork VoltLaunchr/volt-extensions

Add Your Extension to registry.json

Edit registry.json and add your extension:

{
  "version": "1.0.3",
  "lastUpdated": "2026-04-14T04:45:00Z",
  "extensions": [
    // ... existing extensions (github, notion, password-generator) ...
    {
      "manifest": {
        "id": "my-extension",
        "name": "My Extension",
        "version": "1.0.0",
        "description": "A brief description",
        "author": {
          "name": "Your Name",
          "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"
    }
  ]
}

Registry entry fields:

FieldDescription
manifestComplete manifest.json object
downloadUrlGitHub release download URL (.zip or .tar.gz)
downloadsDownload count (starts at 0)
starsUser star count
verifiedSecurity-reviewed by maintainers
featuredPromoted in the Extension Store
createdAtSubmission date (ISO 8601)
updatedAtLast update date (ISO 8601)

Submit a Pull Request

Create a PR with your changes. Include:

  • Link to your extension repository
  • Brief description of functionality
  • Screenshots if applicable

README Template

Include a comprehensive README with your extension:

# My Extension

> Brief tagline describing your extension

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

Install from Volt's Extension Browser or manually:

1. Download the latest release
2. Open Volt Settings → Extensions
3. Click "Install from file" and select the ZIP

## Usage

Trigger the extension by typing:

- `keyword` - Basic usage
- `keyword option` - With option

### Examples

```
keyword 16        → Does something with 16
keyword custom    → Does something custom
```

## Configuration

| Option    | Default | Description |
| --------- | ------- | ----------- |
| `option1` | `true`  | Description |

## Requirements

- Volt v0.4.0 or higher

## License

MIT © Your Name

Versioning

Follow Semantic Versioning:

Change TypeVersion BumpExample
Bug fixesPATCH1.0.0 → 1.0.1
New features (backwards compatible)MINOR1.0.0 → 1.1.0
Breaking changesMAJOR1.0.0 → 2.0.0

Updating Your Extension

Update Version

Bump the version in manifest.json:

{
  "version": "1.1.0"
}

Create New Release

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

Update Registry

Submit a PR to update the downloadUrl and version in registry.json.

Community Guidelines

  • Be responsive to issues and feedback
  • Keep your README up to date
  • Add a CHANGELOG.md for tracking changes
  • Follow the Code of Conduct
  • Test thoroughly before releasing updates

Troubleshooting

Extension not loading?

Common issues and solutions:

IssueSolution
Extension not appearingCheck manifest.json is valid JSON
"Invalid manifest" errorVerify all required fields are present
Extension crashesCheck browser console for errors
ZIP won't installEnsure files are at root level, not in a subfolder

Support

Documentation

Full extension development docs

Examples

Reference implementations

GitHub Issues

Report bugs or request features

On this page

Publishing Your ExtensionPrerequisitesExtension Package Structuremanifest.json ConfigurationRequired FieldsOptional FieldsPackaging Your ExtensionPrepare Your FilesCreate ZIP ArchiveTest Your PackagePublishing to GitHub ReleasesCreate a GitHub RepositoryCreate a Git TagCreate GitHub ReleaseAutomated Releases with GitHub ActionsSubmitting to the Official RegistryFork the Extensions RepositoryAdd Your Extension to registry.jsonSubmit a Pull RequestREADME TemplateVersioningUpdating Your ExtensionUpdate VersionCreate New ReleaseUpdate RegistryCommunity GuidelinesTroubleshootingSupport