> ## Documentation Index
> Fetch the complete documentation index at: https://klyx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build and run your first Klyx extension

This guide walks you through creating a minimal Klyx extension from scratch. You'll set up a project, implement the plugin interface, and bundle it into a `.klyx` file.

## Prerequisites

* A Klyx-compatible device or emulator running Klyx 4.2.0+
* Basic knowledge of [Kotlin](https://kotlinlang.org/docs/home.html) and [Jetpack Compose](https://developer.android.com/compose)

## 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:

```text theme={null}
my-extension/
├── app/
│   ├── build.gradle.kts
│   └── src/main/
│       ├── AndroidManifest.xml
│       └── java/com/myextension/
│           └── MyPlugin.kt
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── gradle/
│   └── libs.versions.toml
└── plugin.json
```

## Configure the version catalog

In `gradle/libs.versions.toml`:

```toml libs.versions.toml lines theme={null}
[versions]
# agp and kotlin version must match with klyx app's agp and kotlin version
agp = "9.2.1"
kotlin = "2.4.0"
klyx = "4.2.0-SNAPSHOT"

[libraries]
klyx-api = { module = "io.github.klyx-dev:klyx-api", version.ref = "klyx" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
klyx = { id = "io.github.klyx-dev.plugin", version.ref = "klyx" }
```

## 3. Set up the root build file

In `build.gradle.kts`:

```kotlin build.gradle.kts lines theme={null}
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.serialization) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.klyx) apply false
}
```

## Configure the app module

In `app/build.gradle.kts`:

```kotlin build.gradle.kts lines theme={null}
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.klyx)
}

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

android {
    namespace = "com.myextension"
}

dependencies {
    compileOnly(libs.klyx.api)
}
```

<Tip>
  The `klyx-api` dependency uses `compileOnly` because Klyx provides the API at runtime. Don't use `implementation`.
</Tip>

## Write the Android manifest

In `app/src/main/AndroidManifest.xml`:

```xml AndroidManifest.xml lines theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <application tools:ignore="MissingApplicationIcon" />
</manifest>
```

## Create plugin.json

In `plugin.json` (at the project root):

```json plugin.json lines theme={null}
{
  "id": "com.myextension.helloworld",
  "name": "Hello World",
  "version": "1.0.0",
  "minAppVersion": "4.2.0",
  "entryClass": "com.myextension.MyPlugin",
  "description": "My first Klyx extension",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT",
  "permissions": []
}
```

## Implement the plugin

In `app/src/main/java/com/myextension/MyPlugin.kt`:

```kotlin MyPlugin.kt lines theme={null}
package com.myextension

import androidx.compose.material3.Text
import com.klyx.api.plugin.KlyxPlugin
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

class MyPlugin : KlyxPlugin {

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

    override suspend fun onLoad() {
        screens.register(
            this,
            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"))
    }
}
```

## Build the bundle

Run the Gradle task:

```bash theme={null}
./gradlew klyxBundleDebug
```

This produces `output/my-extension.klyx` — a bundle containing your APK, plugin.json, and any assets.

## Install on Klyx

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

Navigate to your screen from within Klyx's navigation.

## Next steps

<Card title="Plugin Manifest Reference" icon="file-lines" href="/extensions/plugin-manifest">
  Full reference for plugin.json fields
</Card>

<Card title="Plugin Lifecycle" icon="arrows-rotate" href="/extensions/plugin-lifecycle">
  Understand load, start, stop, and unload
</Card>