Skip to main content
This page documents Gradle-specific properties for Compose Hot Reload, including build configuration, task management, and optimization settings.

Overview

Gradle properties control how Hot Reload integrates with your Gradle build:
  • Project and task identification
  • Build optimization and caching
  • Java toolchain configuration
  • Continuous rebuild mode
  • Build warmup and performance
These properties can be set via:
  • gradle.properties file (prefixed with systemProp.)
  • Command line flags (-D flags)
  • Environment variables
  • Gradle build scripts

Project Configuration

Build Root

gradle.build.root
file
Target: application, devtoolsThe root path to the current Gradle project. This property is automatically set by the Hot Reload Gradle plugin and used by the recompiler to locate your project.
// Automatically set by plugin
val buildRoot = System.getProperty("gradle.build.root")
// e.g., "/Users/developer/my-project"

Project Path

gradle.build.project
string
Target: application, devtoolsThe gradle ‘path’ to the ‘project’ which is currently executed and needs recompiling.Examples:
  • : (root project)
  • :app:
  • :someModule:composeApp
// Identifies which Gradle project to recompile
val projectPath = System.getProperty("gradle.build.project")

Hot Reload Task

gradle.build.task
string
Target: application, devtoolsThe name of the task which is supposed to be recompiled for hot reload. This is typically the name of a ComposeReloadHotClasspathTask task.
// Example task name
val taskName = System.getProperty("gradle.build.task")
// e.g., "composeHotReloadDesktop"

Java Toolchain

Java Home

org.gradle.java.home
file
Target: application, devtoolsThe ‘java home’ used to run Gradle. The recompiler will pick the same java to launch the recompiler in order to avoid cache misses or other issues.Why this matters: Using different JDKs between the main build and recompilation can cause:
  • Gradle cache misses
  • Incompatible bytecode
  • Performance degradation
# gradle.properties
org.gradle.java.home=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
# Command line
./gradlew runHot -Dorg.gradle.java.home=/path/to/jdk

Build Modes

Hot Reload Build Detection

compose.reload.isHotReloadBuild
boolean
default:"false"
Target: buildAvailable in the build (e.g. Gradle) to indicate whether or not the current build is intended to recompile classes for a hot reload build. Typically, this property is used to disable tasks which are not required to produce classes and improve build speed.Use case: Skip expensive tasks during hot reload recompilation.
// In build.gradle.kts
tasks.register("generateDocs") {
  // Skip documentation generation during hot reload
  onlyIf {
    System.getProperty("compose.reload.isHotReloadBuild") != "true"
  }
}

tasks.named("processResources") {
  // Skip resource processing during hot reload if not needed
  enabled = System.getProperty("compose.reload.isHotReloadBuild") != "true"
}

Offline Mode

gradle.offline.mode
boolean
default:"false"
Target: application, devtoolsThe ‘offline mode’ used to run Gradle. The recompiler will pick the same offline mode to launch the recompiler in order to avoid cache misses or other issues.
# Run in offline mode
./gradlew runHot --offline
The Hot Reload recompiler will automatically inherit this setting.

Build Optimization

Build Optimization

compose.reload.gradle.build.optimize
boolean
default:"true"
Target: application, devtools, build
Visibility: delicate
  • true: Compose Hot Reload will try to optimize your build during hot reload (e.g. by enabling Gradle’s configuration cache during ‘recompilation’)
  • false: No optimization will be performed
Optimizations applied:
  • Enables Gradle configuration cache for recompilation
  • Skips unnecessary tasks
  • Reuses build outputs when possible
# gradle.properties - disable optimizations if you encounter issues
systemProp.compose.reload.gradle.build.optimize=false

Continuous Build Mode

compose.reload.build.continuous
boolean
default:"false"
Target: application, devtools, build
Visibility: delicate
  • true: Compose Hot Reload will start a recompiler Gradle Daemon, which will continuously rebuild/reload the project by watching all inputs to the build
  • false: The user is expected to rebuild/reload manually by launching a task (or using tooling)
