Publishing to the Plugin Market

The official Komari plugin market is an open-source catalog repository (plugin-market) holding plugin metadata, download URLs, and SHA-256 checksums. Plugin packages remain hosted by their authors; the market handles the catalog, validation, and distribution index.

The plugin market is built into the server; the default source is the official Komari catalog. The server supports multiple configurable market sources (REST endpoints: see RPC Methods - Plugin management).

Catalog entry (v1.json)

Each installable plugin contains these fields:

{
  "name": {
    "zh-CN": "Komari Test Plugin",
    "en": "Komari Test Plugin"
  },
  "short": "TestPlugin",
  "description": {
    "zh-CN": "A test plugin for Komari",
    "en": "A test plugin for Komari"
  },
  "version": "1.0.0",
  "author": "Your Name",
  "url": "https://github.com/your-name/komari-example",
  "preview": "https://example.com/preview.png",
  "download": "https://example.com/plugin.zip",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "komari": ">=1.0.0"
}

Field	Required	Description
name	Yes	string or i18n object
short	Yes	unique plugin short name, [A-Za-z0-9_-]; entries sorted case-insensitively by short, no duplicates
description	No	string or i18n object
version	Yes	plugin version
author	Yes	string or i18n object
url	No	project homepage, HTTP(S) URL without userinfo (user:pass@)
preview	No	preview image, absolute HTTP(S) URL; PNG/JPEG/GIF/WebP/AVIF
download	paired with sha256	plugin ZIP download URL, absolute HTTP(S); may be omitted together with sha256 for source-only entries
sha256	paired with download	lowercase SHA-256 of that exact ZIP (64 hex chars)
komari	No	server version constraint, must exactly match komari-plugin.json

Install validation

When installing from the market, the server: downloads (cap 100 MiB) → verifies SHA-256 → verifies the package manifest matches the catalog's short and version → installs. Catalogs are cached on the server for 10 minutes.

Submitting a plugin

Choose the appropriate template on the plugin-market repository issues page. The submission is fully automated by GitHub Actions: after validation passes, an update PR is created automatically.

Note

Fill in the fixed Issue Form fields as-is; do not rename or reorder field headings — the Action reads them by name.

Option 1: Open-source GitHub plugin

Only required:

• GitHub repository URL (must be public)
• Preview image URL
• Confirmation that the latest Release ships a plugin package

The Action reads the repository's latest Release and finds the single valid plugin ZIP among its assets (the package must contain a root-level komari-plugin.json).

Option 2: Plugin hosted outside GitHub

Provide:

• Project URL (must not be GitHub-hosted)
• Package download URL (must not be GitHub-hosted)
• Preview image URL
• Plugin name, unique short name, version, description, and author
• Confirmation that the code is not malicious and the package has no auto-updates

Validation rules (run automatically on submission)

Category	Rule
URLs	credentials rejected; download hosts must not be private/internal IPs; GitHub URLs rejected for the external-hosted form
Package size	download ≤ 100 MiB, ≤ 10 redirects
Package safety	no absolute/traversal/backslash/NUL paths, no symlinks; ≤ 10,000 files, ≤ 128 MiB per file, ≤ 512 MiB extracted
Manifest	exactly one root komari-plugin.json (≤ 1 MiB); valid name/short/version/author
Consistency	short and version from the external-hosted form must match the in-package manifest
Preview	PNG/JPEG/GIF/WebP/AVIF; GitHub blob links normalized to raw links
Catalog	SHA-256 computed, sorted case-insensitively by short, updated_at updated

On failure the Action comments the reason on the issue and closes it; transient failures (403/408/425/429/5xx, DNS) leave the issue open for retry.

Release auto-updates

For catalog entries backed by GitHub repositories, an update workflow runs every 6 hours:

1. Builds the download URL from the repository URL + latest Release tag + current asset name (GitHub API asset URL as fallback).
2. Re-validates the in-package manifest, short, version, and SHA-256.
3. Only after all checks pass does it create an update PR.

So, for GitHub-hosted plugins, just publish a new Release (with the plugin ZIP asset) and the market follows automatically — no manual catalog edits needed.

Local quick check for catalog ordering

node scripts/check-catalog-order.mjs