Kotlin Compose Desktop 完全ガイド：開発から配布まで

2026年5月13日

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

Contents

1 概要と前提条件（Kotlin Compose Desktop の位置づけと準備）
- 1.1 Compose Desktop の位置づけ
- 1.2 開発前の必須・推奨環境
2 新規プロジェクト作成と最小サンプル（IntelliJ 起点 / Gradle 起点）
3 設計と実装の実務ポイント（ステート・リソース・ネイティブ連携）
4 テストと CI（UI テスト・ヘッドレス実行・GitHub Actions サンプル）
5 セキュリティと配布（JDK 同梱、コード署名、Notarization、CI 自動化）

スポンサードリンク

概要と前提条件（Kotlin Compose Desktop の位置づけと準備）

ここでは Compose Desktop の用途と、開発前に揃えるべき最低限の環境を説明します。業務アプリの導入判断や初期準備に使ってください。

Compose Desktop の位置づけ

Compose Multiplatform のデスクトップ実装として、Kotlin で宣言的 UI を記述できます。
Android 向け Compose とは API とライフサイクルが異なるため、コードの流用には注意が必要です。

開発前の必須・推奨環境

以下は開発を始める前に確認すべき要素です。実務ではこれらを基準に環境を固定してください。

JDK（推奨）: LTS 系 OpenJDK（例：Adoptium/Temurin の LTS）。jpackage を使う場合はその JDK に jpackage が含まれるか確認してください。
IDE（推奨）: IntelliJ IDEA の最新安定版（Community/Ultimate）。Kotlin と Compose プラグインの互換性を合わせます。
ビルド: Gradle（Kotlin DSL 推奨）と Gradle Wrapper の利用を推奨します。org.jetbrains.compose プラグインを利用してください。
OS/アーキテクチャ: x86_64 と Apple Silicon（arm64）両方での検証を行ってください。各 OS の署名要件を事前確認します。
その他: Git、CI（例: GitHub Actions）、コード署名証明書（配布時）、ネイティブツールチェイン（jpackage 等）。

新規プロジェクト作成と最小サンプル（IntelliJ 起点 / Gradle 起点）

まずは最小サンプルを動かして基盤を確認します。ここでは IntelliJ での手順と、手動で Gradle（Kotlin DSL）から作る手順を示します。

IntelliJ 起点の手順

IntelliJ の New Project で Compose テンプレートが使える場合はそれを利用すると最短です。テンプレートがないときは以下の手順で手動セットアップします。

File → New → Project を開き、Kotlin/JVM または Compose テンプレートを選びます。
Gradle を選択し、Kotlin DSL（.kts）を選びます。
プロジェクト作成後、Gradle タブから wrapper を確認し、存在しない場合は後述のコマンドで生成します。
Run 構成を作成する場合は、Run → Edit Configurations → "+" → "Application" を選択し、Main class に MainKt（トップレベル main の場合）を指定します。あるいは Gradle の Tasks → application → run を使う方法が簡単です。

注意点: IntelliJ とプロジェクトで使用する JDK を一致させてください。IDE 内の Project SDK と Gradle の toolchain/JAVA_HOME を揃えるとトラブルが減ります。

Gradle (Kotlin DSL) 起点の手順

コマンドラインで最小プロジェクトを作る手順と Gradle Wrapper の作成例です。プロジェクトで使う Gradle のバージョンはプラグイン互換性に合わせて選んでください。

# ディレクトリ作成
mkdir sample-app &amp;&amp; cd sample-app

# settings.gradle.kts を作成
cat &gt; settings.gradle.kts &lt;&lt;'EOF'
rootProject.name = &quot;sample-app&quot;
EOF

# Gradle Wrapper を作成 (ローカルに gradle がある場合)
gradle wrapper --gradle-version 8.6 --distribution-type all

# または Gradle が無い場合は IntelliJ の New Project で wrapper を生成してください