Note: Continuous mode is subject to change and might be removed in the future.
# Enable continuous rebuild mode
./gradlew runHot -Dcompose.reload.build.continuous=true
In continuous mode, Hot Reload watches for file changes and automatically triggers recompilation without manual intervention.

Build Warmup

compose.reload.build.warmup
boolean
default:"false"
Target: application, devtools, build
Visibility: delicate
  • true: Compose Hot Reload will launch a warmup recompile request when the application is started, to ensure that the recompiler Gradle daemon is running and ready to handle requests
  • false: No warmup request will be sent, first reload request may take longer time
Benefits of warmup:
  • Faster first reload (Gradle daemon already running)
  • Pre-resolved dependencies
  • Warmed up JVM
Trade-off: Slower application startup
# gradle.properties - enable warmup for faster reloads
systemProp.compose.reload.build.warmup=true

Runtime Dependencies

Auto Runtime Dependencies

compose.reload.autoRuntimeDependenciesEnabled
boolean
default:"true"
Target: buildWhether or not the hot-reload-runtime will be added as a compile dependency automatically when running a build.When enabled, the Gradle plugin automatically adds Hot Reload runtime dependencies to your project.
// When disabled, you must add dependencies manually:
dependencies {
  implementation("org.jetbrains.compose.reload:compose-reload-runtime")
}
# gradle.properties - disable auto-dependencies
systemProp.compose.reload.autoRuntimeDependenciesEnabled=false

JetBrains Runtime (JBR)

JBR Binary

compose.reload.jbr.binary
file
Target: build
Visibility: delicate
The path to the ‘JetBrainsRuntime’ which shall be used when launching the app.Note: This is a build-only property!
# Specify custom JBR
./gradlew runHot -Dcompose.reload.jbr.binary=/path/to/jbr/bin/java

JBR Version

compose.reload.jbr.version
int
default:"21"
Target: build
Visibility: delicate
Specifies the default ‘JetBrains Runtime’ version that shall be used (e.g. 21 or 25).
# gradle.properties - use JBR 25
systemProp.compose.reload.jbr.version=25

Auto JBR Provisioning

compose.reload.jbr.autoProvisioningEnabled
boolean
default:"false"
Target: build
Visibility: experimental
Automatically provisions compatible ‘JetBrains Runtime’ version that shall be used for hot reload tasks.When enabled, Hot Reload will automatically download and configure a compatible JBR if none is found.
# gradle.properties - enable auto-provisioning
systemProp.compose.reload.jbr.autoProvisioningEnabled=true

Gradle JBR Provisioning

compose.reload.jbr.gradleProvisioningEnabled
boolean
default:"true"
Target: build
Visibility: internal
If enabled Compose Hot Reload Gradle plugin will attempt to automatically provision compatible ‘JetBrains Runtime’ version via Gradle’s toolchain resolution mechanism.This property is internal and only intended for use in tests.

IntelliJ IDEA Integration

IDEA Hot Reload Support

idea.compose.hot-reload
boolean
default:"false"
Target: build, application, devtoolsSet by IntelliJ to signal the Gradle Plugin that IDE tooling is available. Setting this variable will relax the Gradle Plugin to not touch existing run tasks as we expect the IDE to provide a convenient way of launching in hot-reload mode.Automatically set by IntelliJ IDEA. Do not set manually.

IDEA Support Version

idea.compose.hot-reload.version
int
Target: build, application, devtoolsSet by IntelliJ during builds to convey its ‘support level’ for hot reload.Support levels:
  • Not Present, but idea.compose.hot-reload being set: Supports running hot run tasks
  • 2: Support running ‘hot run’ tasks and ‘hot reload’ tasks
  • 3: Supports providing IDEA runtime using idea.compose.hot-reload.jbr
Automatically set by IntelliJ IDEA. Do not set manually.

IDEA JBR Path

