setting-up-compose-hotswan

Compose HotSwan のセットアップ：実機でゼロから1秒未満のリロードを実現する

Compose HotSwan は、JetBrains IDE プラグインと Gradle コンパイラープラグインを組み合わせたもので、変更された Kotlin クラスを実行中の Compose アプリに1秒未満で差し替え、実機またはエミュレーター上でナビゲーション、スクロール、remember の状態を保持します。このスキルでは両方のプラグインをインストールし、標準の Gradle DSL を debugOnly = true で設定して、最初の保存からリロードまでの一連の動作を確認します。関連するスキルでは、ホットリロードできる変更とできない変更（../understanding-hot-reload-limits/SKILL.md）、リロード後の状態保持、AI 主導の反復ループについて扱います。

執筆時点で確認済みのバージョンです。新しいマイナーバージョンについては、最新のリリースノートを確認してください。

このスキルを使う場面

• 開発者が HotSwan、ホットリロード、UI の即時更新、「保存して確認」、「再ビルドなし」、ライブ編集、またはデバイス上での Compose の高速な反復について言及している場合。
• 開発者が HotSwan JetBrains Marketplace プラグインをインストール済みで、Gradle コンパイラープラグインの適用方法を尋ねている場合。
• チームが新しいプロジェクトに HotSwan を導入するにあたり、標準的な libs.versions.toml とルートおよびアプリのビルド設定を求めている場合。
• 開発者が IDE プラグインをインストールした直後で、ツールウィンドウのステータスが WATCHING になる前の状態で止まっている場合。

このスキルを使わない場面

• JetBrains 独自の Live Edit または Apply Changes についての質問の場合。HotSwan はこれらとは別の製品であり、対象範囲も異なります。混同しないでください。
• IDE 内の Compose Preview のレンダリングについての質問の場合。HotSwan の対象は実機またはエミュレーターで実行中のアプリであり、プレビューキャンバスではありません。
• どの変更がホットリロードされ、どの変更で再ビルドが必要になるかについての質問の場合。../understanding-hot-reload-limits/SKILL.md を参照してください。
• リロード後の複雑な状態の保持についての質問の場合。状態保持に関する関連スキルを参照してください（ここでは対象外です）。

前提条件

• Android Studio 2024.3+ または IntelliJ IDEA 2024.3+。
• Kotlin 2.0+ を使用し、Compose モジュールに org.jetbrains.kotlin.plugin.compose Gradle プラグインがすでに適用されていること。
• Gradle 8+。
• USB デバッグが有効で、adb devices から認識できる実機またはエミュレーター。
• JetBrains Marketplace から HotSwan IDE プラグインをインストールしていること（https://plugins.jetbrains.com/plugin/30551-compose-hotswan/）。

ワークフロー

1. libs.versions.toml でプラグインを宣言し、バージョンを一元管理します。

   [plugins]
   hotswan-compiler = { id = "com.github.skydoves.compose.hotswan.compiler", version = "1.2.10" }
   

   1.2.10 を指定します（執筆時点で確認済みの最新バージョンです）。採用前に HotSwan のリリースページ で、より新しい安定版がないか確認してください。HotSwan は頻繁に更新されるため、新しいマイナーバージョンで、より新しい Compose ランタイムへの互換性が追加されることがよくあります。プラグイン ID は正確に com.github.skydoves.compose.hotswan.compiler です。com.github のプレフィックスを他のベンダーの名前空間に置き換えないでください。HotSwan は com.github.skydoves で公開されています。

2. ルートの build.gradle.kts で apply false を指定し、プラグインを一度だけ解決しつつ、適用をオプトインするモジュールに限定します。

   plugins {
       alias(libs.plugins.hotswan.compiler) apply false
   }
   

3. 各 Compose アプリモジュールの build.gradle.kts に適用します。

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.kotlin.compose)
       alias(libs.plugins.hotswan.compiler)
   }
   

