Compose Hot Reload

Compose Hot Reload는 Compose Multiplatform 프로젝트를 작업하는 동안 UI 변경 사항을 시각화하고 실험하는 데 도움을 줍니다. 테스트 데이터를 사용하여 격리된 컴포넌트를 확인하는 데 유용한 표준 Compose 미리보기(Compose previews)와 달리, Compose Hot Reload는 코드 변경 사항을 실행 중인 애플리케이션에 직접 적용합니다.

번들로 제공되는 Compose Hot Reload Gradle 플러그인은 Kotlin 2.1.20 이상 및 Java 21 이하와 호환되는 JVM 타겟을 필요로 합니다. Compose Hot Reload의 모든 기능을 사용하려면, IntelliJ IDEA 버전 2025.2.2 이상 및 Android Studio Otter 2025.2.1 이상에서 사용할 수 있는 Kotlin Multiplatform IDE 플러그인을 설치하는 것을 권장합니다.

다른 타겟에 대한 지원 추가를 검토하는 동안, 데스크톱 앱을 샌드박스(sandbox)로 사용하여 흐름을 끊지 않고 공통 코드(common code)의 UI 변경 사항을 빠르게 실험해 볼 수 있습니다.

프로젝트에 Compose Hot Reload 추가하기

Compose Hot Reload는 다음 두 가지 방법으로 추가할 수 있습니다:

• IntelliJ IDEA 또는 Android Studio에서 프로젝트를 처음부터 생성
• 기존 프로젝트에 Gradle 플러그인 추가

처음부터 생성하기

이 섹션에서는 IntelliJ IDEA 및 Android Studio에서 데스크톱 타겟을 포함한 멀티플랫폼 프로젝트를 생성하는 단계를 안내합니다. 프로젝트가 생성되면 Compose Hot Reload가 자동으로 추가됩니다.

1. 빠른 시작(quickstart) 가이드에서 Kotlin Multiplatform 개발 환경 설정 안내를 완료합니다.
2. IDE에서 File | New | Project를 선택합니다.
3. 왼쪽 패널에서 Kotlin Multiplatform을 선택합니다.
4. New Project 창에서 Name, Group, Artifact 필드를 지정합니다.
5. Desktop 타겟을 선택하고 Create를 클릭합니다.

기존 프로젝트에 추가하기

Compose Multiplatform 1.10.0부터 Compose Hot Reload 플러그인은 번들로 제공되며, 데스크톱 타겟을 포함하는 모든 프로젝트에서 기본적으로 활성화됩니다.

프로젝트에 이미 데스크톱 타겟이 포함되어 있다면, Compose Multiplatform 버전을 1.10.0 이상으로 업그레이드하여 별도의 설정 없이 Compose Hot Reload 기능을 바로 사용할 수 있습니다.

기본적으로 활성화되어 있지만, 특정 이전 버전을 사용하기 위해 Compose Hot Reload 플러그인을 명시적으로 선언할 수도 있습니다.

이전 버전의 Compose Multiplatform

1.10.0 이전 버전의 Compose Multiplatform을 사용하는 멀티플랫폼 프로젝트의 경우, 데스크톱 타겟이 구성되어 있어야 하며 Compose Hot Reload 플러그인을 명시적으로 추가해야 합니다. 아래 단계는 공유 로직 및 UI를 포함한 앱 생성 튜토리얼의 프로젝트를 참고용으로 사용합니다.

1. 데스크톱 타겟 도입: jvmMain 디렉토리를 생성하고, main() 함수를 정의하며, actual 구현을 제공합니다. 이미 프로젝트에 데스크톱 타겟이 포함되어 있다면 이 단계를 건너뛸 수 있습니다. 참고를 위해 JVM 진입점 추가의 샘플을 확인하세요.