# ディレクトリ作成

mkdir sample-app && cd sample-app

# settings.gradle.kts を作成

cat > settings.gradle.kts <<'EOF'

rootProject.name = "sample-app"

EOF

# Gradle Wrapper を作成 (ローカルに gradle がある場合)

gradle wrapper --gradle-version 8.6 --distribution-type all

# または Gradle が無い場合は IntelliJ の New Project で wrapper を生成してください

build.gradle.kts の最小例（バージョンは各自で最新互換を確認してください）:

plugins {
    kotlin(&quot;jvm&quot;) version &quot;&lt;kotlin-version&gt;&quot; // 例: 1.9.0 (要確認)
    id(&quot;org.jetbrains.compose&quot;) version &quot;&lt;compose-plugin-version&gt;&quot; // ドキュメントを確認
    application
}

repositories {
    mavenCentral()
    maven(&quot;https://maven.pkg.jetbrains.space/public/p/compose/dev&quot;)
}

kotlin {
    jvm {
        withJava() // 一部のタスクやツールで必要になることがあります
    }
}

dependencies {
    implementation(compose.desktop.currentOs)
}

// application プラグインと compose プラグインで mainClass の指定が必要です。
// mainClass は Kotlin のトップレベル main の場合 &quot;MainKt&quot;（パッケージ付きで完全修飾）になります。
application {
    mainClass.set(&quot;MainKt&quot;)
}

compose.desktop {
    application {
        // Compose プラグイン側の mainClass 指定
        mainClass = &quot;MainKt&quot;
        nativeDistributions {
            packageName = &quot;sample-app&quot;
            packageVersion = &quot;0.1.0&quot;
            // targetFormats の設定はプラグインバージョン依存です。公式ドキュメントを必ず参照してください。
        }
    }
}

plugins {

kotlin("jvm") version "<kotlin-version>" // 例: 1.9.0 (要確認)

id("org.jetbrains.compose") version "<compose-plugin-version>" // ドキュメントを確認

application

}

repositories {

mavenCentral()

maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")

}

kotlin {

jvm {

withJava() // 一部のタスクやツールで必要になることがあります

}

dependencies {

implementation(compose.desktop.currentOs)

}

// application プラグインと compose プラグインで mainClass の指定が必要です。

// mainClass は Kotlin のトップレベル main の場合 "MainKt"（パッケージ付きで完全修飾）になります。

application {

mainClass.set("MainKt")

}

compose.desktop {

application {

// Compose プラグイン側の mainClass 指定

mainClass = "MainKt"

nativeDistributions {

packageName = "sample-app"

packageVersion = "0.1.0"

// targetFormats の設定はプラグインバージョン依存です。公式ドキュメントを必ず参照してください。

}

注記: 上記のプラグインと mainClass の扱いはバージョンにより挙動が変わります。プラグインの公式ドキュメントを確認してください（参照リンクは最後に記載。確認: 2026-05-13）。

最小サンプルの構成と実行

最小構成例と実行方法です。まずファイルを配置します。

src/main/kotlin/Main.kt
src/main/resources/（必要な資産）

Main.kt の例：

import androidx.compose.material.Button
import androidx.compose.material.MaterialTheme
import androidx.compose.material.Text
import androidx.compose.runtime.*
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application

@Composable
fun App() {
    var count by remember { mutableStateOf(0) }
    MaterialTheme {
        Button(onClick = { count++ }) {
            Text(&quot;Count: $count&quot;)
        }
    }
}

fun main() = application {
    Window(onCloseRequest = ::exitApplication, title = &quot;Sample&quot;) {
        App()
    }
}

import androidx.compose.material.Button

import androidx.compose.material.MaterialTheme

import androidx.compose.material.Text

import androidx.compose.runtime.*

import androidx.compose.ui.window.Window

import androidx.compose.ui.window.application

@Composable

fun App() {

var count by remember { mutableStateOf(0) }

MaterialTheme {

Button(onClick = { count++ }) {

Text("Count: $count")

}

fun main() = application {

Window(onCloseRequest = ::exitApplication, title = "Sample") {

App()

}

実行コマンドの例:

ローカル（ラッパー使用）: ./gradlew run
JAR 生成: ./gradlew jar
ネイティブパッケージ作成（プラグイン依存）: ./gradlew package など（タスク名はプラグイン・バージョンで異なります。公式ドキュメントを参照してください）

代表的な初期トラブルと調査手順

ここではよくある問題と調べ方を簡潔に示します。問題発生時の第一手順として使ってください。

依存解決エラー: repositories と plugin バージョンを確認し、./gradlew --refresh-dependencies を試してください。
JDK 不整合: JAVA_HOME と IntelliJ の Project SDK を合わせます。jpackage を使う場合は jpackage が存在する JDK を使用します。
リソース未読み込み: src/main/resources 配下に置き、パッケージ経路で読み込めるか確認します。

設計と実装の実務ポイント（ステート・リソース・ネイティブ連携）

UI 設計とステート管理は保守性とパフォーマンスに直結します。ここでは現場で役立つ具体例を示します。

ステート管理とアーキテクチャ

ロジック層と UI 層は責務を分離してください。StateFlow を用いた ViewModel パターンが扱いやすいです。

UI ローカル: remember / mutableStateOf を使用します。
ViewModel 層: Kotlin の StateFlow / MutableStateFlow で状態を保ち、Composable 側は collectAsState で購読します。
再描画抑制: derivedStateOf や remember を使って高コスト計算の再実行を避けます。

ViewModel の簡単な例:

import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.update

data class UiState(val count: Int = 0)

class MainViewModel {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow&lt;UiState&gt; = _uiState

    fun increment() {
        _uiState.update { it.copy(count = it.count + 1) }
    }
}

import kotlinx.coroutines.flow.MutableStateFlow

import kotlinx.coroutines.flow.StateFlow

import kotlinx.coroutines.flow.update

data class UiState(val count: Int = 0)

class MainViewModel {

private val _uiState = MutableStateFlow(UiState())

val uiState: StateFlow<UiState> = _uiState

fun increment() {

_uiState.update { it.copy(count = it.count + 1) }

}

Composable 側では collectAsState() を使って購読します。

リソース管理とネイティブ連携

画像やフォントは src/main/resources に置き、painterResource や Font で読み込みます。ファイルダイアログやシステムトレイは AWT を使うことが現実的です。

画像読み込み例:

import androidx.compose.ui.res.painterResource
import androidx.compose.foundation.Image

Image(painter = painterResource(&quot;images/logo.png&quot;), contentDescription = &quot;logo&quot;)

import androidx.compose.ui.res.painterResource

import androidx.compose.foundation.Image

Image(painter = painterResource("images/logo.png"), contentDescription = "logo")

ファイル選択の例（AWT の FileDialog を利用）:

import java.awt.FileDialog
import java.awt.Frame
import java.nio.file.Paths

fun openFile(): java.nio.file.Path? {
    val dialog = FileDialog(Frame(), &quot;Open&quot;, FileDialog.LOAD)
    dialog.isVisible = true
    val dir = dialog.directory ?: return null
    val file = dialog.file ?: return null
    return Paths.get(dir, file)
}

import java.awt.FileDialog

import java.awt.Frame

import java.nio.file.Paths

fun openFile(): java.nio.file.Path? {

val dialog = FileDialog(Frame(), "Open", FileDialog.LOAD)

dialog.isVisible = true

val dir = dialog.directory ?: return null

val file = dialog.file ?: return null

return Paths.get(dir, file)

}

ネイティブ連携はインターフェイスで切り出しておくと可搬性が上がります。

マルチプラットフォーム戦略

ロジックは commonMain、UI は desktopMain に分けることで共有可能性を高めます。expect/actual でプラットフォーム固有処理を切り出してください。

共通ロジックは副作用を持たないようにする。
プラットフォームごとの実装は actual に配置してテスト可能にする。

テストと CI（UI テスト・ヘッドレス実行・GitHub Actions サンプル）

品質を担保するため、ユニットテストと UI テストを CI に組み込みます。ヘッドレス実行や署名を自動化する実例を示します。

ユニットと UI テストの設定

ユニットテストは JUnit5 と kotlinx-coroutines-test で行います。Compose の UI テストは ui-test-junit4 等のテストアーティファクトを使います。バージョン互換性に注意し、公式ドキュメントを参照してください。

依存例（build.gradle.kts）:

dependencies {
    testImplementation(kotlin(&quot;test&quot;))
    testImplementation(&quot;org.jetbrains.kotlinx:kotlinx-coroutines-test:&lt;coroutines-version&gt;&quot;)
    testImplementation(&quot;org.jetbrains.compose.ui:ui-test-junit4:&lt;compose-version&gt;&quot;) // 変更あり。要確認
}

dependencies {

testImplementation(kotlin("test"))

testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:<coroutines-version>")

testImplementation("org.jetbrains.compose.ui:ui-test-junit4:<compose-version>") // 変更あり。要確認

}

Compose UI テストの簡単な例:

import androidx.compose.ui.test.junit4.createComposeRule
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.test.performClick
import org.junit.Rule
import org.junit.Test

class MainTest {
    @get:Rule
    val composeTestRule = createComposeRule()

    @Test fun counterIncrements() {
        composeTestRule.setContent { App() }
        composeTestRule.onNodeWithText(&quot;Count: 0&quot;).assertExists()
        composeTestRule.onNodeWithText(&quot;Count: 0&quot;).performClick()
        composeTestRule.onNodeWithText(&quot;Count: 1&quot;).assertExists()
    }
}

import androidx.compose.ui.test.junit4.createComposeRule

import androidx.compose.ui.test.onNodeWithText

import androidx.compose.ui.test.performClick

import org.junit.Rule

import org.junit.Test

class MainTest {

@get:Rule

val composeTestRule = createComposeRule()

@Test fun counterIncrements() {

composeTestRule.setContent { App() }

composeTestRule.onNodeWithText("Count: 0").assertExists()

composeTestRule.onNodeWithText("Count: 0").performClick()

composeTestRule.onNodeWithText("Count: 1").assertExists()

}

注記: テスト用のアーティファクト名や API はバージョン依存です。プラグインのドキュメントを確認してください（参照リンク参照、確認: 2026-05-13）。

ヘッドレス実行（Xvfb）とローカル確認

Linux CI で GUI テストを走らせるには Xvfb を使います。ローカルでも同じ手順で検証できます。

インストール: sudo apt-get install -y xvfb
実行例:

# 方法 A: Xvfb を手動で起動
Xvfb :99 -screen 0 1920x1080x24 &amp; export DISPLAY=:99
./gradlew test --no-daemon

# 方法 B: xvfb-run を使う
xvfb-run --auto-servernum --server-args='-screen 0 1920x1080x24' ./gradlew test

# 方法 A: Xvfb を手動で起動

Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99

./gradlew test --no-daemon

# 方法 B: xvfb-run を使う

xvfb-run --auto-servernum --server-args='-screen 0 1920x1080x24' ./gradlew test

GitHub Actions の簡易 CI サンプル

下は Linux ジョブで Xvfb を使いテストを実行する最小例です。実運用では OS ごとにジョブを分け、成果物の署名とアップロードを追加します。

name: CI

on: [push, pull_request]

jobs:
  test-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
      - name: Install Xvfb
        run: sudo apt-get update &amp;&amp; sudo apt-get install -y xvfb
      - name: Run tests (headless)
        run: |
          Xvfb :99 -screen 0 1920x1080x24 &amp; export DISPLAY=:99
          ./gradlew test --no-daemon

name: CI

on: [push, pull_request]

jobs:

test-linux:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Set up JDK

uses: actions/setup-java@v4

with:

distribution: temurin

java-version: '17'

- name: Install Xvfb

run: sudo apt-get update && sudo apt-get install -y xvfb

- name: Run tests (headless)

run: |

Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99

./gradlew test --no-daemon

Windows と macOS でのビルド・署名・Notarization は後述のセキュリティと配布セクションを参照してください。

セキュリティと配布（JDK 同梱、コード署名、Notarization、CI 自動化）

JDK の同梱やコード署名、Notarization は配布における重要項目です。ここで具体的な運用例と注意点を示します。

JDK と同梱の注意点

配布に JDK を同梱する際はライセンスを確認してください。OpenJDK（Adoptium/Temurin 等）は配布可能ですが、利用条件を確認する必要があります。jpackage を使う場合は、ビルドに使う JDK に jpackage が含まれることを確認してください。

推奨: LTS JDK を選び、ライセンスを明記する。
参考: 同梱しないスリムな配布や、自動アップデートで JRE を外部に依存する方法も検討します。

Windows の署名と CI 運用例

Windows では通常 SignTool を使った署名が行われます。商用配布では EV 証明書を用いると SmartScreen の信頼性が高まります。

PFX で署名する例:

# PowerShell（Windows ランナー）
# 事前に PFX を Secret に保管し、ランナー上に復号・インポートしてから署名
echo &quot;${{ secrets.WINDOWS_PFX_BASE64 }}&quot; | base64 --decode &gt; cert.pfx
$pwd = ConvertTo-SecureString &quot;${{ secrets.PFX_PASSWORD }}&quot; -AsPlainText -Force
Import-PfxCertificate -FilePath cert.pfx -CertStoreLocation Cert:\CurrentUser\My -Password $pwd

# signtool による署名
&amp; &quot;C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe&quot; sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a path\to\installer.exe

# PowerShell（Windows ランナー）

# 事前に PFX を Secret に保管し、ランナー上に復号・インポートしてから署名

echo "${{ secrets.WINDOWS_PFX_BASE64 }}" | base64 --decode > cert.pfx

$pwd = ConvertTo-SecureString "${{ secrets.PFX_PASSWORD }}" -AsPlainText -Force

Import-PfxCertificate -FilePath cert.pfx -CertStoreLocation Cert:\CurrentUser\My -Password $pwd

# signtool による署名

& "C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe" sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a path\to\installer.exe

タイムスタンプサーバーを指定して、署名にタイムスタンプを付与してください。タイムスタンプにより署名の有効性が将来も保たれます。

CI の運用上の注意:

PFX はリポジトリに置かず、CI の Secrets に格納します。
証明書アクセスは最小権限のジョブに限定し、マージ時のみ署名動作を許可するなどルールを設けます。

macOS の署名・Notarization と CI 運用例

macOS の配布では Developer ID による署名と Apple の Notarization（公証）が必要になることが多いです。Apple は notarytool（API キー方式）を推奨しています。

notarytool による notarize の概略:

`bash

スポンサードリンク

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

-Kotlin

comment コメントをキャンセル

: Kotlin

2024年最新・無料Kotlin学習教材まとめと始め方

Kotlinは無料教材が充実しており、2024年7月更新のリソースだけで初心者がHello, World!アプリを作成できます。

: Kotlin

Jetpack Compose と Coroutines の相性と実践的非同期 UI パターン

Jetpack Compose は UI 再コンポジションや副作用処理に Coroutines を採用し、非同期ロジックと状態管理を統一的に扱えます。本稿では LaunchedEffect・produceState・rememberCoroutineScope・ViewModel の StateFlow/SharedFlow など実践的パターンとコード例を紹介します。