System Properties

Compose Hot Reload uses system properties to configure runtime behavior, build processes, and development tools. These properties can be set via -D flags when launching your application or Gradle build.

Overview

System properties control various aspects of Hot Reload:

Application properties: Core runtime behavior and lifecycle
Build properties: Compilation and recompilation settings
Dev tools properties: UI and debugging features
Gradle properties: Build system integration
Logging properties: Output and diagnostics
Advanced properties: Experimental and internal features

Application Properties

Hot Reload Status

compose.reload.isActive

boolean

default:"false"

Target: application
Visibility: publicWill be set to true if the application is launched with Hot Reload and therefore can be used to detect if hot reload is ‘active’.

val isHotReload = System.getProperty("compose.reload.isActive") == "true"
if (isHotReload) {
  // Hot reload-specific behavior
}

compose.reload.mainClass

string

Target: application, devtoolsProperty available in the application and ‘devtools’ pointing to the mainClass used to launch the application.

compose.reload.launchMode

enum

Target: application, devtools
Enum class: org.jetbrains.compose.reload.core.LaunchModeTells the application ‘how’ it was launched.

compose.reload.headless

boolean

default:"false"

Target: application, devtools, buildIndicating whether or not the application is supposed to run in headless mode.

Classpath Configuration

compose.reload.hotApplicationClasspath

string

Target: applicationThe classpath known to be hot. This property is optional.

compose.reload.argfile

file

Target: application, devtools, buildThe java ‘argfile’ (see: Java Command-Line Argument Files) containing all arguments of the current run.

Process Management

compose.reload.pidFile

file

Target: application, devtoolsPath to the current application’s pidfile.

compose.reload.parentPid

long

Target: devtools, buildThe pid of the parent process. This property is used by components that shall connect to the ‘orchestration’ (e.g. recompiler, devtools, …). If the parent dies, it is expected that children exit as well.

Orchestration

compose.reload.orchestration.port

int

Target: build, devtools, applicationCurrent ‘Orchestration Server’ port. This property is used by components that shall connect to the ‘orchestration’ (e.g. recompiler, devtools, …).

Build Properties

Hot Reload Build

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.

tasks.register("someTask") {
  enabled = System.getProperty("compose.reload.isHotReloadBuild") != "true"
}

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.

Build System Selection

compose.reload.buildSystem

enum

Target: application, devtools
Enum class: org.jetbrains.compose.reload.core.BuildSystemIndicating the application which build system is supposed to be used for recompiling. See further build-system specific (Gradle, Amper, …) properties.

Dependency Analysis

compose.reload.virtualMethodResolveEnabled

boolean

default:"true"

Target: application, buildtrue: Enable dependency analysis for virtual calls (e.g. Interfaces and their corresponding implementations will be tracked).

// When enabled, changing an interface implementation triggers reload
interface MyInterface { fun doSomething() }
class MyImpl : MyInterface { override fun doSomething() { /* ... */ } }

compose.reload.dirtyResolveDepthLimit

int

default:"5"

Target: application, buildIf a given scope is marked as dirty, then Hot Reload will follow the dependency graph between fields/methods and further marks scopes as dirty. This property limits how deep this graph can be traversed.Higher values provide more accurate reloading but may impact performance.

Statics Re-initialization

compose.reload.staticsReinitializeMode

enum

default:"AllDirty"

Target: application, build
Visibility: experimental
Enum class: org.jetbrains.compose.reload.core.StaticsReinitializeModeSets the mode for statics re-initialization.

AllDirty: All static initializers that are recognized as dirty (affected by changes) will be re-invoked on reload.
ChangedOnly: Only statics of changed classes will be re-initialized.

Dev Tools Properties

Dev Tools Lifecycle

compose.reload.devToolsEnabled

boolean

default:"true"

Target: application, devtools, build
Visibility: publicFlag to disable the ‘devtools’ application entirely.

# Disable dev tools
./gradlew runHot -Dcompose.reload.devToolsEnabled=false

compose.reload.devToolsHeadless

boolean

default:"false"

Target: application, devtools, build
Visibility: publicRun the dev tools in headless mode (No UI window shown).

compose.reload.devToolsClasspath

files

Target: applicationThe classpath notation of the devTools application. Hot Reload will start DevTools in a different process and therefore needs the classpath.

Dev Tools UI

compose.reload.devToolsTransparencyEnabled

boolean