2. 최신 버전의 Compose Hot Reload로 버전 카탈로그를 업데이트합니다(릴리스 참조). gradle/libs.versions.toml에 다음 코드를 추가합니다:

   composeHotReload = { id = "org.jetbrains.compose.hot-reload", version.ref = "composeHotReload"}

   프로젝트 전체에서 종속성을 중앙에서 관리하기 위해 버전 카탈로그를 사용하는 방법에 대한 자세한 내용은 Gradle 모범 사례를 참조하세요.

3. 상위 프로젝트의 build.gradle.kts(ComposeDemo/build.gradle.kts)에서 plugins {} 블록에 다음 코드를 추가합니다:

   plugins {
       alias(libs.plugins.composeHotReload) apply false
   }

   이렇게 하면 각 하위 프로젝트에서 Compose Hot Reload 플러그인이 여러 번 로드되는 것을 방지할 수 있습니다.

4. 멀티플랫폼 애플리케이션이 포함된 하위 프로젝트의 build.gradle.kts(ComposeDemo/sharedUI/build.gradle.kts)에서 plugins {} 블록에 다음 코드를 추가합니다:

   plugins { 
       alias(libs.plugins.composeHotReload)
   }

5. 프로젝트는 향상된 클래스 재정의(class redefinition)를 지원하는 OpenJDK 포크인 JetBrains Runtime(JBR)에서 실행되어야 합니다. Compose Hot Reload는 프로젝트에 호환되는 JBR을 자동으로 프로비저닝(provision)할 수 있습니다.

   최신 JetBrains Runtime은 Java 21만 지원합니다: Java 22 이상과만 호환되는 프로젝트에 Compose Hot Reload를 추가하면, 프로젝트 실행 시 링크 오류(linkage error)가 발생합니다.

   자동 프로비저닝을 허용하려면 settings.gradle.kts 파일에 다음 Gradle 플러그인을 추가합니다:

   plugins {
       id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
   }

6. Sync Gradle Changes 버튼을 클릭하여 Gradle 파일을 동기화합니다:

Compose Hot Reload 사용하기

1. jvmMain 디렉토리에서 main.kt 파일을 열고 main() 함수를 업데이트합니다:

   fun main() = application {
       Window(
           onCloseRequest = ::exitApplication,
           alwaysOnTop = true,
           title = "composedemo",
       ) {
           App()
       }
   }

   alwaysOnTop 변수를 true로 설정하면, 생성된 데스크톱 앱이 모든 창 위에 유지되어 코드를 수정하고 변경 사항을 실시간으로 확인하기가 더 쉬워집니다.

2. App.kt 파일을 열고 Button 컴포저블(composable)을 업데이트합니다:

   Button(onClick = { showContent = !showContent }) {
       Column {
           Text(Greeting().greet())
       }
   }

   이제 버튼의 텍스트가 greet() 함수에 의해 제어됩니다.

3. Greeting.kt 파일을 열고 greet() 함수를 업데이트합니다:

    fun greet(): String {
        return "Hello!"
    }

4. main.kt 파일을 열고 거터(gutter)에 있는 Run 아이콘을 클릭합니다. Run 'composeApp [jvm]' with Compose Hot Reload를 선택합니다.

   

   

5. greet() 함수에서 반환되는 문자열을 업데이트한 다음, 모든 파일을 저장( / )하면 데스크톱 앱이 자동으로 업데이트되는 것을 확인할 수 있습니다.

   

   또는 할당된 단축키를 누르거나 Reload UI 버튼을 클릭하여 명시적으로 다시 로드(reload)를 트리거할 수도 있습니다. Settings | Tools | Compose Hot Reload 페이지에서 트리거 동작을 수정할 수 있습니다.

축하합니다! Compose Hot Reload가 실제로 작동하는 것을 확인했습니다. 이제 매번 데스크톱 실행 구성을 다시 시작할 필요 없이 텍스트, 이미지, 서식, UI 구조 등을 변경하며 자유롭게 실험해 볼 수 있습니다.

도움 받기

Compose Hot Reload 사용 중 문제 발생 시, GitHub 이슈 생성을 통해 알려주세요.