Compose Hot Reload for JVM Compose Multiplatform apps

Compose Hot Reload targets the JVM UI editing loop

Compose Hot Reload addresses a specific delay in Compose Multiplatform development: changing a UI and then restarting the application to inspect the result. The project is intended for developers building a Compose Multiplatform application with a JVM target, particularly desktop applications created through the Kotlin Multiplatform quickstart. It is not a general hot-swap solution for every kind of Kotlin application. The README explicitly says that Compose Hot Reload needs a JVM target and that support for other targets is still being explored.

The project works with the Kotlin compiler, Compose compiler, and Compose Multiplatform version as a coordinated toolchain. The documented minimums are Kotlin 2.1.20, Compose compiler 2.1.20, and Compose Multiplatform 1.8.2. Compose Hot Reload `1.2.0-alpha02` and later requires Compose Multiplatform `1.10.0+`. The available `v1.3.0-beta02` release is therefore not a generally applicable version for a project still using Compose Multiplatform 1.8.2 through 1.9.x.

JetBrains Runtime is the execution component that makes the reload cycle possible. Compatibility is not unrestricted. The JVM target must use Java 21 or earlier. This boundary matters for teams considering newer Java settings, because the README does not claim compatibility with a Java target above that limit.

Gradle tasks orchestrate the running JVM application

Based on the repository layout, Compose Hot Reload is split into Gradle integration, orchestration, runtime, agent, analysis, and development-tool modules. The user-facing plugin adds hot-run tasks to the project. The README identifies `:hotRunJvm` as the multiplatform launch task and `:hotRun` as the Kotlin/JVM launch task. Each also has an asynchronous counterpart, `:hotRunJvmAsync` and `:hotRunAsync`.

The application runs under JetBrains Runtime. When Auto mode is enabled, Gradle file watching and the continuous build system detect changed files and initiate a reload. Explicit mode instead waits for the developer to trigger the operation. In the IDE, the runtime presentation includes a Reload UI button, and a shortcut can also be assigned. Trigger behavior can be changed under Settings | Tools | Compose Hot Reload.

This mechanism is narrower than replacing the entire build or application process. The README specifically frames the result as UI code changes becoming visible without a restart. It does not document how application startup logic, external resources, native dependencies, or unrelated JVM classes behave after a reload. Code that keeps important state outside the running UI must not be assumed to reset or persist correctly.

Installing the Gradle plugin in an existing project

For an existing project, first declare the plugin in `gradle/libs.versions.toml`. This version-catalog entry gives the rest of the build one plugin version reference:

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

In the parent project's `build.gradle.kts`, apply the alias with `apply false`. The README says this prevents the plugin from being loaded multiple times across subprojects.

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

Apply the plugin in the subproject that contains the multiplatform application.

plugins { 
    alias(libs.plugins.composeHotReload)
}

After synchronizing Gradle changes, the application subproject should expose the hot-run tasks. If the project is created from scratch instead, the README directs developers to the Kotlin Multiplatform quickstart and requires selecting the desktop target. JetBrains Runtime must also be available. The Kotlin Multiplatform IDE plugin reuses IntelliJ's JetBrains Runtime installation when launching Compose Hot Reload.

For Gradle-managed provisioning, the documented `settings.gradle.kts` option is:

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

Alternatively, automatic provisioning can be enabled with `compose.reload.jbr.autoProvisioningEnabled`. The README labels automatic JetBrains Runtime provisioning experimental, so it should not be treated as equivalent to the ordinary IDE-managed runtime path.

Running the first hot reload session

The shortest documented first use is the CLI path. From the project root, run the task belonging to the application module. The README gives these alternatives:

./gradlew :app:hotRunJvm
# or
./gradlew :composeApp:hotRunJvm

Choose the module path that exists in the project. Once the application is running, save source files and Auto mode updates the UI. If Auto mode is not enabled, use the documented reload action instead.

In IntelliJ IDEA or Android Studio, click the Run icon beside the main function and select Run 'shared [jvm]' with Compose Hot Reload. Saving changes then triggers a reload according to the configured behavior. The recommended environment is IntelliJ IDEA 2025.2.2 or later, or Android Studio Otter 2025.2.1 or later, with the Kotlin Multiplatform IDE plugin installed.

Automatic mode can also be requested from the CLI or run configuration with `--autoReload` or `--auto`. The repository documentation does not give a separate first-use command for applying a plugin to a project, so the IDE run action or the generated Gradle task is the confirmed entry point.

