Reload Modes - Compose Hot Reload

Overview

Compose Hot Reload supports two reload modes that control how and when code changes are applied to your running application:

Explicit Mode: You manually trigger reloads when you’re ready
Auto Mode: Changes are automatically detected and applied

Each mode has different trade-offs in terms of control, performance, and workflow integration.

Explicit Mode (Default)

In Explicit Mode, you control exactly when code changes are compiled and reloaded.

How It Works

You make changes to your code and save files
Nothing happens automatically
When you’re ready, you manually trigger a reload:
- Click the “Reload UI” button in the dev tools window
- Press the configured keyboard shortcut in your IDE
- Run ./gradlew reload from the command line
Gradle recompiles changed files
The hot reload agent applies the changes

Benefits

Explicit Mode is recommended for most development workflows as it gives you precise control over when reloads occur.

Control: Reload only when you’ve finished a logical change
Performance: No background file watching or compilation overhead
Stability: Avoid reloading incomplete or broken code
Debugging: Easier to reason about when changes are applied
Battery Life: Less CPU usage from continuous builds

When to Use

You’re making complex changes across multiple files
You want to complete a thought before seeing the result
You’re working on battery power
You’re debugging and need predictable behavior
You prefer manual control over automatic systems

Usage Examples

From the IDE:

Make code changes and save
Click the Reload UI button that appears in the floating dev tools window
Or use the keyboard shortcut (configurable in Settings | Tools | Compose Hot Reload)

From the command line:

# Terminal 1: Start your application
./gradlew :app:hotRunJvm

# Terminal 2: Trigger reload after making changes
./gradlew :app:reload

Multiple reloads:

# Reload specific source set
./gradlew :app:hotReloadJvmMain

# Reload all running applications
./gradlew :app:reload

Auto Mode

In Auto Mode, Gradle continuously watches for file changes and automatically triggers recompilation and reload.

How It Works

You start your application with auto reload enabled
Gradle’s file system watching (--watch-fs) monitors your source files
When you save changes, Gradle automatically:
- Detects the changed files
- Incrementally recompiles them
- Sends the updated classes to the agent
- Triggers a hot reload
Your UI updates automatically

Benefits

Immediate Feedback: See changes the moment you save
Flow State: Stay focused on coding without manual triggers
Live Editing: Experience near-instantaneous visual feedback
Fewer Keystrokes: No need to switch context or press buttons

Drawbacks

Auto Mode can cause unexpected reloads if you save files while still editing or if you have auto-save enabled.

Less Control: Reloads happen automatically, even for incomplete code
Performance: Continuous file watching and builds consume CPU
Battery Drain: Higher power consumption on laptops
Unexpected Reloads: May reload when you didn’t intend to
Build Interruptions: Can’t easily batch multiple file changes

When to Use

You’re making rapid, small tweaks to UI code
You want instant visual feedback for design work
You’re working on a powerful desktop with AC power
You prefer automatic systems over manual control
You’re doing exploratory coding with lots of experiments

Enabling Auto Mode

Auto Mode must be explicitly enabled using command-line arguments. From the IDE:

Modify your run configuration
Add --autoReload or --auto to the task arguments

From the command line:

# Using --autoReload flag
./gradlew :app:hotRunJvm --autoReload

# Or using the shorter --auto flag
./gradlew :app:hotRunJvm --auto

The --auto flag is a shorthand alias for --autoReload. Both flags do exactly the same thing.

In build.gradle.kts: You can set the default behavior in your build script:

tasks.withType<ComposeHotRun>().configureEach {
    isAutoReloadEnabled.set(true)
}

Disabling Auto Mode

If auto reload is enabled by default in your build script, you can disable it:

# Disable auto reload explicitly
./gradlew :app:hotRunJvm --no-autoReload

# Or using the shorter form
./gradlew :app:hotRunJvm --no-auto

Configuration

Auto mode is controlled by several configuration properties:

Gradle Property

Set in gradle.properties:

# Enable auto reload by default for all runs
compose.reload.gradleBuildContinuous=true

System Property

Pass at runtime:

./gradlew :app:hotRunJvm -Dcompose.reload.gradleBuildContinuous=true

Task Configuration

Configure in build.gradle.kts:

tasks.withType<ComposeHotRun>().configureEach {
    // Enable auto reload by default
    isAutoReloadEnabled.set(true)
    
    // Or make it conditional
    isAutoReloadEnabled.set(
        providers.gradleProperty("autoReload")
            .map { it.toBoolean() }
            .orElse(false)
    )
}

Then use:

./gradlew :app:hotRunJvm -PautoReload=true

Command-Line Arguments Reference

Here’s a complete reference of reload-related arguments:

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

Understanding Gradle Continuous Build

Auto Mode leverages Gradle’s built-in continuous build feature:

# Gradle's continuous build (used internally by auto mode)
./gradlew build --continuous

When enabled:

Gradle monitors all declared task inputs
File system watching uses native OS APIs for efficiency
Incremental compilation runs automatically
Only changed files are recompiled

Gradle’s file system watching is highly optimized and uses minimal CPU when files aren’t changing.

Supported File Systems

Gradle’s file watching works on:

Linux: All major file systems (ext4, btrfs, xfs, etc.)
macOS: APFS, HFS+
Windows: NTFS

Windows Dev Drive (ReFS) is not supported by Gradle’s file system watching. If you’re using ReFS, you must:

Use Explicit Mode only
Or move your project to an NTFS drive

See Known Limitations for details.

Reload Tasks (Explicit Mode Only)

When using Explicit Mode, you have several Gradle tasks available:

