Installation

CStories is published to GitHub Packages.

1. Create a GitHub token

GitHub Packages requires authentication, even to download public packages. Create a personal access token (classic) with the read:packages scope, then add it to ~/.gradle/gradle.properties:

gpr.user=<your-github-username>
gpr.token=<your-token>

2. Declare the GitHub Packages repository in the consumer project

In the settings.gradle.kts of the project that will use CStories, add the repository to both repository blocks:

pluginManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/mplessis/CStories")
            credentials {
                username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR")
                password = providers.gradleProperty("gpr.token").orNull ?: System.getenv("GITHUB_TOKEN")
            }
        }
        gradlePluginPortal()
        mavenCentral()
        google()
    }
}

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/mplessis/CStories")
            credentials {
                username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR")
                password = providers.gradleProperty("gpr.token").orNull ?: System.getenv("GITHUB_TOKEN")
            }
        }
        mavenCentral()
        google()
    }
}

These are two separate repository blocks: pluginManagement resolves the plugin itself, while dependencyResolutionManagement resolves the actual dev.cstories:* library artifacts. Missing either one causes resolution errors.

Local development

To try unreleased changes, run ./gradlew publishAllToMavenLocal from the CStories repository and add mavenLocal() first in both blocks instead. See Local publishing.

3. Apply the CStories plugin

In the module that will host your stories:

If the project is a reusable library, this must be a dedicated stories module. Do not apply the plugin to the published component library itself, because it adds cstories-runtime and catalog dependencies to that module. See Structure a multi-module project.

plugins {
    kotlin("multiplatform") version "<kotlin-version>"
    id("org.jetbrains.compose") version "<compose-version>"
    id("org.jetbrains.kotlin.plugin.compose") version "<kotlin-version>"
    id("dev.cstories.gradle") version "<version>"
}

kotlin {
    jvm()
}

Replace the placeholders with:

• <version>: the CStories version you published, defined by cstoriesVersion in the CStories repository's gradle.properties;
• <kotlin-version> and <compose-version>: the Kotlin and Compose Multiplatform versions matching that CStories version (see the table below). The Compose compiler plugin (org.jetbrains.kotlin.plugin.compose) always uses the same version as Kotlin.

CStories	Kotlin (<kotlin-version>)	Compose Multiplatform (<compose-version>)
2.0.5	2.4.21	1.12.2
2.0.4	2.4.21	1.12.2
2.0.3	2.4.21	1.12.2
2.0.2	2.4.21	1.12.2
2.0.1	2.4.21	1.12.2
2.0.0	2.4.21	1.12.2
1.x	2.2.0	1.8.2

CStories artifacts are compiled with these versions: use at least the same ones in your project. Since CStories 2.0.0, the iosX64 target is no longer published, as Compose Multiplatform 1.11+ no longer supports it.

Compose compiler plugin

The CStories plugin applies org.jetbrains.kotlin.plugin.compose, but does not bundle it. If this plugin is not already declared in the module (directly, or through a convention plugin), declare it yourself in the plugins {} block, with the same version as your Kotlin plugin. Otherwise the build fails with Plugin with id 'org.jetbrains.kotlin.plugin.compose' not found.

For a first use, the recommended path is to start with the jvm() target only, in order to run the catalog as a desktop application. Applying the plugin with no target declared fails fast with a clear error instead of silently forcing one.

4. Run the catalog

./gradlew runCStoriesDesktop

If the module also declares a wasmJs target, the catalog can also be launched in the browser:

./gradlew runCStoriesWasm

Next: Create your first story.