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

Field	Description	Example
`id`	Unique identifier (kebab-case)	`"password-generator"`
`name`	Display name	`"Password Generator"`
`version`	Semantic version	`"1.0.4"`
`description`	Short description	`"Generate secure passwords"`
`main`	Entry point file	`"index.ts"`

Optional Fields

Field	Description	Values
`author`	Author info	`{ name, github?, email? }`
`icon`	Icon path	`"assets/icon.png"`
`category`	Category for registry	`productivity`, `utilities`, `development`, `media`, `social`, `finance`, `games`, `other`
`keywords`	Search keywords	`["password", "security"]`
`minVoltVersion`	Minimum Volt version	`"0.4.0"`
`permissions`	Required permissions	`["clipboard", "filesystem", "network", "shell", "notifications"]`

Packaging Your Extension

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

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

# Navigate to parent directory
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:

Extract the ZIP to a test folder
Verify manifest.json is at the root
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

Go to your repository on GitHub
Click Releases → Create a new release
Select your tag (e.g., my-extension-v1.0.0)
Set release title: My Extension v1.0.0
Add release notes describing changes
Upload your ZIP file as a release asset
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.1",
  "lastUpdated": "2024-12-26T09:30:00Z",
  "extensions": [
    // ... existing extensions ...
    {
      "manifest": {
        "id": "my-extension",
        "name": "My Extension",
        "version": "1.0.0",
        "description": "A brief description",
        "author": {
          "name": "Your Name",
          "github": "yourusername"
        },
        "main": "index.ts",
        "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": "2024-12-26T12:00:00Z",
      "updatedAt": "2024-12-26T12:00:00Z"
    }
  ]
}

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 Type	Version Bump	Example
Bug fixes	PATCH	`1.0.0` → `1.0.1`
New features (backwards compatible)	MINOR	`1.0.0` → `1.1.0`
Breaking changes	MAJOR	`1.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:

Issue	Solution
Extension not appearing	Check `manifest.json` is valid JSON
"Invalid manifest" error	Verify all required fields are present
Extension crashes	Check browser console for errors
ZIP won't install	Ensure 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

Publishing Guide