Skip to main content
Frequently asked questions about Compose Hot Reload and their answers.

​
Platform support

Compose Hot Reload is designed to work with Compose Multiplatform. To use Compose Hot Reload with an Android-only project, you need to:
  1. Switch from the Jetpack Compose plugin to the Compose Multiplatform plugin.
  2. Add a separate Gradle module and configure the JVM target.
While this requires some restructuring, it allows you to take advantage of Compose Hot Reload’s features.
Yes! Compose Hot Reload fully supports desktop-only Compose Multiplatform applications.However, be aware that you cannot start the application via the run button in the gutter (CMP-3123). Instead, use Gradle tasks from the command line:
./gradlew :app:hotRunJvm
Compose Hot Reload requires a JVM target in your multiplatform project. Support for other targets (iOS, Web, etc.) is being explored for the future, but is not currently available.Your project can have multiple targets, but hot reload will only work with the JVM target.

​
Usage and workflow

Compose Hot Reload supports two reload modes:
  • Explicit mode (default): You manually trigger the reload after making changes by pressing the assigned shortcut key or clicking the Reload UI button.
  • Auto mode: Compose Hot Reload uses Gradle’s file-watching and continuous build system to automatically reload when file changes are detected.
To enable auto mode, add the --autoReload or --auto flag:
./gradlew :app:hotRunJvm --autoReload
You can also configure the trigger behavior in Settings | Tools | Compose Hot Reload in your IDE.
The Kotlin Multiplatform IDE plugin currently supports only a single Compose Hot Reload connection at a time. If you try to simultaneously run multiple Compose applications within the same IDE instance, you may experience unexpected shutdowns.Recommended approach:
  • Run only one application in hot reload mode from the IDE
  • Run other applications from the command line without hot reload
See the known limitations for more details.
Compose Hot Reload aims to support most code changes, including:
  • UI composable functions
  • Layout and styling changes
  • Business logic within composables
  • Resource changes
However, some changes require a full restart:
  • Changes to global state (unless manually handled)
  • Changes to application initialization code
  • Adding or removing dependencies
  • Build configuration changes
See the global state limitations for more information.
If the dev tools window is causing issues or you don’t need it, you can disable it in several ways:
  1. Headless mode (keeps functionality, hides UI): 
    ./gradlew :app:hotRunJvm -Dcompose.reload.devToolsHeadless=true
  2. Detached mode (separate window, no snapping): 
    ./gradlew :app:hotRunJvm -Dcompose.reload.devToolsDetached=true
  3. Completely disabled (may limit functionality): 
    ./gradlew :app:hotRunJvm -Dcompose.reload.devToolsEnabled=false

​
Configuration

If you define a custom JVM target name, Gradle uses a different task name. For example, if your target name is desktop:
kotlin {
    jvm("desktop")
}
The task name becomes :hotRunDesktop instead of :hotRunJvm.
You can configure the main class in your build script instead of passing it as a command-line argument.Option 1: In the Compose Hot Reload task
tasks.withType<ComposeHotRun>().configureEach {
    mainClass.set("com.example.MainKt")
}
Option 2: In the Compose Multiplatform application block
compose.desktop {
    application {
        mainClass = "com.example.MainKt"
    }
}
Yes! If you want to try the latest changes in Compose Hot Reload, you can use dev builds.Add the firework Maven repository in your settings.gradle.kts file:
pluginManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/firework/dev")
    }
}

dependencyResolutionManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/firework/dev")
    }
}
Dev builds are unstable and may contain bugs. Use them only for testing the latest features.

​
Troubleshooting

The dev tooling window snapping to your main application window can cause unusual behavior on some window managers.Solutions:
  1. Run in detached mode: -Dcompose.reload.devToolsDetached=true
  2. Run in headless mode: -Dcompose.reload.devToolsHeadless=true
  3. Disable dev tools: -Dcompose.reload.devToolsEnabled=false
See window behavior issues for more details.
ViewModels persist their state through UI changes, which can cause issues with hot reload. You need to manually reset the ViewModel state after hot reload.Add the hot reload runtime API dependency:
implementation("org.jetbrains.compose.hot-reload:hot-reload-runtime-api:*latest version*")
Then reset the ViewModel store:
if (isHotReloadActive) {
  val viewModelStoreOwner = LocalViewModelStoreOwner.current
  staticHotReloadScope.invokeAfterHotReload {
    viewModelStoreOwner?.viewModelStore?.clear()
  }
}
See ViewModel support for more information.
Compose Hot Reload relies on Gradle File System Watching, which does not currently support ReFS (Windows Dev Drive file system).Solution: Move your project to an NTFS-formatted drive.See Windows Dev Drive incompatibility for more details.
To get more information about what Compose Hot Reload is doing:
./gradlew :app:hotRunJvm --debug
Or set the Gradle logging level in gradle.properties:
org.gradle.logging.level=debug

​
Support and community

If you encounter a bug or issue with Compose Hot Reload:
  1. Check the known limitations page
  2. Search existing issues on GitHub
  3. If your issue is not listed, report a new issue in the CMP tracker
When reporting an issue, include:
  • Compose Hot Reload version
  • Kotlin version
  • Compose Multiplatform version
  • Operating system
  • Steps to reproduce
  • Error messages or logs
You can ask questions and get help from the community in several places:
Compose Hot Reload is an open-source project, and contributions are welcome!Check the contribution guidelines for more information.
Official documentation for Compose Hot Reload is available at:

Build docs developers (and LLMs) love

Get started for freeTalk to us