default:"true (except Linux)"

Target: application, build, devtools
Visibility: delicateSome platforms might not be able to render transparency correctly (e.g. some Linux environments). This property will allow such platforms to disable/enable transparency. This property is subject to change if the issues with transparency rendering are resolved.Default is platform-dependent: Os.currentOrNull() != Os.Linux

compose.reload.devToolsDetached

boolean

default:"false"

Target: application, build, devtools
Visibility: publicIf enabled, dev tools window will be detached from the main application.

Reload Effects

compose.reload.effectsEnabled

boolean

default:"true"

Target: application, build
Visibility: publicEnable reload effects that are shown in the UI when a reload is triggered.

Gradle-Specific Properties

See Gradle Properties for detailed Gradle configuration.

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.

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.

gradle.build.root

file

Target: application, devtoolsThe root path to the current Gradle project.

gradle.build.project

string

Target: application, devtoolsThe gradle ‘path’ to the ‘project’ which is currently executed and needs recompiling (e.g. :app:, :, or :someModule:composeApp).

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.

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)

Continuous mode is subject to change and might be removed in the future.

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

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

Amper Properties

amper.build.root

string

Target: application, devtoolsThe root path to the current Amper project.

amper.build.task

string

Target: application, devtoolsThe name of the task which is supposed to be recompiled for hot reload in Amper.

Logging Properties

compose.reload.logLevel

enum

default:"Info"

Target: application, devtools, build
Visibility: public
Enum class: org.jetbrains.compose.reload.core.Logger.LevelMinimum logging level. Available values: Trace, Debug, Info, Warning, Error.

# Enable debug logging
./gradlew runHot -Dcompose.reload.logLevel=Debug

compose.reload.logStdout

boolean

default:"false"

Target: application, build, devtools
Visibility: publicEnable output of all logs into the standard output.

# Send logs to stdout
./gradlew runHot -Dcompose.reload.logStdout=true

JetBrains Runtime Properties

compose.reload.jbr.binary

file

Target: build
Visibility: delicateThe path to the ‘JetBrainsRuntime’ which shall be used when launching the app.Note: This is a build-only property!

compose.reload.jbr.version

int

default:"21"

Target: build
Visibility: delicateSpecifies the default ‘JetBrains Runtime’ version that shall be used (e.g. 21 or 25).

compose.reload.jbr.autoProvisioningEnabled

boolean

default:"false"

Target: build
Visibility: experimentalAutomatically provisions compatible ‘JetBrains Runtime’ version that shall be used for hot reload tasks.

compose.reload.jbr.gradleProvisioningEnabled

boolean

default:"true"

Target: build
Visibility: internalIf 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.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.

idea.compose.hot-reload.version

int

Target: build, application, devtoolsSet by IntelliJ during builds to convey its ‘support level’ for hot reload.

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

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.

compose.reload.idea.debugger.dispatch.port

int

Target: application, devtools, buildNote: Expected as an environment variable, as this is expected to be transitively available to all child processes.Currently, launching applications with hot reload might be done through a couple of intermediate processes. For example, launching a test will go through a chain like:

intellij --launches--> Gradle --launches--> JVM(Junit) --launches--> Gradle --launches--> JVM (Application)

When a run configuration is started in ‘debug mode’ intellij will set the system property idea.debugger.dispatch.port. This will indicate that a server is listening at this port, which can be used to provision debugging servers.This debug port will then be made available as an environment variable using this key. Launching the final application will respect this port, if present and provision a debugging session. This will allow a test to be deeply debuggable by just pressing ‘Debug’.

compose.reload.subprocessDebuggingEnabled

boolean

default:"false"

Target: buildEnable this property to allow propagating the idea.debugger.dispatch.port to all subprocesses. This is useful when debugging dev tools.Note: This may break the debugging of the user application if IntelliJ is not configured to accept multiple debugging sessions. Not recommended to use outside of hot reload debugging.

Advanced Properties

Standard I/O Redirection

compose.reload.stdinFile

file

Target: build, application, devtools
Visibility: delicateUsed by ‘async’/‘non-blocking’ launches of the application. Will point to the stdin file (can be pipe).‘async’/‘non-blocking’ mode is subject to change and might be removed in the future.

compose.reload.stdoutFile

file

Target: build, application, devtools
Visibility: delicateUsed by ‘async’/‘non-blocking’ launches of the application. Will point to a file where the stdout is supposed to be written to.‘async’/‘non-blocking’ mode is subject to change and might be removed in the future.

