Quickstart

Build and run your first Klyx extension

This guide walks you through creating a minimal Klyx extension from scratch. You will set up a project, implement the plugin using @PluginManifest, and bundle it into a .klyx file.

Prerequisites

• Android Studio (latest stable)
• A Klyx-compatible device or emulator running Klyx 4.2.0 or later
• Basic knowledge of Kotlin and Jetpack Compose
• Kotlin 2.1 or later (for context receivers support)

1. Create the project

Create a new Android project in Android Studio with No Activity. Use minimum SDK 28 and Kotlin.

Your project structure should look like this:

my-extension/
├── app/
│   ├── build.gradle.kts
│   └── src/main/
│       ├── AndroidManifest.xml
│       └── java/com/yourext/
│           └── MyExtension.kt
├── build.gradle.kts
├── settings.gradle.kts
└── gradle/
    └── libs.versions.toml

Note that there is no plugin.json file — the @PluginManifest annotation generates it for you at compile time.

2. Configure the version catalog

In gradle/libs.versions.toml:

[versions]
klyx = "4.2.0-SNAPSHOT"

[plugins]
klyx = { id = "io.github.klyx-dev.compiler.plugin", version.ref = "klyx" }

The klyx plugin provides Kotlin, AGP, and Compose automatically — you do not need to add them yourself.

3. Set up the root build file

In build.gradle.kts:

plugins {
    alias(libs.plugins.klyx) apply false
}

4. Configure the app module

In app/build.gradle.kts:

plugins {
    alias(libs.plugins.klyx)
}

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

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

5. Write the Android manifest

In app/src/main/AndroidManifest.xml:

<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.

6. Implement the plugin

In app/src/main/java/com/yourext/MyExtension.kt:

package com.yourext

import androidx.compose.material3.Text
import com.klyx.api.plugin.KlyxPlugin
import com.klyx.api.plugin.PluginManifest
import com.klyx.api.plugin.PluginInfo
import com.klyx.api.plugin.runtime
import com.klyx.api.ui.Screen
import com.klyx.api.ui.ScreenId
import com.klyx.api.ui.ScreenRegistry
import com.klyx.api.service.plugin

@PluginManifest(
    id = "com.yourext.helloworld",
    version = "1.0.0",
    name = "Hello World",
    minAppVersion = "4.2.0",
    description = "My first Klyx extension",
    author = Author(name = "Your Name"),
    license = "MIT"
)
class MyExtension : KlyxPlugin {

    private val screens: ScreenRegistry by plugin()
    private val info: PluginInfo by runtime()

    override suspend fun onLoad() {
        screens.register(Screen(ScreenId("hello.main")) {
            Text("Hello from ${info.descriptor.name}!")
        })
    }

    override suspend fun onStart() {}

    override suspend fun onStop() {}

    override suspend fun onUnload() {
        screens.unregister(ScreenId("hello.main"))
    }
}

Notice how screens.register(...) does not require passing this. Registration methods use Kotlin context receivers — the compiler infers the plugin from the surrounding KlyxPlugin context.

7. Build the bundle

Run the Gradle task:

./gradlew klyxBundleDebug

This produces output/MyExtension.klyx — a gzipped tarball containing your APK and the generated plugin.json.

8. Install on Klyx

Transfer the .klyx file to your device and open it with Klyx. Klyx extracts the bundle, reads plugin.json, loads the APK, instantiates your entryClass, and calls onLoad() followed by onStart().

Next steps

Plugin Manifest Reference

Full reference for the @PluginManifest annotation

Plugin Lifecycle

Understand load, start, stop, and unload

Building & Bundling

Package and publish your extension