Skip to content

Known_limitations.md

Latest commit

 

History

History
130 lines (97 loc) · 7.18 KB

Known_limitations.md

File metadata and controls

130 lines (97 loc) · 7.18 KB

Known limitations of Compose Hot Reload

This list contains known issues/limitations of Compose Hot Reload. The limitations listed here are mainly caused by external factors rather than Compose Hot Reload itself. Therefore, we cannot guarantee that these issues will be resolved in the future. The list does not cover all possible issues and may be updated.

Adding Compose Hot Reload causes my application's window to flicker/jump/behave weirdly

Compose Hot Reload currently supports all main OSs. However, the dev tooling window snapping itself to the main application's window can cause unusual behavior (flickering, jumping, etc.) on some window managers. If you encounter such issues, please report them to us; we will try to reproduce and fix them.

As a workaround, you can try:

  1. Running the dev tools window in detached mode by setting the -Dcompose.reload.devToolsDetached=true property. This will launch the dev tools as a regular window, without snapping to the main application's window.
  2. Running the dev tools window in a headless mode by setting the -Dcompose.reload.devToolsHeadless=true property. This will launch the dev tools process, but will not show any UI.
  3. Disabling the dev tools process entirely by setting the -Dcompose.reload.devToolsEnabled=false property. This will prevent the dev tools process from starting, which may limit some functionality of Compose Hot Reload.

Original issue: CMP-9674

Issues when using Virtual Desktops/Workspaces

All the main OSs support some form of virtual desktops/workspaces. However, they do not provide a public API for accessing information about the current desktop of the window nor an API for changing the virtual desktop of the window. This is expected, as user applications should not rely on or care about the current desktop of the window.

Unfortunately, this means that Compose Hot Reload cannot reliably detect on which virtual desktop the user windows spawns and cannot change the virtual desktop of the dev tools window when necessary. The same happens when the user moves the main applications window to another virtual desktop: Compose Hot Reload cannot detect that and move the dev tools window accordingly.

Therefore, if you use virtual desktops, we recommend running the dev tools window in detached mode. You can enable detached mode by setting the -Dcompose.reload.devToolsDetached=true property.

Original issue: #426

Compose Hot Reload does not work with Windows Dev Drive (ReFS)

Compose Hot Reload relies on the Gradle File System Watching to detect changes in the source files. Unfortunately, it does not currently support ReFS. There is an open issue in Gradle's tracker: #31634.

For now, we recommend moving your project to an NTFS-formatted drive.

Original issue: #190

Running multiple Compose applications in the same IDE instance

The Kotlin Multiplatform IDE plugin currently supports only a single Compose Hot Reload connection at a time. If you try to simultaneously run multiple Compose applications within the same IDE instance, you may experience unexpected shutdowns.

Supporting only a single Compose Hot Reload connection in Kotlin Multiplatform is intentional, as having multiple Compose Hot Reload-related UI elements in the IDE can be overwhelming and confusing. If you're running multiple Compose applications simultaneously, we recommend running only one of them in hot reload mode. Alternatively, you can run other applications from the command line; then Compose Hot Reload will not automatically connect to the IDE.

Original issue: #408

Property compose.application.resources.dir is null when running hot reload tasks

Compose desktop native distribution that allows adding arbitrary files to the final distribution, accessing them later via compose.application.resources.dir system property from the application. However, the Compose Gradle plugin currently sets this property only for the run task. For other tasks, including desktopRun, hotRunDesktop, etc., this property is not set.

As a workaround, you can set this property manually in your build.gradle.kts file:

tasks.withType<ComposeHotRun>().configureEach {
    systemProperty(
        "compose.application.resources.dir",
        project.layout.buildDirectory.dir("compose/tmp/prepareAppResources").get()
    )
}

Original issue: #343

Original issue in CMP tracker: CMP-8800

Exceptions when making changes to the global state

Compose Hot Reload aims to support any changes to the source code of the application. Unfortunately, it is not always possible, mainly because of the global state. When you make changes to your application's code, Compose Hot Reload invalidates all the affected Compose code and re-renders the UI to ensure that all the references to the 'old' code are cleaned up. However, Compose Hot Reload cannot invalidate the global state of your application (except statics), which means that it is possible that some changes to it will cause exceptions.

If changes to the global state cause issues in your application, you have two options:

  1. Restart the application after the changes.
  2. 'Manually' reset the global state of your application by adding hooks via the Compose Hot Reload Runtime API. Add the following dependency:
implementation("org.jetbrains.compose.hot-reload:hot-reload-runtime-api:*latest version*")
if (isHotReloadActive) {
    // Non-composable option
    staticHotReloadScope.invokeAfterHotReload {
        // reset your state here
    }
    // Composable option
    AfterHotReloadEffect {
        // reset your state here
    }
}

ViewModel support

One of the common examples of the global state is are the ViewModel classes. View models presist their state through the changes in the UI, meaning that any information they store will be persisted as well. If you want to use hot reload with view models, you need to make sure that you reset their state properly after hot reload.

if (isHotReloadActive) {
  val viewModelStoreOwner = LocalViewModelStoreOwner.current
  staticHotReloadScope.invokeAfterHotReload {
    viewModelStoreOwner?.viewModelStore?.clear()
  }
}

Original issue: #489

If you encounter any issues not mentioned here, please report them to us. If you have any further questions regarding one of the listed issues, please feel free to ask them in the linked original issue or create a new issue/discussion.