Reload Modes

Understand the difference between Explicit and Auto reload modes

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

1. You make changes to your code and save files
2. Nothing happens automatically
3. 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
4. Gradle recompiles changed files
5. 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:

1. Make code changes and save

2. Click the Reload UI button that appears in the floating dev tools window

3. 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

1. You start your application with auto reload enabled
2. Gradle’s file system watching (--watch-fs) monitors your source files
3. When you save changes, Gradle automatically:
   • Detects the changed files
   • Incrementally recompiles them
   • Sends the updated classes to the agent
   • Triggers a hot reload
4. 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:

1. Modify your run configuration
2. 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:

1. Configure Reload Behavior:

   • Go to Settings | Tools | Compose Hot Reload
   • Choose when to trigger reload:
     • On save (Explicit)
     • On build (Explicit)
     • Automatically (Auto Mode)

2. 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

3. 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:

1. Create a Gradle run configuration for hotRunJvm
2. Use the “Reload UI” button in the dev tools window
3. 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

1. Check the dev tools console for compilation errors
2. Verify the file is on the hot classpath (project sources)
3. Ensure you saved the file before triggering reload
4. 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.