Plugin Manifest

Reference for the @PluginManifest annotation

Every Klyx extension must declare a plugin entry class annotated with @PluginManifest. The Klyx Kotlin compiler plugin reads this annotation at compile time, validates it, and generates the plugin.json descriptor and a PluginDescriptor companion property for you automatically.

You never hand-author plugin.json — it is generated from the annotation.

Declaration

Annotate your KlyxPlugin implementation class:

package com.myext

@PluginManifest(
    id = "com.myext.helloworld",
    version = "1.0.0",
    name = "Hello World",
    minAppVersion = "4.2.0",
    description = "A minimal Klyx extension",
    author = Author(name = "Your Name"),
    license = "MIT",
    links = Links(
        source = "https://github.com/you/my-extension",
        issues = "https://github.com/you/my-extension/issues"
    ),
    permissions = []
)
class MyExtension : KlyxPlugin {
    override suspend fun onLoad() { /* ... */ }
    override suspend fun onStart() { /* ... */ }
    override suspend fun onStop() { /* ... */ }
    override suspend fun onUnload() { /* ... */ }
}

Author annotation

The Author annotation provides information about the plugin’s author:

@Author(
    name = "Your Name",
    email = "[e-mail]",
    url = "https://example.com",
    github = "yourhandle"
)

Links annotation

The Links annotation provides useful links associated with the extension:

@Links(
    source = "https://github.com/you/my-extension",
    issues = "https://github.com/you/my-extension/issues",
    website = "https://example.com",
    donate = "https://ko-fi.com/you"
)

Field reference

id (required)

Unique plugin identifier in reverse-DNS notation. Must match the regex pattern of lowercase letters, digits, dots, and hyphens, starting with a letter.

"com.myext.helloworld"

version (default: "0.1.0")

Semantic version string. Klyx uses this to determine if an update is available.

"1.0.0"

name (default: "<auto>", falls back to id)

Human-readable display name shown in Klyx’s plugin manager. If left blank or set to "<auto>", it defaults to the id.

"Hello World"

minAppVersion (default: "4.2.0")

The minimum version of Klyx required to run this extension. Must be a valid semver string. Version 4.2.0 introduced the plugin system.

"4.2.0"

maxAppVersion (default: "", meaning no upper limit)

If set, the extension will not load on newer versions of Klyx. Use this when a Klyx major version breaks your extension’s API. Must be a valid semver string if non-empty.

"5.0.0"

description (default: "")

A short description of what the extension does.

"Adds custom features to Klyx"

icon (default: "")

Path (relative to the project root) to the plugin’s icon file. The Gradle plugin can auto-detect icon.png or icon.jpg from the project root if this is left blank.

"icon.png"

license (default: "")

SPDX license identifier or a short license name.

"MIT"

author (default: Author(name = ""))

Information about the extension author. See the Author annotation above. The name field is required if the author annotation is present.

links (default: Links())

Useful links related to the extension. See the Links annotation above. All fields are optional.

permissions (default: [])

A list of permission strings the extension requires. Currently reserved for future use.

["terminal", "network"]

Compile-time validation

The Klyx compiler plugin validates the @PluginManifest annotation at compile time and reports errors as compile errors (not runtime failures). It checks:

Rule	Details
Plugin ID format	Must match reverse-DNS pattern (e.g. com.example.git-tools)
Version format	Must be valid semver (e.g. 1.0.0)
minAppVersion	Must be valid semver
maxAppVersion	If set, must be valid semver
min/max order	minAppVersion must not be greater than maxAppVersion
Annotation target	Must be on a class, not a function or property
KlyxPlugin	The annotated class must implement KlyxPlugin
Constructor	Must have a public no-argument constructor
Class modifiers	Must not be abstract, inner, or local
Duplicate	Only one class per module can be annotated
descriptor property	The name descriptor is reserved on the companion object

Generated artifacts

After compilation, the following is generated in build/klyx/generated/:

1. plugin.json — A JSON file consumed by the Klyx Gradle plugin when assembling the .klyx bundle
2. PluginDescriptor companion property — Accessible as MyExtension.descriptor, this is a PluginDescriptor instance that the PluginManager can read at runtime for integrity verification. The compiled descriptor is compared against the plugin.json from the bundle to detect tampering or corruption.

Example

Here is an example of using @PluginManifest on a plugin entry class:

@PluginManifest(
    id = "com.example.myplugin",
    version = "1.0.0",
    name = "My Plugin",
    minAppVersion = "4.2.0",
    description = "A comprehensive reference implementation demonstrating all Klyx extension APIs",
    author = Author(name = "Klyx"),
    license = "MIT",
    links = Links(
        source = "https://github.com/klyx-dev/my-plugin",
        issues = "https://github.com/klyx-dev/my-plugin/issues"
    ),
    permissions = []
)
class MyPlugin : KlyxPlugin { /* ... */ }