Installation - Compose Hot Reload

This guide covers everything you need to know about installing and configuring Compose Hot Reload in both new and existing projects.

Prerequisites

Ensure your project meets these minimum version requirements:

Kotlin

Version 2.1.20 or higher

Compose Compiler

Version 2.1.20 or higher

Compose Multiplatform

Version 1.8.2 or higher

Java Target

Java 21 or earlier (for JetBrains Runtime compatibility)

To be compatible with JetBrains Runtime, your project must target Java 21 or earlier.

Recommended IDE Setup

For the best development experience:

IntelliJ IDEA 2025.2.2 or higher, or Android Studio Otter 2025.2.1 or higher
Kotlin Multiplatform IDE plugin installed

Installation Methods

There are two ways to set up Compose Hot Reload:

New Project

Create a project with hot reload from the start

Existing Project

Add hot reload to your current project

New Project from Scratch

Create a new project

Follow the Kotlin Multiplatform quickstart guide to set up your environment and create a project.

Be sure to select the desktop target when creating the project, as Compose Hot Reload requires a JVM target.

Configure the hot reload plugin

Once your project is created, follow the steps in Add to Existing Project to enable hot reload.

Add to Existing Project

Step 1: Update Version Catalog

Add the Compose Hot Reload plugin to your version catalog in gradle/libs.versions.toml:

gradle/libs.versions.toml

[versions]
composeHotReload = "1.1.0"

[plugins]
composeHotReload = { id = "org.jetbrains.compose.hot-reload", version.ref = "composeHotReload" }

If you don’t use a version catalog, you can specify the plugin version directly in your build files.

Step 2: Apply to Parent Project

In your parent project’s build.gradle.kts, add the plugin with apply false to prevent it from being loaded multiple times in subprojects:

build.gradle.kts

plugins {
    kotlin("multiplatform") apply false
    kotlin("plugin.compose") apply false
    id("org.jetbrains.compose") apply false
    alias(libs.plugins.composeHotReload) apply false
}

Step 3: Enable in Application Module

In the build.gradle.kts of your application subproject, apply the hot reload plugin:

plugins {
    kotlin("multiplatform")
    kotlin("plugin.compose")
    id("org.jetbrains.compose")
    id("org.jetbrains.compose.hot-reload")
}

compose.desktop {
    application {
        mainClass = "com.example.MainKt"
    }
}

kotlin {
    jvm()
    jvmToolchain(21)

    sourceSets.commonMain.dependencies {
        implementation(compose.desktop.currentOs)
        implementation(compose.foundation)
        implementation(compose.material3)
    }
}

Step 4: Configure Main Class

You can configure the main class in two ways:

Compose Desktop Block (Recommended)
Hot Reload Task
Command Line Argument

build.gradle.kts

compose.desktop {
    application {
        mainClass = "com.example.MainKt"
    }
}

build.gradle.kts

tasks.withType<ComposeHotRun>().configureEach {
    mainClass.set("com.example.MainKt")
}

./gradlew :app:hotRunJvm --mainClass com.example.MainKt

Step 5: Sync Gradle

Click the Sync Gradle Changes button in your IDE to synchronize the configuration.

JetBrains Runtime Provisioning

An installation of the JetBrains Runtime (JBR) is required to run Compose Hot Reload. There are three ways to provide it:

Option 1: IDE Plugin (Recommended)

Install the Kotlin Multiplatform plugin

Install the Kotlin Multiplatform IDE plugin in IntelliJ IDEA or Android Studio.

Run from IDE

When launching Compose Hot Reload from the IDE, it will automatically reuse IntelliJ’s installation of the JetBrains Runtime.

Option 2: Gradle Toolchain Resolution

Configure Gradle to automatically download the JetBrains Runtime by adding the Foojay resolver to your settings.gradle.kts:

settings.gradle.kts

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

This allows Gradle to download and manage the appropriate JDK toolchain automatically.

Option 3: Automatic JBR Provisioning (Experimental)

Automatic JetBrains Runtime provisioning is an experimental feature. Please report any issues you encounter.

Enable automatic provisioning by setting the property in your gradle.properties:

gradle.properties

compose.reload.jbr.autoProvisioningEnabled=true

Or pass it as a command-line argument:

./gradlew :app:hotRunJvm -Pcompose.reload.jbr.autoProvisioningEnabled=true

Custom JVM Target Names

If you define a custom JVM target name in your Kotlin configuration, the hot reload task names will reflect that:

build.gradle.kts

kotlin {
    jvm("desktop")
}

The corresponding hot reload tasks will be:

:hotRunDesktop (instead of :hotRunJvm)
:hotRunDesktopAsync

Available Gradle Tasks

The Compose Hot Reload plugin automatically creates the following tasks:

Run Tasks

Multiplatform Projects

:hotRunJvm - Run with hot reload
:hotRunJvmAsync - Async variant

Kotlin/JVM Projects

:hotRun - Run with hot reload
:hotRunAsync - Async variant

Reload Tasks (Explicit Mode Only)

You cannot run reload tasks with the --autoReload or --auto command-line argument.

:reload - Reload all currently running applications
:hotReloadJvmMain - Reload applications using the jvmMain source set

