Building & Bundling

How to build, bundle, and distribute Klyx extensions

Klyx extensions are built using the Klyx Gradle plugin, which packages your APK and generated manifest into a .klyx bundle (a gzipped tarball).

The Klyx Gradle plugin

Apply the plugin in your app/build.gradle.kts:

plugins {
    alias(libs.plugins.klyx)
}

android {
    namespace = "com.yourext"
    compileSdk = 37
}

klyx {
    outputDirectory.set(rootProject.file("output"))
}

The Klyx Gradle plugin (io.github.klyx-dev.compiler.plugin) does several things:

• Applies the Kotlin compiler plugin that processes @PluginManifest
• Auto-detects icon.png, readme.md, and changelog.md from the project root
• Applies the Android Application or Library plugin automatically
• Enables Jetpack Compose if the compose option is set (enabled by default)
• Adds klyx-api as a compileOnly dependency automatically
• Sets minSdk to 28, Java 21 compatibility, and buildFeatures.compose = true

You do not need to apply com.android.application, kotlin.compose, or kotlin.serialization yourself — the klyx plugin handles all of that.

Configuration options

All options are available on the klyx { } extension block:

Option	Type	Default	Description
pluginJsonFile	RegularFileProperty	build/klyx/generated/plugin.json	Path to the generated descriptor JSON
icon	RegularFileProperty	Auto-detected	Plugin icon file
readme	RegularFileProperty	Auto-detected	Readme displayed on the plugin details page
changelog	RegularFileProperty	Auto-detected	Version history
extraFiles	ConfigurableFileCollection	Empty	Additional files to pack into the bundle
outputFileName	Property<String>	Project name	Name of the output bundle (without extension)
outputDirectory	DirectoryProperty	build/klyx	Where to output the .klyx bundle
autoPushToDevice	Property<Boolean>	false	Whether to auto-push to a connected device via adb
library	Property<Boolean>	false	Whether to build as a library instead of an application
compose	Property<Boolean>	true	Whether to enable Jetpack Compose

Auto-detected files

The plugin automatically detects and includes these files from the project root if you do not specify them explicitly:

File	Purpose
plugin.json	Generated by the compiler plugin (required — do not hand-author)
icon.png / icon.jpg	Plugin icon shown in the plugin manager
readme.md	Displayed on the plugin details page
changelog.md	Version history

Build tasks

The plugin adds several Gradle tasks:

Task	Description
klyxBundleDebug	Build a debug .klyx bundle
klyxBundleRelease	Build a release .klyx bundle
klyxBundle	Build the release bundle (alias for klyxBundleRelease)
klyxPushDebug	Push the debug bundle to a connected device
klyxPushRelease	Push the release bundle to a connected device

The push tasks run automatically after bundling when autoPushToDevice is true:

./gradlew klyxBundleDebug

This produces output/MyExtension.klyx.

Bundle format

The task produces a .klyx file — a gzipped tarball containing:

MyExtension.klyx
├── plugin.apk       -- Compiled extension (debug or release APK)
├── plugin.json      -- Generated plugin descriptor
├── icon.png         -- Plugin icon (if present)
├── readme.md        -- Documentation (if present)
├── changelog.md     -- Version history (if present)
└── [extra files]    -- Anything configured via extraFiles

Entry	Required	Description
plugin.json	Yes	Generated by the @PluginManifest compiler plugin
plugin.apk	Yes	The compiled APK
icon.png	No	Store icon (512x512 recommended)
readme.md	No	Plugin description and docs
changelog.md	No	Version changelog

Android Studio IDE support

For the best plugin development experience, enable the klyx compiler plugin in Android Studio so you get IDE features like code completion and navigation for Klyx APIs.

Go to Menu > Help > Edit Custom Properties… and add this line to the idea.properties file:

kotlin.k2.only.bundled.compiler.plugins.enabled=false

Restart Android Studio after making this change.

R8 / ProGuard

If you enable minification, keep your entry class:

-keep class com.myext.MyExtension { *; }

The @PluginManifest annotation ensures the entry class name is generated into plugin.json. However, if R8 renames or removes the class, Klyx will not be able to load it reflectively. Make sure to add a keep rule.

AndroidManifest

Keep it minimal:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <application tools:ignore="MissingApplicationIcon" />
</manifest>

No activities, services, or providers are needed. The plugin entry point is declared via the @PluginManifest annotation, not the manifest.

Version compatibility

The minAppVersion in your @PluginManifest annotation should match the version of klyx-api you are compiling against. For example, if your build.gradle.kts uses a version catalog:

[versions]
klyx = "4.2.0-SNAPSHOT"

then set minAppVersion = "4.2.0" in the @PluginManifest.

Publishing to the registry

Klyx hosts a community plugin registry at github.com/klyx-dev/plugins. Publishing is done through a pull request — CI validates your bundle and publishes it automatically on merge.

Prerequisites

1. Your @PluginManifest annotation is valid (see manifest reference for validation rules)
2. You have built a .klyx bundle with ./gradlew klyxBundle

Publish via pull request

1. Fork the registry repo
2. Add your .klyx file to the incoming/ directory
3. Create a pull request to main
4. Wait for CI — the workflow validates your bundle and posts results as a PR comment
5. Merge once validation passes — your plugin is published automatically

What CI validates

The registry CI pipeline checks:

• plugin.json exists and is valid JSON
• All required fields are present and non-empty: id, version, name, minAppVersion, entryClass
• id matches the format: reverse-DNS (e.g. com.example.myplugin)
• version follows semver (e.g. 1.0.0)
• minAppVersion and maxAppVersion follow semver
• entryClass is a valid fully-qualified class name
• author.name is present if author is an object
• plugin.apk exists in the bundle

After publishing

The publish workflow:

1. Creates a directory under plugins/{plugin-id}/ with all versioned bundles and extracted metadata
2. Updates plugins/index.json — the auto-generated registry index
3. Purges the jsDelivr CDN cache so users see the latest version
4. Clears the incoming/ directory

Ownership

When you first publish a plugin, you become its owner. The registry tracks ownership through a Cloudflare Worker at plugins.klyx.workers.dev. Only the registered owner can publish updates to that plugin ID. This prevents namespace squatting and unauthorized updates.

Manual distribution

You can also share .klyx files directly with users. They can open the file with Klyx to install the extension.