DevelopersPlugin DevelopmentPublishing

Publishing Plugins

Share your plugin with the Lokus community through the official marketplace.

Prerequisites

Before publishing, ensure you have:

  1. A completed, tested plugin
  2. A Lokus account at lokusmd.com
  3. An API token for publishing

Quick Start

# 1. Build your plugin
npm run build
 
# 2. Validate the manifest
npx lokus-plugin validate
 
# 3. Login (first time only)
npx lokus-plugin login
 
# 4. Publish
npx lokus-plugin publish

Step-by-Step Guide

Step 1: Prepare Your Plugin

Update plugin.json:

{
  "manifest": "2.0",
  "id": "my-plugin",
  "name": "my-plugin",
  "displayName": "My Awesome Plugin",
  "version": "1.0.0",
  "description": "A detailed description of what your plugin does",
  "author": "Your Name",
  "license": "MIT",
  "main": "./dist/index.js",
  "lokusVersion": ">=1.0.0",
  "keywords": ["productivity", "editor"],
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-plugin"
  }
}

Ensure you have:

  • Clear, descriptive displayName and description
  • Correct version (semantic versioning)
  • Valid author information
  • Appropriate keywords for discoverability

Step 2: Build and Validate

# Build production bundle
npm run build
 
# Run tests
npm test
 
# Validate manifest
npx lokus-plugin validate

Expected output:

✓ Plugin manifest is valid
  Name: my-plugin
  Version: 1.0.0
  Description: A detailed description of what your plugin does

Step 3: Get Your API Token

  1. Go to lokusmd.com/marketplace
  2. Sign in to your account
  3. Navigate to Developer Settings
  4. Click Generate API Token
  5. Copy the token (starts with lok_)

Important: Keep your token secure. Don’t commit it to version control.

Step 4: Login

npx lokus-plugin login

When prompted, paste your API token.

Alternatively, use environment variables:

export LOKUS_REGISTRY_TOKEN=lok_xxxxxxxxxxxxxxxx

Step 5: Publish

npx lokus-plugin publish

Output:

Publishing my-plugin@1.0.0...
✓ Validated manifest
✓ Packaged plugin
✓ Uploaded to registry

Success! my-plugin@1.0.0 published
View at: https://lokusmd.com/marketplace/plugin/my-plugin

Version Management

Use semantic versioning (semver):

  • Patch (1.0.0 → 1.0.1): Bug fixes
  • Minor (1.0.0 → 1.1.0): New features (backwards compatible)
  • Major (1.0.0 → 2.0.0): Breaking changes
# Update version in package.json and plugin.json
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

Note: Keep package.json and plugin.json versions in sync.

Publishing Options

Dry Run

Test the publish process without actually uploading:

npx lokus-plugin publish --dry-run

Beta/Preview Releases

Publish to a specific tag:

npx lokus-plugin publish --tag beta

Users can install with:

# In Lokus marketplace, filter by "beta" releases

Custom Registry

For private registries:

npx lokus-plugin publish --registry https://your-registry.com

Plugin Visibility

All published plugins are:

  • Public by default
  • Immediately available in the marketplace
  • Searchable by name, description, and keywords

Best Practices

Documentation

Include a comprehensive README.md:

# My Plugin
 
Brief description of what your plugin does.
 
## Features
 
- Feature 1
- Feature 2
- Feature 3
 
## Installation
 
Available in the Lokus Marketplace.
 
## Usage
 
1. Open command palette (Cmd/Ctrl + Shift + P)
2. Type "My Plugin: Command Name"
3. Execute
 
## Configuration
 
| Setting | Default | Description |
|---------|---------|-------------|
| `myPlugin.option` | `true` | Description |
 
## License
 
MIT

Changelog

Maintain a CHANGELOG.md:

# Changelog
 
## [1.0.1] - 2024-01-15
 
### Fixed
- Bug fix description
 
## [1.0.0] - 2024-01-01
 
### Added
- Initial release
- Feature description

Screenshots

Include screenshots in your README to showcase your plugin’s UI.

Updating a Published Plugin

# 1. Make your changes
# 2. Update version
npm version patch
 
# 3. Build
npm run build
 
# 4. Publish update
npx lokus-plugin publish

Unpublishing

To remove a plugin from the marketplace, contact support at lokusmd.com.

Note: Unpublishing may break users who depend on your plugin.

Troubleshooting

”Authentication failed"

# Re-authenticate
npx lokus-plugin login
 
# Or set environment variable
export LOKUS_REGISTRY_TOKEN=lok_xxxxxxxxxxxxxxxx

"Version already exists”

You cannot overwrite an existing version. Bump your version:

npm version patch
npx lokus-plugin publish

“Invalid manifest”

Run validation to see specific errors:

npx lokus-plugin validate

“Network error”

Check your internet connection and try again:

npx lokus-plugin publish

Registry API

The registry is hosted at lokusmd.com/api/v1/registry/:

EndpointMethodDescription
/publishPOSTPublish a plugin
/searchGETSearch plugins
/download/\{id\}/\\{version\\}GETDownload plugin
/plugin/\\\{id\\\}GETPlugin details

Next Steps

CLI ToolsAdvanced Topics