Command-Line Arguments

All hot reload run tasks support these arguments:

Argument	Description	Example
`--mainClass <FQN>`	Specify the main class to run	`./gradlew :app:hotRunJvm --mainClass com.example.MainKt`
`--autoReload` / `--auto`	Enable automatic reloading on file changes	`./gradlew :app:hotRunJvm --autoReload`
`--no-autoReload` / `--no-auto`	Disable automatic reloading	`./gradlew :app:hotRunJvm --no-auto`

Using Developer Builds

To try the latest changes in Compose Hot Reload before they’re officially released, you can use dev builds:

settings.gradle.kts

pluginManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/firework/dev")
        gradlePluginPortal()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/firework/dev")
        mavenCentral()
        google()
    }
}

Then use the dev version in your version catalog or plugin declaration.

Multi-Module Projects

Compose Hot Reload works seamlessly across project modules:

Apply plugin to each module

Apply the hot reload plugin to each module that contains reloadable code:

widgets/build.gradle.kts

plugins {
    kotlin("multiplatform")
    kotlin("plugin.compose")
    id("org.jetbrains.compose")
    id("org.jetbrains.compose.hot-reload")
}

kotlin {
    jvm()
    jvmToolchain(21)

    sourceSets.jvmMain.dependencies {
        implementation(compose.foundation)
        implementation(compose.material3)
    }
}

Include in settings

Ensure all modules are included in your settings.gradle.kts:

settings.gradle.kts

include(":app")
include(":widgets")

Add module dependencies

Reference the module in your app’s dependencies:

app/build.gradle.kts

kotlin {
    sourceSets.commonMain.dependencies {
        implementation(project(":widgets"))
    }
}

Changes to any module will trigger hot reload automatically!

IDE Configuration

Run Configuration Setup

If you don’t have the Kotlin Multiplatform IDE plugin installed, you can manually create Gradle run configurations:

Open Run Configuration dialog

Navigate to Run → Edit Configurations in your IDE menu.

Add new Gradle configuration

Click the + button and select Gradle.

Configure task

Tasks: :app:hotRunJvm
Arguments: --autoReload (optional)

Save and run

Click OK and run your configuration.

Customize Reload Trigger

You can modify the reload trigger behavior in Settings | Tools | Compose Hot Reload.

Troubleshooting

JetBrains Runtime not found

Solutions:

Install the Kotlin Multiplatform IDE plugin
Add the Foojay resolver to settings.gradle.kts
Enable experimental auto-provisioning with the compose.reload.jbr.autoProvisioningEnabled property

Task names don't match documentation

If you’re using a custom JVM target name, the task names will differ:

kotlin {
    jvm("desktop") // Creates :hotRunDesktop instead of :hotRunJvm
}

Plugin applied multiple times

Make sure you use apply false in the parent project:

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

Android-only project compatibility

Compose Hot Reload is designed for Compose Multiplatform. For Android-only projects:

Switch from the Jetpack Compose plugin to the Compose Multiplatform plugin
Add a separate Gradle module with a JVM target
Configure hot reload in that module

Desktop-only app without IDE run button

For desktop-only Compose Multiplatform apps, you may not be able to start the application via the IDE gutter run button (CMP-3123).Workaround: Use Gradle tasks directly:

./gradlew :app:hotRunJvm

Get Started

Core Concepts

Usage

Advanced

Troubleshooting

​Prerequisites

Kotlin

Compose Compiler

Compose Multiplatform

Java Target

​Recommended IDE Setup

​Installation Methods

New Project

Existing Project

​New Project from Scratch

​Add to Existing Project

​Step 1: Update Version Catalog

​Step 2: Apply to Parent Project

​Step 3: Enable in Application Module

​Step 4: Configure Main Class

​Step 5: Sync Gradle

​JetBrains Runtime Provisioning

​Option 1: IDE Plugin (Recommended)

​Option 2: Gradle Toolchain Resolution

​Option 3: Automatic JBR Provisioning (Experimental)

​Custom JVM Target Names

​Available Gradle Tasks

​Run Tasks

Multiplatform Projects

Kotlin/JVM Projects

​Reload Tasks (Explicit Mode Only)

​Command-Line Arguments

​Using Developer Builds

​Multi-Module Projects

​IDE Configuration

​Run Configuration Setup

​Customize Reload Trigger

​Troubleshooting

​Next Steps

Quickstart Guide

Report Issues

Build docs developers (and LLMs) love

Prerequisites

Recommended IDE Setup

Installation Methods

New Project from Scratch

Add to Existing Project

Step 1: Update Version Catalog

Step 2: Apply to Parent Project

Step 3: Enable in Application Module

Step 4: Configure Main Class

Step 5: Sync Gradle

JetBrains Runtime Provisioning

Option 1: IDE Plugin (Recommended)

Option 2: Gradle Toolchain Resolution

Option 3: Automatic JBR Provisioning (Experimental)

Custom JVM Target Names

Available Gradle Tasks

Run Tasks

Reload Tasks (Explicit Mode Only)

Command-Line Arguments

Using Developer Builds

Multi-Module Projects

IDE Configuration

Run Configuration Setup

Customize Reload Trigger

Troubleshooting

Next Steps