Building & Bundling

How to build, bundle, and distribute Klyx extensions

Klyx extensions are built using the Klyx Gradle plugin, which packages your APK and metadata into a .klyx bundle.

The Klyx Gradle plugin

Apply the io.github.klyx-dev.plugin plugin in your app/build.gradle.kts:

build.gradle.kts

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.klyx)
}

klyx {
    enableCompose()
    outputDirectory = rootProject.file("output")
}

Configuration options

Option	Description
enableCompose()	Applies the Compose compiler plugin and enables buildFeatures.compose
outputDirectory	Where to output the .klyx bundle. Defaults to build/klyx
extraFiles	Additional files to include in the bundle

Auto-detected files

The plugin automatically detects and includes these files from the project root:

File	Purpose
plugin.json	Plugin manifest (required)
icon.png	Plugin icon shown in the plugin manager
readme.md	Displayed on the plugin details page
changelog.md	Version history

Build tasks

The plugin adds three Gradle tasks:

Task	Description
klyxBundleDebug	Build a debug bundle
klyxBundleRelease	Build a release bundle
klyxBundle	Alias for klyxBundleRelease

./gradlew klyxBundleDebug

Bundle format

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

MyExtension.klyx
├── plugin.apk       # Compiled extension (debug or release APK)
├── plugin.json      # Plugin manifest (copied from project root)
├── icon.png         # Plugin icon
├── readme.md        # Documentation
├── changelog.md     # Version history
└── [extra files]    # Anything configured via extraFiles

Entry	Required	Description
plugin.json	Yes	Plugin metadata
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

Dependencies

The klyx-api dependency must be compileOnly:

dependencies {
    compileOnly(libs.klyx.api)
}

Klyx provides the API at runtime. Using implementation would bundle the API into your APK and cause conflicts.

R8 / ProGuard

If you enable minification, you must keep your entry class:

-keep class com.yourext.MyExtension

The SamplePlugin ships a keepRules/rules.keep file that the klyx {} block picks up automatically. You can also put rules in consumer-rules.pro and reference them in your build file:

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "consumer-rules.pro"
            )
        }
    }
}

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 needed. The plugin entry point is declared in plugin.json.

Version compatibility

The minAppVersion in plugin.json should match the version of klyx-api you’re compiling against:

[versions]
klyx = "4.2.0-SNAPSHOT"

with corresponding minAppVersion in plugin.json:

"minAppVersion": "4.2.0"

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 plugin.json is valid (see manifest reference for required fields)
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’s 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: starts with a letter, contains only letters, digits, and dots, no slashes
• 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
• Ownership: You can only publish updates to a plugin you already own. First-time publishers are welcome for new plugin IDs

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. Clears the incoming/ directory

Registry structure

plugins/
  index.json                  # Auto-generated registry index
  com.klyx.sampleplugin/      # Plugin ID directory
    metadata.json              # Extracted plugin.json
    icon.png                   # Extracted plugin icon
    readme.md                  # Extracted readme
    changelog.md               # Extracted changelog
    1.0.0.klyx                 # Versioned bundle file
    1.1.0.klyx                 # Updated version
incoming/                      # Drop .klyx files here (via PR)

Ownership

When you first publish a plugin, you become its owner. 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.