Explicit reload avoids accidental UI updates

Compose Hot Reload provides two trigger models because developer preferences differ. Explicit mode gives control over when code changes are applied. This is useful when a save should not immediately change the running window, or when the developer wants to edit several related properties before checking the combined result. The Reload UI button and its configured shortcut provide the manual action documented by the README.

Auto mode delegates change detection to Gradle file watching and continuous builds. It removes the need to press the reload control after every save, which makes the feedback loop shorter during routine UI work. The trade-off is less explicit control over the moment at which the application changes. The IDE settings page can modify trigger behavior, but the README does not enumerate every setting exposed there.

Without the Kotlin Multiplatform IDE plugin, the README says a developer can manually create Gradle run configurations with hot reload tasks. In that setup, the Reload UI button or the `reload` Gradle task provides the trigger. This is a more manual IDE arrangement, whereas installing the plugin exposes the documented Run action directly from the main-function gutter.

JVM, runtime, and state limits define adoption boundaries

The clearest failure mode is selecting the project for a target or toolchain it does not support. Compose Hot Reload requires a JVM target, so an application built only for non-JVM targets cannot adopt the documented workflow. The project also has hard minimum versions and a Java 21 ceiling for compatibility with JetBrains Runtime. An upgrade to Kotlin or Compose Multiplatform may therefore be part of introducing the plugin, rather than an independent concern.

State handling is another boundary. The README demonstrates changes to UI code and calls the command a UI reload. It does not promise a full process replacement for every code path, nor does it document rollback to a previous class version. Developers should not assume that application startup code, initialization side effects, or data held by discarded objects will be reconstructed in the same way as they would be after a restart.

The plugin also adds build and runtime components. Auto provisioning can download or select JetBrains Runtime through Gradle, while an IDE launch may reuse the runtime installed with IntelliJ. That distinction changes who provides the runtime and where provisioning failures can occur. A team that cannot permit JetBrains Runtime in its development environment cannot use the documented setup as written.

Gradle restart workflows differ from live UI reload

The real alternative is the ordinary Gradle run and rerun workflow used when live reload is not available. A standard run task starts the application, and the developer stops or restarts that process after checking a change. Compose Hot Reload keeps the application active and applies UI code changes through its agent, runtime, analysis, and orchestration components. Gradle remains part of both approaches, but its role differs: it provisions or triggers a normal run in the conventional workflow, while its file watching and continuous build behavior drive automatic UI updates in Auto mode.

Compose Hot Reload is the better fit when the developer is iterating on Compose rendering and wants feedback after saving. The conventional Gradle workflow is the better fit when startup behavior must be repeated from a clean process or when the application cannot satisfy the JVM target, runtime, or version requirements. The README does not describe a fallback in which hot reload can repair an incompatible target, so this is a project-level choice rather than a per-save optimization for every build.

Release maturity and Apache-2.0 adoption costs

The repository is not archived, and its last push was on 2026-10-15. The latest listed release is `v1.3.0-beta02`, dated 2026-10-15, following `v1.3.0-beta01` and `v1.3.0-alpha02`. Those names identify beta and alpha release stages directly. They do not by themselves guarantee compatibility with every project, so upgrades should be checked against the README's minimum Compose Multiplatform requirement.

The repository is licensed under Apache-2.0, with `LICENSE.txt` recorded as the license file. That identifier defines the project's published license terms, while integration teams remain responsible for reviewing how the plugin, runtime, and distributed application artifacts fit their own build and distribution process.

An adoption or upgrade can therefore involve more than editing one plugins block. Check Kotlin, Compose compiler, Compose Multiplatform, Java, IDE, and plugin versions first. Confirm that automatic JetBrains Runtime provisioning is acceptable if Gradle will manage it, and keep an ordinary restart path available for changes that require clean startup behavior.

Editorial conclusion

Compose Hot Reload suits desktop-oriented Compose Multiplatform developers who want save-driven UI iteration without restarting the application. It is not suitable for projects without a JVM target or for toolchains outside the documented Kotlin, Compose, IDE, and Java 21 limits. Before adoption, verify that the target runs on JetBrains Runtime, that its state survives a reload, and that the documented version thresholds match the project.

Frequently asked questions

Official sources

1. Issues
2. JetBrains/compose-hot-reload on GitHub
3. License: Apache-2.0
4. README
5. Releases