idea.compose.hot-reload.jbr
file
Target: buildForwards the ‘JetBrains Runtime’ which is bundled with the current version of IntelliJ (points to the binary bin/java). Can be used as ‘fallback’ when no other JBR is found.Automatically set by IntelliJ IDEA. Do not set manually.

Deprecated

Isolated Projects

compose.reload.isolatedProjectsEnabled
boolean
default:"false"
Target: application, build, devtools
Visibility: deprecated
Enables support for Gradle’s incubating ‘isolated projects’ feature.Note: This property is deprecated and may be removed in future versions.

Configuration Examples

Basic gradle.properties Configuration

# gradle.properties

# Enable debug logging
systemProp.compose.reload.logLevel=Debug

# Optimize build performance
systemProp.compose.reload.gradle.build.optimize=true

# Enable build warmup for faster reloads
systemProp.compose.reload.build.warmup=true

# Specify JBR version
systemProp.compose.reload.jbr.version=21

Command Line Configuration

# Run with specific Gradle properties
./gradlew runHot \
  -Dcompose.reload.gradle.build.optimize=true \
  -Dcompose.reload.build.warmup=true \
  -Dcompose.reload.logLevel=Debug

Conditional Task Configuration

// build.gradle.kts

tasks.withType<Test> {
  // Skip tests during hot reload builds
  onlyIf {
    System.getProperty("compose.reload.isHotReloadBuild") != "true"
  }
}

tasks.register("optimizeAssets") {
  // Only run asset optimization in production builds
  enabled = System.getProperty("compose.reload.isHotReloadBuild") != "true"
}

// Configure compilation for hot reload
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
  kotlinOptions {
    if (System.getProperty("compose.reload.isHotReloadBuild") == "true") {
      // Faster incremental compilation during hot reload
      freeCompilerArgs = freeCompilerArgs + listOf(
        "-Xskip-prerelease-check"
      )
    }
  }
}

Multi-Module Project Configuration

// settings.gradle.kts

// Hot Reload will set gradle.build.project to identify which module to recompile
val hotReloadProject = System.getProperty("gradle.build.project")
if (hotReloadProject != null) {
  println("Hot Reload targeting project: $hotReloadProject")
}

Optimizing Build Performance

# gradle.properties - Performance tuning

# Enable parallel builds
org.gradle.parallel=true

# Increase Gradle daemon memory
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g

# Enable Gradle build cache
org.gradle.caching=true

# Enable configuration cache (used by hot reload optimization)
org.gradle.configuration-cache=true

# Hot Reload optimization (enables config cache during recompilation)
systemProp.compose.reload.gradle.build.optimize=true

Passing Properties Between Processes

Hot Reload automatically passes relevant properties between Gradle and application processes:
// Properties automatically propagated:
// 1. Initial Gradle build sets properties
// 2. Application process receives properties
// 3. Recompiler daemon inherits properties

// Example: Gradle sets java.home
val javaHome = System.getProperty("org.gradle.java.home")

// Hot Reload ensures recompiler uses same JDK
// to avoid cache misses and compatibility issues

Best Practices

Performance Optimization

  1. Enable build optimization:
    systemProp.compose.reload.gradle.build.optimize=true
    
  2. Skip unnecessary tasks:
    tasks.named("expensiveTask") {
      onlyIf { System.getProperty("compose.reload.isHotReloadBuild") != "true" }
    }
    
  3. Use warmup for frequent reloads:
    systemProp.compose.reload.build.warmup=true
    

Stability

  1. Pin Java version:
    org.gradle.java.home=/path/to/stable/jdk
    
  2. Use offline mode for reproducible builds:
    ./gradlew runHot --offline
    
  3. Disable experimental features in production:
    systemProp.compose.reload.jbr.autoProvisioningEnabled=false
    

Debugging

  1. Enable verbose logging:
    systemProp.compose.reload.logLevel=Debug
    systemProp.compose.reload.logStdout=true
    
  2. Disable optimizations when troubleshooting:
    systemProp.compose.reload.gradle.build.optimize=false
    

Build docs developers (and LLMs) love