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

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

```kotlin build.gradle.kts theme={null}
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` |

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

## Bundle format

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

```text theme={null}
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`:

```kotlin theme={null}
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:

```text theme={null}
-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:

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

## AndroidManifest

Keep it minimal:

```xml theme={null}
<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:

```toml theme={null}
[versions]
klyx = "4.2.0-SNAPSHOT"
```

with corresponding `minAppVersion` in `plugin.json`:

```json theme={null}
"minAppVersion": "4.2.0"
```

## Publishing to the registry

Klyx hosts a community plugin registry at [github.com/klyx-dev/plugins](https://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](/extensions/plugin-manifest) for required fields)
2. You have built a `.klyx` bundle with `./gradlew klyxBundle`

### Publish via pull request

1. **Fork** the [registry repo](https://github.com/klyx-dev/plugins/fork)
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

```text theme={null}
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.