4. 同じモジュールファイルで標準の DSL ブロックを設定します。hotSwanCompiler の大文字の S は識別子の一部です。

   hotSwanCompiler {
       enabled = true
       debugOnly = true
   }
   

   debugOnly = true がデフォルトであり、本番環境でのルールです。リリースビルドには HotSwan の変換を含めてはいけません。

5. Gradle を同期します。 ビルドでエラーなくプラグインが解決されるはずです。ビルドのプラグイン一覧（./gradlew :app:buildEnvironment または IDE の Gradle ツールウィンドウ）を確認し、プラグインが適用されていることを確認します。

6. View -> Tool Windows -> HotSwan から HotSwan ツールウィンドウを開きます。 Start をクリックします。ステータスインジケーターが READY に変わるはずです。

7. 通常どおり Run アクションでアプリを実行します。 アプリのプロセスが接続されると、ツールウィンドウのステータスが READY から WATCHING に変わります。

8. 本体のみを編集して保存します。 composable 関数本体内の色またはテキストを変更し、ファイルを保存します。変更は 1 秒以内にデバイスに反映されるはずです。ナビゲーション、スクロール位置、remember の値はそのまま維持されます。

9. 変更が反映されない場合は、Gradle の設定を変更する前に、以下のトラブルシューティングチェックリストを確認してください。

パターン

パターン：本番環境の安全性のため debugOnly true を設定する

// WRONG
hotSwanCompiler {
    enabled = true
}
// WRONG because: omitting `debugOnly = true` allows the HotSwan transformations to attach to release
// builds. They are diagnostic-only and MUST NOT ship in production.

// RIGHT
hotSwanCompiler {
    enabled = true
    debugOnly = true
}

パターン：DSL ブロック名の大文字の S を正確に指定する

// WRONG
hotswanCompiler {
    enabled = true
    debugOnly = true
}
// WRONG because: the extension is hotSwanCompiler with a capital S in the middle. Lowercase will
// not resolve and Gradle reports an unknown extension.

// RIGHT
hotSwanCompiler {
    enabled = true
    debugOnly = true
}

パターン：ルートでは apply false を指定し、モジュールでは alias(...) を使う

// WRONG (root build.gradle.kts)
plugins {
    alias(libs.plugins.hotswan.compiler)
}
// WRONG because: applying at the root project triggers the compiler plugin everywhere, including
// modules without Compose. Use apply false at the root and alias(...) inside each Compose module.

// RIGHT (root build.gradle.kts)
plugins {
    alias(libs.plugins.hotswan.compiler) apply false
}

// RIGHT (app/build.gradle.kts; Compose module)
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.hotswan.compiler)
}

hotSwanCompiler {
    enabled = true
    debugOnly = true
}

パターン：ソースレベルで HotSwan に依存しない

// WRONG
import com.github.skydoves.compose.hotswan.runtime.HotReloadable

@HotReloadable
@Composable
fun Greeting() { Text("Hello") }
// WRONG because: HotSwan is a build-time and IDE-time tool. Production code must not import
// HotSwan runtime classes or annotations; the Gradle plugin attaches transformations during
// compilation without requiring source-level coupling.

// RIGHT
@Composable
fun Greeting() { Text("Hello") }

パターン：標準の 3 ファイル構成（そのまま貼り付け可能）

# gradle/libs.versions.toml
[plugins]
hotswan-compiler = { id = "com.github.skydoves.compose.hotswan.compiler", version = "1.2.10" }

// build.gradle.kts (root)
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.hotswan.compiler) apply false
}

// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.hotswan.compiler)
}

hotSwanCompiler {
    enabled = true
    debugOnly = true
}

トラブルシューティング