`reload`

Reloads all currently running hot reload applications:

./gradlew :app:reload

This task:

Recompiles all changed source files
Sends a ReloadClassesRequest via orchestration
Waits for the agent to apply changes
Works with multiple running applications

`hotReloadJvmMain`

Reloads only applications using the jvmMain source set:

./gradlew :app:hotReloadJvmMain

Use this when:

You have multiple JVM targets
You want to reload only specific source sets

`hotReload<Target>Main`

For custom target names:

kotlin {
    jvm("desktop")
}

The reload task becomes:

./gradlew :app:hotReloadDesktopMain

You cannot use reload tasks with the --autoReload or --auto flags. Auto mode handles reloading automatically.

IDE Integration

IntelliJ IDEA / Android Studio

With the Kotlin Multiplatform plugin installed:

Configure Reload Behavior:
- Go to Settings | Tools | Compose Hot Reload
- Choose when to trigger reload:
  - On save (Explicit)
  - On build (Explicit)
  - Automatically (Auto Mode)
Run Configuration:
- Use “Run with Compose Hot Reload” from the gutter icon
- Or create a Gradle run configuration with hotRunJvm task
- Add --autoReload to arguments if desired
Keyboard Shortcut:
- Customize the reload shortcut in Settings | Keymap
- Search for “Compose Hot Reload”

Without IDE Plugin

If you don’t have the Kotlin Multiplatform plugin:

Create a Gradle run configuration for hotRunJvm
Use the “Reload UI” button in the dev tools window
Or run ./gradlew reload from a terminal

Choosing the Right Mode

Scenario	Recommended Mode
General development	Explicit
UI design and tweaking	Auto
Complex refactoring	Explicit
Debugging	Explicit
Laptop (battery)	Explicit
Desktop (AC power)	Either
Multiple file changes	Explicit
Single file iteration	Auto
Learning/experimenting	Auto
Production code	Explicit

Performance Considerations

Explicit Mode

No overhead when not reloading
Reloads happen only when triggered
Full Gradle daemon remains running (normal behavior)

Auto Mode

Continuous file watching: Minimal CPU (~1-2%)
Incremental compilation: Only changed files
Gradle daemon: Stays active between builds
Memory: Gradle keeps more in memory for speed

For large projects (>100k LOC), Explicit Mode is recommended to avoid continuous build overhead.

Troubleshooting

Auto Mode Not Working

Check that file watching is enabled:

./gradlew :app:hotRunJvm --auto --info

Look for:

Watching 123 directory hierarchies to track changes

Verify your file system is supported:

Windows ReFS is not supported
Use NTFS on Windows

Increase file watch limit on Linux:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Reload Too Slow

Use incremental compilation (enabled by default in Kotlin 2.0+):

kotlin {
    jvm {
        compilations.configureEach {
            compilerOptions.configure {
                useK2.set(true)
            }
        }
    }
}

Disable unnecessary Gradle tasks during hot reload:

tasks.configureEach {
    onlyIf {
        val isHotReload = providers.systemProperty("compose.reload.isHotReloadBuild")
            .map { it.toBoolean() }
            .orElse(false)
            .get()
        
        if (isHotReload && name in listOf("test", "jar", "assemble")) {
            false // Skip these tasks during hot reload
        } else {
            true
        }
    }
}

Changes Not Applying

Check the dev tools console for compilation errors
Verify the file is on the hot classpath (project sources)
Ensure you saved the file before triggering reload
Check for static state issues (see Known Limitations)

Summary

Explicit Mode (default): Manual control, better for most workflows
Auto Mode: Automatic detection, better for rapid iteration
Enable with --autoReload or --auto flags
Configure in gradle.properties or build.gradle.kts
Use reload tasks in Explicit Mode
Choose based on your workflow and hardware

Start with Explicit Mode and switch to Auto Mode when you need faster iteration on UI changes.

Get Started

Core Concepts

Usage

Advanced

Troubleshooting

​Overview

​Explicit Mode (Default)

​How It Works

​Benefits

​When to Use

​Usage Examples

​Auto Mode

​How It Works

​Benefits

​Drawbacks

​When to Use

​Enabling Auto Mode

​Disabling Auto Mode

​Configuration

​Gradle Property

​System Property

​Task Configuration

​Command-Line Arguments Reference

​Understanding Gradle Continuous Build

​Supported File Systems

​Reload Tasks (Explicit Mode Only)

​reload

​hotReloadJvmMain

​hotReload<Target>Main

​IDE Integration

​IntelliJ IDEA / Android Studio

​Without IDE Plugin

​Choosing the Right Mode

​Performance Considerations

​Explicit Mode

​Auto Mode

​Troubleshooting

​Auto Mode Not Working

​Reload Too Slow

​Changes Not Applying

​Summary

Build docs developers (and LLMs) love

Overview

Explicit Mode (Default)

How It Works

Benefits

When to Use

Usage Examples

Auto Mode

How It Works

Benefits

Drawbacks

When to Use

Enabling Auto Mode

Disabling Auto Mode

Configuration

Gradle Property

System Property

Task Configuration

Command-Line Arguments Reference

Understanding Gradle Continuous Build

Supported File Systems

Reload Tasks (Explicit Mode Only)

`reload`

`hotReloadJvmMain`

`hotReload<Target>Main`

IDE Integration

IntelliJ IDEA / Android Studio

Without IDE Plugin

Choosing the Right Mode

Performance Considerations

Explicit Mode

Auto Mode

Troubleshooting

Auto Mode Not Working

Reload Too Slow

Changes Not Applying

Summary