compose.reload.stderrFile

file

Target: build, application, devtools
Visibility: delicateUsed by ‘async’/‘non-blocking’ launches of the application. Will point to a file where the stderr is supposed to be written to.‘async’/‘non-blocking’ mode is subject to change and might be removed in the future.

Deprecated Properties

compose.reload.isolatedProjectsEnabled

boolean

default:"false"

Target: application, build, devtools
Visibility: deprecatedEnables support for Gradle’s incubating ‘isolated projects’ feature.

Usage Examples

Setting Properties via Command Line

# Enable debug logging and disable dev tools UI
./gradlew runHot \
  -Dcompose.reload.logLevel=Debug \
  -Dcompose.reload.devToolsHeadless=true

Setting Properties in gradle.properties

# gradle.properties
systemProp.compose.reload.logLevel=Debug
systemProp.compose.reload.devToolsEnabled=true
systemProp.compose.reload.effectsEnabled=true

Checking Hot Reload Status in Code

fun isHotReloadActive(): Boolean {
  return System.getProperty("compose.reload.isActive") == "true"
}

@Composable
fun MyApp() {
  if (isHotReloadActive()) {
    // Show development-only UI
    DeveloperToolbar()
  }
  
  // Regular app content
  AppContent()
}

Optimizing Build for Hot Reload

tasks.register("expensiveTask") {
  // Skip expensive tasks during hot reload builds
  onlyIf {
    System.getProperty("compose.reload.isHotReloadBuild") != "true"
  }
}

Property Visibility Levels

Properties are marked with visibility levels indicating their stability:

public: Stable API, safe to use in production
experimental: New features, API may change
delicate: Advanced features, use with caution
internal: For internal use only, may change without notice
deprecated: Will be removed in future versions
(no marker): Standard properties, generally stable

Target Environments

Each property specifies which environments it applies to:

application: Runtime application process
devtools: Dev tools UI process
build: Gradle build process

Gradle Plugin

Runtime API

Configuration

Overview

Application Properties

Hot Reload Status

Classpath Configuration

Process Management

Orchestration

Build Properties

Hot Reload Build

Build System Selection

Dependency Analysis

Statics Re-initialization

Dev Tools Properties

Dev Tools Lifecycle

Dev Tools UI

Reload Effects

Gradle-Specific Properties

Amper Properties

Logging Properties

JetBrains Runtime Properties

IntelliJ IDEA Integration

Advanced Properties

Standard I/O Redirection

Deprecated Properties

Usage Examples

Setting Properties via Command Line

Setting Properties in gradle.properties

Checking Hot Reload Status in Code

Optimizing Build for Hot Reload

Property Visibility Levels

Target Environments

Build docs developers (and LLMs) love

Gradle Plugin

Runtime API

Configuration

​Overview

​Application Properties

​Hot Reload Status

​Classpath Configuration

​Process Management

​Orchestration

​Build Properties

​Hot Reload Build

​Build System Selection

​Dependency Analysis

​Statics Re-initialization

​Dev Tools Properties

​Dev Tools Lifecycle

​Dev Tools UI

​Reload Effects

​Gradle-Specific Properties

​Amper Properties

​Logging Properties

​JetBrains Runtime Properties

​IntelliJ IDEA Integration

​Advanced Properties

​Standard I/O Redirection

​Deprecated Properties

​Usage Examples

​Setting Properties via Command Line

​Setting Properties in gradle.properties

​Checking Hot Reload Status in Code

​Optimizing Build for Hot Reload

​Property Visibility Levels

​Target Environments

Build docs developers (and LLMs) love

Overview

Application Properties

Hot Reload Status

Classpath Configuration

Process Management

Orchestration

Build Properties

Hot Reload Build

Build System Selection

Dependency Analysis

Statics Re-initialization

Dev Tools Properties

Dev Tools Lifecycle

Dev Tools UI

Reload Effects

Gradle-Specific Properties

Amper Properties

Logging Properties

JetBrains Runtime Properties

IntelliJ IDEA Integration

Advanced Properties

Standard I/O Redirection

Deprecated Properties

Usage Examples

Setting Properties via Command Line

Setting Properties in gradle.properties

Checking Hot Reload Status in Code

Optimizing Build for Hot Reload

Property Visibility Levels

Target Environments