• Run の後、ステータスが READY のまま変わらない。 デバイスが接続されていません。adb devices を実行して、デバイスまたはエミュレーターが一覧に表示されることを確認します。USB を再接続するか、エミュレーターを再起動してください。
• ステータスが WATCHING なのに、保存しても再読み込みされない。 構造的な変更（パラメーター、コンストラクター、インターフェイス、インライン関数、新しいリソース ID）を保存しています。変更の境界を特定するには、../understanding-hot-reload-limits/SKILL.md を参照してください。
• 再読み込みは発生するが、状態が失われる。 変更によってティア 2（コンポジションのリセット）またはティア 3（Activity.recreate()）の再コンポジションが発生しています。利用可能になり次第、状態保持に関する関連スキルを参照してください。
• hotSwanCompiler { ... } ブロックを解決できない。 プラグインを追加した後に Gradle が同期されていません。再同期し、モジュールで Kotlin 2.0 以降が有効な Kotlin バージョンになっていること、およびエイリアスが libs.versions.toml のエントリと一致することを確認してください。

必須ルール

• 必須： debugOnly = true を設定してください。HotSwan の変換は診断専用であり、リリースビルドに含めてはなりません。
• 必須： Gradle プラグインは Compose モジュールにのみ適用してください。ルートプロジェクトでは apply false を指定し、Compose 以外のモジュールが変換されないようにしてください。
• 禁止： ソースコードから HotSwan のクラスに依存してはなりません。アノテーションやランタイムのインポートは使用しないでください。HotSwan はビルド時および IDE で使用するツールであり、本番コードは純粋なままにしてください。
• 禁止： HotSwan を古い Compose Compiler と併用してはなりません。HotSwan を追加する前に、Kotlin 2.0 以降では org.jetbrains.kotlin.plugin.compose が適用されていることを確認してください。
• 必須： libs.versions.toml で HotSwan のバージョンを固定し、プロジェクト内のすべての Compose モジュールで同じバージョンを使うようにしてください。最新の検証済みバージョンは 1.2.10 です。バージョンを固定する前に、より新しい安定版がないか hotswan.dev/docs/releases を確認してください。
• 推奨： 手動のホットリロードに慣れ、MCP 経由で Claude に編集・再読み込み・スクリーンショットのサイクルを実行させたい場合は、HotSwan と関連スキルである AI イテレーションループ（../iterating-with-ai-and-mcp/SKILL.md）を組み合わせてください。

検証

• ./gradlew :app:buildEnvironment の出力に、適用済みプラグインとして com.github.skydoves.compose.hotswan.compiler が含まれている。
• Run でアプリを起動した後、HotSwan のツールウィンドウのステータスが WATCHING と表示される。
• コンポーザブル内の Text の色を変更してファイルを保存すると、1 秒以内にデバイス上の色が変わる。
• remember の値、スクロール位置、ナビゲーションのバックスタックが変更後も維持される。
• リリースビルド（./gradlew :app:assembleRelease）に HotSwan の変換が含まれていない。debugOnly = true が設定されていることを確認するか、dexdump でリリースの dex を調べ、HotSwan が挿入したヘルパークラスがないことを確認してください。
• モジュール内の本番ソースファイルが com.github.skydoves.compose.hotswan.* シンボルをインポートしていない（grep -R "com.github.skydoves.compose.hotswan" src/main/ の検索結果が 0 件）。

参考資料

• HotSwan の JetBrains Marketplace プラグイン：https://plugins.jetbrains.com/plugin/30551-compose-hotswan/
• HotSwan のリリース（最新の安定版の正式な情報源）：https://hotswan.dev/docs/releases
• HotSwan のドキュメントポータル（skydoves/compose-hotswan-web）：https://github.com/skydoves/compose-hotswan-web
• HotSwan の Gradle 設定ドキュメント：https://github.com/skydoves/compose-hotswan-web（`/docs/gradle-configuration` 内）
• Compose Compiler Gradle プラグイン（Kotlin 2.0 以降）：https://developer.android.com/jetpack/androidx/releases/compose-compiler
• ホットリロードで対応できる変更と再ビルドが必要な変更の境界については、関連スキル ../understanding-hot-reload-limits/SKILL.md を参照してください。