Skip to content

Kotlin/JSプロジェクトのセットアップ ​

Kotlin/JSプロジェクトでは、ビルドシステムとしてGradleを使用します。開発者がKotlin/JSプロジェクトを簡単に管理できるように、JavaScript開発で一般的なルーティン作業を自動化するヘルパータスクと、プロジェクト設定ツールを提供するkotlin.multiplatform Gradleプラグインが用意されています。

このプラグインは、npmまたはYarnパッケージマネージャーを使用してバックグラウンドでnpm依存関係をダウンロードし、webpackを使用してKotlinプロジェクトからJavaScriptバンドルをビルドします。依存関係の管理や設定の調整は、その大部分をGradleビルドファイルから直接行うことができ、完全な制御が必要な場合は自動生成された設定をオーバーライドすることも可能です。

build.gradle(.kts)ファイル内でorg.jetbrains.kotlin.multiplatformプラグインを手動でGradleプロジェクトに適用できます。

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}

Kotlin Multiplatform Gradleプラグインを使用すると、ビルドスクリプトのkotlin {}ブロック内でプロジェクトのさまざまな側面を管理できます。

groovy
kotlin {
    // ...
}

kotlin {}ブロック内では、以下の項目を設定・管理できます。

実行環境 ​

Kotlin/JSプロジェクトは、2つの異なる実行環境をターゲットにできます。

  • ブラウザ: ブラウザ内でのクライアントサイドスクリプティング用
  • Node.js: サーバーサイドスクリプティングなど、ブラウザ外でJavaScriptコードを実行するため用

Kotlin/JSプロジェクトのターゲット実行環境を定義するには、内部にbrowser {}またはnodejs {}を含んだjs {}ブロックを追加します。

kotlin
kotlin {
    js {
        browser {
        }
        binaries.executable()
    }
}

binaries.executable()命令は、実行可能な.jsファイルを出力するようKotlinコンパイラに明示的に指示します。binaries.executable()を省略した場合、コンパイラはKotlin内部ライブラリファイルのみを生成します。これは他のプロジェクトからは使用できますが、単体で実行することはできません。

これは通常、実行可能ファイルを作成するよりも高速であり、プロジェクトの非末端(リーフ以外)モジュールを扱う際の最適化となる場合があります。

Kotlin Multiplatformプラグインは、選択された環境で動作するようにタスクを自動的に設定します。これには、アプリケーションの実行およびテストに必要な環境と依存関係のダウンロードおよびインストールが含まれます。これにより、開発者は追加の設定なしでシンプルなプロジェクトをビルド、実行、テストできます。また、既存のインストール環境を使用するオプションもあります。詳細はインストール済みNode.jsの使用を参照してください。

ECMAScriptターゲットの設定 ​

Kotlin/JSは、ECMAScript標準のES5、ES2015、およびES2020バージョン用のJavaScriptを生成できます。ターゲット環境でサポートされている最新のバージョンを選択してください。

  • es5は、古いJavaScript環境との互換性を提供し、デフォルトのターゲットです。
  • es2015は、以下を含むES2015機能のサポートを有効にします。
    • コードベースをシンプルにし、保守性を向上させるモジュール。
    • OOP原則を取り入れ、よりクリーンで直感的なコードを実現するクラス。
    • 最終的なバンドルサイズを改善し、デバッグを容易にするsuspend関数のコンパイル用ジェネレーター。
    • JavaScriptコードのインライン化。
  • es2020には、サポートされているすべてのES2015機能が含まれ、コンパイラが生成されたJavaScriptコードでECMAScript 2020機能を使用できるようになります。例えば、KotlinのLong値をJavaScriptのBigInt値にコンパイルします。

ECMAScriptターゲットを設定するには、build.gradle(.kts)ファイルでtargetプロパティを設定します。例えば、ES2020をターゲットにするには次のようにします。

kotlin
tasks.withType<KotlinJsCompile>().configureEach {
    compilerOptions {
        target = "es2020"
    }
}

詳細は、ES5、ES2015、およびES2020の各標準仕様を参照してください。

出力粒度の設定 ​

プロジェクト内でコンパイラが.jsファイルを出力する方法を選択できます。

  • モジュールごと(One per module): デフォルトでは、JSコンパイラはコンパイル結果としてプロジェクトのモジュールごとに別々の.jsファイルを出力します。

  • プロジェクトごと(One per project): gradle.propertiesファイルに次の行を追加することで、プロジェクト全体を単一の.jsファイルにコンパイルできます。

    properties
    # Default: per-module
    kotlin.js.ir.output.granularity=whole-program
  • ファイルごと(One per file): Kotlinファイルごとに1つ(ファイルにエクスポートされた宣言が含まれている場合は2つ)のJavaScriptファイルを生成する、より細かい粒度の出力を設定できます。ファイルごとのコンパイルモードを有効にするには、次のようにします。

    1. プロジェクトでES2015機能をサポートするために、コンパイルターゲットとしてes2015またはes2020を設定します。

    2. gradle.propertiesファイルに次の行を追加します。

      properties
      # Default: per-module
      kotlin.js.ir.output.granularity=per-file
Experimental

TypeScript型定義ファイル(`d.ts`)の生成

Kotlin/JSコンパイラは、KotlinコードからTypeScript定義を生成できます。これらの定義は、ハイブリッドアプリケーションで作業する際に、JavaScriptツールやIDEによって次のような目的で使用されます。

  • オートコンプリートの提供
  • 静的解析ツールのサポート
  • JavaScriptおよびTypeScriptプロジェクトへのKotlinコード追加の簡素化

TypeScript定義の生成は、特にビジネスロジックを共有するユースケースにおいて価値があります。

コンパイラは、@JsExportでマークされたトップレベルの宣言を収集し、.d.tsファイルにTypeScript定義を自動生成します。

TypeScript定義を生成するには、Gradleビルドファイルで明示的に設定する必要があります。build.gradle.ktsファイルのjs {}ブロック内にgenerateTypeScriptDefinitions()関数を追加します。

kotlin
kotlin {
    js {
        binaries.executable()
        browser {
        }
        generateTypeScriptDefinitions()
    }
}

生成された定義は、対応する未webpackのJavaScriptコードと共にbuild/js/packages/<package_name>/kotlinディレクトリに出力されます。

依存関係 ​

依存関係を宣言するには、build.gradle(.kts)ファイルのjsMainソースセット内にあるdependencies {}ブロックを使用します。

kotlin
kotlin {
    sourceSets {
        jsMain {
            dependencies {
                implementation("org.example.myproject:1.1.0")
            }
        }
    }
}
groovy
kotlin {
    sourceSets {
        jsMain {
            dependencies {
                implementation 'org.example.myproject:1.1.0'
            }
        }
    }
}

依存関係として使用できるのは、Kotlin/JS用のアーティファクトを含むライブラリのみです。依存関係を解決するには、build.gradle(.kts)ファイルのrepositories {}ブロックで、Gradleがそれらを検索するリポジトリを宣言します。例えば次のようになります。

kotlin
repositories {
    mavenCentral()
}

追加するライブラリがnpmのパッケージに依存している場合、Gradleはそれらの推移的依存関係も自動的に解決します。

Kotlin標準ライブラリ ​

標準ライブラリへの依存関係は自動的に追加されます。標準ライブラリのバージョンは、Kotlin Multiplatformプラグインのバージョンと同じになります。

マルチプラットフォームテスト用には、kotlin.test APIが利用可能です。マルチプラットフォームプロジェクトを作成する場合、commonTestに単一の依存関係を追加することで、すべてのソースセットにテスト依存関係を追加できます。

kotlin
kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // プラットフォーム固有の依存関係をすべて自動的に導入します
        }
    }
}
groovy
kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // プラットフォーム固有の依存関係をすべて自動的に導入します
            }
        }
    }
}

npm依存関係 ​

JavaScriptの世界において、依存関係を管理する最も一般的な方法はnpmです。npmはJavaScriptモジュールの最大のパブリックリポジトリを提供しています。

Kotlin Multiplatform Gradleプラグインを使用すると、他の依存関係を宣言するのとまったく同じように、Gradleビルドスクリプト内でnpm依存関係を宣言できます。

npm依存関係を宣言するには、依存関係宣言内のnpm()関数にその名前とバージョンを渡します。npmのセマンティックバージョニング(semver)構文に基づいて、1つまたは複数のバージョン範囲を指定することもできます。

kotlin
kotlin {
    sourceSets {
        jsMain {
            dependencies {
                implementation(npm("core-js", "^3.38.1"))
            }
        }
    }
}
groovy
kotlin {
    sourceSets {
        jsMain {
            dependencies {
                implementation npm('core-js', '^3.38.1')
            }
        }
    }
}

デフォルトでは、プラグインはYarnパッケージマネージャーの独立したインスタンスを使用して、npm依存関係をダウンロードおよびインストールします。追加設定なしでそのまま動作しますが、特定のニーズに合わせて調整することも可能です。

Yarnの代わりに、npmパッケージマネージャーを直接使用してnpm依存関係を扱うこともできます。パッケージマネージャーとしてnpmを使用するには、gradle.propertiesファイルで次のプロパティを設定します。

none
kotlin.js.yarn=false

通常の依存関係の他に、Gradle DSLから使用できる依存関係の種類がさらに3つあります。各種類の依存関係をどのような場合に使用するのが最適かについての詳細は、npmの公式ドキュメントを参照してください。

npm依存関係がインストールされたら、KotlinからJSを呼び出すで説明されているように、コード内でそのAPIを使用できます。

runタスク ​

Kotlin Multiplatform Gradleプラグインは、追加の設定なしで純粋なKotlin/JSプロジェクトを実行できるjsBrowserDevelopmentRunタスクを提供します。

ブラウザでKotlin/JSプロジェクトを実行する場合、このタスクはbrowserDevelopmentRunタスク(Kotlinマルチプラットフォームプロジェクトでも使用可能)のエイリアスとなります。これは、JavaScriptアーティファクトを提供(serve)するためにwebpack-dev-serverを使用します。 サーバーが実行されるポートの調整など、webpack-dev-serverで使用される設定をカスタマイズしたい場合は、webpack設定ファイルを使用してください。

Node.jsをターゲットとするKotlin/JSプロジェクトを実行する場合は、nodeRunタスクのエイリアスであるjsNodeDevelopmentRunタスクを使用します。

プロジェクトを実行するには、標準ライフサイクルのjsBrowserDevelopmentRunタスク、またはそれが対応するエイリアスを実行します。

bash
./gradlew jsBrowserDevelopmentRun

ソースファイルに変更を加えた後にアプリケーションの再ビルドを自動的にトリガーするには、Gradleの継続的ビルド(continuous build)機能を使用します。

bash
./gradlew jsBrowserDevelopmentRun --continuous

または

bash
./gradlew jsBrowserDevelopmentRun -t

プロジェクトのビルドが成功すると、webpack-dev-serverは自動的にブラウザページをリフレッシュします。

testタスク ​

Kotlin Multiplatform Gradleプラグインは、プロジェクトのテストインフラストラクチャを自動的にセットアップします。必要なテストランナーやその他の依存関係をダウンロードしてインストールします。

ブラウザプロジェクトの場合、Karmaテストランナーと新しいブラウザテスト用DSLのいずれかを選択できます。Node.jsプロジェクトの場合は、Mochaテストフレームワークが利用可能です。

プラグインは、次のような便利なテスト機能も提供します。

  • ソースマップの生成
  • テストレポートの生成
  • コンソールでのテスト実行結果の表示

Karma ​

Karmaプロジェクトは非推奨(deprecated)となりました。新機能の追加やバグ修正は予定されていません。ブラウザテストの代替手段として、新しいブラウザテスト用DSLをお試しください。

Karmaテストランナーを設定するには、build.gradle(.kts)ファイルのブラウザのtestTask内にuseKarma {}ブロックを追加します。例えば、特定のブラウザに対してテストを実行するには、次のように記述します。

kotlin
kotlin {
    js {
        browser {
            testTask {
                useKarma {
                    useIe()
                    useSafari()
                    useFirefox()
                    useChrome()
                    useChromeCanary()
                    useChromeHeadless()
                    usePhantomJS()
                    useOpera()
                }
            }
        }
        binaries.executable()
        // ...
    }
}

または、gradle.propertiesファイルでブラウザのテストターゲットを追加することもできます。

text
kotlin.js.browser.karma.browsers=firefox,safari

これにより、すべてのモジュールに対するブラウザのリストを定義した上で、特定のモジュールのビルドファイルで個別のブラウザを追加することができます。

Kotlin Multiplatform Gradleプラグインは、ビルド時にbuild/js/packages/projectName-test/karma.conf.jsにKarma設定ファイルを自動生成します。このファイルには、ビルドファイルのuseKarma {}ブロックで設定した内容が含まれます。

プロジェクトのルートにあるkarma.config.dディレクトリ内に追加の設定ファイルを配置することもできます。このディレクトリ内のすべての.js設定ファイルは読み込まれ、ビルド時に生成されたkarma.conf.jsに自動的にマージされます。

Karmaの設定の詳細については、Karmaのドキュメントを参照してください。

Experimental

ブラウザテスト用DSL

Kotlinは、ブラウザ環境でKotlin/JSテストを実行するための実験的なDSLを提供しています。これは特定の技術に依存しない(technology-agnostic)ように設計されています。現在の実装では、内部で以下のツールが使用されています。

  • Playwright: ブラウザドライバおよび配布マネージャーとして機能し、Chromium、Firefox、およびWebKit(Safari)ブラウザエンジンをサポートします。
  • Mocha: テストランナーとして機能します。
  • webpack: バンドラーとして機能します(今後のリリースでViteに置き換えられる予定です)。

新しいブラウザテスト用DSLを試すには、Kotlin/JSターゲットのbrowser {}内にオプトインのtest {}ブロックを追加します。

kotlin
import org.jetbrains.kotlin.gradle.ExperimentalJsTestDsl
import kotlin.time.Duration.Companion.seconds

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                // kotlin.Durationを使用してすべてのランナーのデフォルトタイムアウトを設定
                timeout = 30.seconds
                // Gradleプロバイダーを使用してヘッドレスモードを設定
                headless = providers
                    .environmentVariable("IS_IN_CI")
                    .map { it.toBoolean() }
                    .orElse(false)
                // カスタムChromiumランナーを有効化して設定
                chromium("chromium-no-webgl2") {
                    // このランナーのデフォルトタイムアウトをオーバーライド
                    timeout = 10.seconds

                    // Chromium固有の追加起動引数
                    launchArgs.add("--disable-webgl2")
                }
                // Firefoxランナーを有効化
                firefox()
                // WebKit (Safari) テストランナーを有効化
                webkit()
                // カスタムWebKitランナーを有効化して設定
                webkit("headful") {
                    headless = false
                }
            }
        }
    }
}

新しいブラウザテスト用DSLの設定の詳細については、Kotlin/JSでのテストの実行を参照してください。

Node.js ​

Node.jsプロジェクトの場合、Kotlin Multiplatform GradleプラグインはMochaテストフレームワークを自動的にセットアップします。

Node.jsテストランナーで使用される環境変数を指定するには(例えば、テストに外部情報を渡したり、パッケージ解決を微調整したりするため)、ビルドファイル内のtestTask {}ブロック内でキーと値のペアを指定してenvironment()関数を使用します。

kotlin
kotlin {
    js {
        nodejs {
            testTask {
                environment("key", "value")
            }
        }
    }
}

テストの実行 ​

デフォルトでは、Kotlin Multiplatform Gradleプラグインはブラウザテストの実行にHeadless Chromeを使用します。ブラウザはプラグインにバンドルされていないため、テストランナーによってブラウザが見つからない場合の処理が異なります。

  • Karmaの場合、プラグインがテストを実行できるように、テスト対象のブラウザがマシンにすでにインストールされている必要があります。CI(継続的インテグレーション)サーバー上でKotlin/JSテストを実行する場合は、テスト対象のブラウザがそこにもインストールされていることを確認してください。
  • 新しいブラウザテスト用DSLの場合、プラグインは初回実行時にplaywright installコマンドを使用して必要なブラウザをインストールします。Playwrightがこれらのブラウザの配置場所を管理し、ローカルにインストールされているブラウザは使用しません。

テストを実行するには、標準ライフサイクルのcheckタスクを実行します。

bash
./gradlew check

テストをスキップしたい場合は、ビルドファイル内のtestTask {}ブロックでテストを無効にします。

kotlin
kotlin {
    js {
        browser {
            testTask {
                enabled.set(false)
            }
        }
        binaries.executable()
        // ...
    }
}

webpackバンドル ​

ブラウザターゲットに対して、Kotlin Multiplatform Gradleプラグインは広く知られているwebpackモジュールバンドラーを使用します。

webpackタスク ​

最も一般的なwebpackの調整は、Gradleビルドファイルのkotlin.js.browser.webpackTask {}設定ブロックから直接行うことができます。

  • mainOutputFileName − webpackでバンドルされた出力ファイルの名前。webpackタスクの実行後、<projectDir>/build/kotlin-webpack/<targetName>/<binaryName>に生成されます。デフォルト値はプロジェクト名です。
  • output.libraryTarget − webpackで出力されるモジュールシステム。Kotlin/JSプロジェクトで利用可能なモジュールシステムの詳細を参照してください。デフォルト値はumdです。
groovy
webpackTask {
    mainOutputFileName = "mycustomfilename.js"
    output.libraryTarget = "commonjs2"
}

また、バンドル、実行、テストタスクで使用する共通のwebpack設定をcommonWebpackConfig {}ブロックで構成することもできます。

webpack設定ファイル ​

Kotlin Multiplatform Gradleプラグインは、ビルド時に標準のwebpack設定ファイルを自動的に生成します。これはbuild/js/packages/projectName/webpack.config.jsに配置されます。

webpack設定をさらに調整したい場合は、プロジェクトのルートにあるwebpack.config.dというディレクトリ内に追加の設定ファイルを配置します。プロジェクトのビルド時に、すべての.js設定ファイルがbuild/js/packages/projectName/webpack.config.jsファイルに自動的にマージされます。 例えば、新しいwebpackローダーを追加するには、webpack.config.dディレクトリ内の.jsファイルに次のように記述します。

この場合、設定オブジェクトはグローバルオブジェクトのconfigになります。スクリプト内でこれを変更する必要があります。

groovy
config.module.rules.push({
    test: /\.extension$/,
    loader: 'loader-name'
});

webpackのすべての設定機能については、その公式ドキュメントで詳しく説明されています。

実行可能ファイルのビルド ​

webpackを介して実行可能なJavaScriptアーティファクトをビルドするために、Kotlin Multiplatform GradleプラグインにはjsBrowserDevelopmentWebpackおよびjsBrowserProductionWebpack Gradleタスクが含まれています。

  • jsBrowserDevelopmentWebpackは、サイズは大きくなりますが短時間で作成できる開発用アーティファクトを作成します。そのため、アクティブな開発中はjsBrowserDevelopmentWebpackタスクを使用してください。
  • jsBrowserProductionWebpackは、生成されたアーティファクトにデッドコード削除(DCE: dead code elimination)を適用し、結果のJavaScriptファイルを軽量化(minify)します。時間はかかりますが、より小さなサイズの実行可能ファイルが生成されます。そのため、本番環境用にプロジェクトを準備する際はjsBrowserProductionWebpackタスクを使用してください。

開発用または本番用の各アーティファクトを取得するには、これらのタスクのいずれかを実行します。別途指定しない限り、生成されたファイルはbuild/kotlin-webpackに出力されます。

bash
./gradlew jsBrowserProductionWebpack

これらのタスクは、ターゲットが(binaries.executable()によって)実行可能ファイルを生成するように設定されている場合にのみ使用可能である点に注意してください。

build/dist/<targetName>/<binaryName>ディレクトリにディストリビューション(配布用成果物)を生成するには、代わりにjsBrowserDistributionタスクを実行します。

bash
./gradlew jsBrowserDistribution

このタスクは、プロジェクトのリソースを含むすぐに使用可能なディストリビューションを生成します。

CSS ​

Kotlin Multiplatform Gradleプラグインは、webpackのCSSローダーおよびstyleローダーもサポートしています。すべてのオプションは、プロジェクトのビルドに使用されるwebpack設定ファイルを直接変更することで変更できますが、最も一般的に使用される設定はbuild.gradle(.kts)ファイルから直接利用できます。

プロジェクトでCSSサポートを有効にするには、GradleビルドファイルのcommonWebpackConfig {}ブロックでcssSupport.enabledオプションを設定します。この設定は、ウィザードを使用して新しいプロジェクトを作成した場合、デフォルトでも有効になっています。

kotlin
browser {
    commonWebpackConfig {
        cssSupport {
            enabled.set(true)
        }
    }
}
groovy
browser {
    commonWebpackConfig {
        cssSupport {
            it.enabled = true
        }
    }
}

あるいは、webpackTask {}、runTask {}、およびtestTask {}に対して個別にCSSサポートを追加することもできます。

kotlin
browser {
    webpackTask {
        cssSupport {
            enabled.set(true)
        }
    }
    runTask {
        cssSupport {
            enabled.set(true)
        }
    }
    testTask {
        useKarma {
            // ...
            webpackConfig.cssSupport {
                enabled.set(true)
            }
        }
    }
}
groovy
browser {
    webpackTask {
        cssSupport {
            it.enabled = true
        }
    }
    runTask {
        cssSupport {
            it.enabled = true
        }
    }
    testTask {
        useKarma {
            // ...
            webpackConfig.cssSupport {
                it.enabled = true
            }
        }
    }
}

プロジェクトでCSSサポートを有効にすると、設定されていないプロジェクトからスタイルシートを使用しようとしたときに発生するModule parse failed: Unexpected character '@' (14:0)などの一般的なエラーを防ぐのに役立ちます。

cssSupport.modeを使用して、検出されたCSSの処理方法を指定できます。以下の値が使用可能です。

  • "inline"(デフォルト): スタイルはグローバルの<style>タグに追加されます。
  • "extract": スタイルは別ファイルに抽出されます。その後、HTMLページから読み込むことができます。
  • "import": スタイルは文字列として処理されます。これは、コードからCSSにアクセスする必要がある場合(val styles = require("main.css")など)に便利です。

同じプロジェクトで異なるモードを使用するには、cssSupport.rulesを使用します。ここでは、各ルールがモード、ならびにincludeおよびexcludeパターンを定義するKotlinWebpackCssRulesのリストを指定できます。

Node.js ​

Node.jsをターゲットとするKotlin/JSプロジェクトの場合、プラグインはホスト上にNode.js環境を自動的にダウンロードしてインストールします。既存のNode.jsインスタンスがある場合は、それを使用することもできます。

サブプロジェクトごとにNode.js設定を構成することも、プロジェクト全体に対して設定することもできます。

Node.jsバージョンの変更 ​

現在のデフォルトのNode.jsバージョンは24.16.0ですが、特定のサブプロジェクトで別のバージョンを使用することもできます。サブプロジェクトのbuild.gradle(.kts)ファイルに次の行を追加します。例えば次のようになります。

kotlin
project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
    project.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec>().version = "26.2.0"
}
groovy
project.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin) {
    project.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec).version = "26.2.0"
}

すべてのサブプロジェクトを含むプロジェクト全体に対してバージョンを設定するには、同じコードをallprojects {}ブロックに適用します。例えば次のようになります。

kotlin
allprojects {
    project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
        project.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec>().version = "26.2.0"
    }
}
groovy
allprojects {
    project.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin) {
        project.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec).version = "26.2.0"
    }
}

インストール済みNode.jsの使用 ​

Kotlin/JSプロジェクトをビルドするホストにNode.jsがすでにインストールされている場合、独自のNode.jsインスタンスをインストールする代わりに、それを使用するようにKotlin Multiplatform Gradleプラグインを設定できます。

インストール済みのNode.jsインスタンスを使用するには、build.gradle(.kts)ファイルに次の行を追加します。

kotlin
project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
    // デフォルトの動作にするには `true` に設定
    project.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec>().download = false
}
groovy
project.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin) {
    // デフォルトの動作にするには `true` に設定
    project.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec).download = false
}

Yarn ​

デフォルトでは、ビルド時に宣言された依存関係をダウンロードしてインストールするために、プラグインはYarnパッケージマネージャーの独自のインスタンスを管理します。追加設定なしでそのまま動作しますが、設定を調整したり、ホストにすでにインストールされているYarnを使用したりすることもできます。

追加のYarn機能: .yarnrc ​

追加のYarn機能を設定するには、プロジェクトのルートに.yarnrcファイルを配置します。ビルド時に自動的に読み込まれます。

例えば、npmパッケージにカスタムレジストリを使用するには、プロジェクトルートの.yarnrcという名前のファイルに次の行を追加します。

text
registry "http://my.registry/api/npm/"

.yarnrcの詳細については、Yarn公式ドキュメントを参照してください。

インストール済みYarnの使用 ​

Kotlin/JSプロジェクトをビルドするホストにYarnがすでにインストールされている場合、独自のYarnインスタンスをインストールする代わりに、それを使用するようにKotlin Multiplatform Gradleプラグインを設定できます。

インストール済みのYarnインスタンスを使用するには、build.gradle(.kts)に次の行を追加します。

kotlin
rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> {
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootEnvSpec>().download = false
    // デフォルトの動作にするには "true"
}
groovy
rootProject.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin) {
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootEnvSpec).download = false
}

kotlin-js-storeによるバージョンロック ​

プロジェクトルートのkotlin-js-storeディレクトリは、バージョンロックに必要なyarn.lockファイルを保持するために、Kotlin Multiplatform Gradleプラグインによって自動的に生成されます。ロックファイルは完全にYarnプラグインによって管理され、kotlinNpmInstall Gradleタスクの実行中に更新されます。

推奨されるプラクティスに従い、kotlin-js-storeとその内容をバージョン管理システムにコミットしてください。これにより、すべてのマシンでまったく同じ依存関係ツリーを使用してアプリケーションがビルドされることが保証されます。

必要に応じて、build.gradle(.kts)でディレクトリ名とロックファイル名の両方を変更できます。

kotlin
rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> {
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension>().lockFileDirectory =
        project.rootDir.resolve("my-kotlin-js-store")
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension>().lockFileName = "my-yarn.lock"
}
groovy
rootProject.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin) {
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension).lockFileDirectory =
        file("my-kotlin-js-store")
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension).lockFileName = 'my-yarn.lock'
}

ロックファイルの名前を変更すると、依存関係検査ツールがファイルを認識しなくなる場合があります。

yarn.lockの詳細については、Yarn公式ドキュメントを参照してください。

yarn.lockが更新されたことのレポート ​

Kotlin/JSには、yarn.lockファイルが更新された場合に通知できるGradle設定が用意されています。CIビルドプロセス中にyarn.lockがサイレントに変更された場合に通知を受け取りたい場合に、これらの設定を使用できます。

  • YarnLockMismatchReport: yarn.lockファイルの変更をどのようにレポートするかを指定します。以下のいずれかの値を使用できます。
    • FAIL: 対応するGradleタスクを失敗させます。これがデフォルトです。
    • WARNING: 変更に関する情報を警告ログに出力します。
    • NONE: レポートを無効にします。
  • reportNewYarnLock: 最近作成されたyarn.lockファイルについて明示的にレポートします。初回起動時に新しいyarn.lockファイルを生成するのが一般的な慣例であるため、デフォルトではこのオプションは無効になっています。このオプションを使用すると、ファイルがリポジトリにコミットされていることを確認できます。
  • yarnLockAutoReplace: Gradleタスクが実行されるたびに、yarn.lockを自動的に置き換えます。

これらのオプションを使用するには、build.gradle(.kts)を次のように更新します。

kotlin
import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnLockMismatchReport
import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension

rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> {
    rootProject.the<YarnRootExtension>().yarnLockMismatchReport =
        YarnLockMismatchReport.WARNING // NONE | FAIL
    rootProject.the<YarnRootExtension>().reportNewYarnLock = false // true
    rootProject.the<YarnRootExtension>().yarnLockAutoReplace = false // true
}
groovy
import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnLockMismatchReport
import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension

rootProject.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin) {
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension).yarnLockMismatchReport =
        YarnLockMismatchReport.WARNING // NONE | FAIL
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension).reportNewYarnLock = false // true
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension).yarnLockAutoReplace = false // true
}

デフォルトでの--ignore-scriptsを使用したnpm依存関係のインストール ​

侵害されたnpmパッケージからの悪意のあるコードの実行リスクを低減するために、Kotlin Multiplatform Gradleプラグインは、デフォルトでnpm依存関係のインストール中にライフサイクルスクリプトを実行しないようにしています。

build.gradle(.kts)に次の行を追加することで、ライフサイクルスクリプトの実行を明示的に有効にできます。

kotlin
rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> { 
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension>().ignoreScripts = false
}
groovy
rootProject.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin) {
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension).ignoreScripts = false
}

ディストリビューションターゲットディレクトリ ​

デフォルトでは、Kotlin/JSプロジェクトのビルド結果はプロジェクトルート内の/build/dist/<targetName>/<binaryName>ディレクトリに配置されます。

プロジェクトの配布ファイルの場所を別の場所に変更するには、ビルドスクリプトのbrowser {}ブロック内にdistribution {}ブロックを追加し、set()メソッドを使用してoutputDirectoryプロパティに値を設定します。プロジェクトのビルドタスクを実行すると、Gradleはプロジェクトのリソースと共に出力バンドルをこの場所に保存します。

kotlin
kotlin {
    js {
        browser {
            distribution {
                outputDirectory.set(projectDir.resolve("output"))
            }
        }
        binaries.executable()
        // ...
    }
}
groovy
kotlin {
    js {
        browser {
            distribution {
                outputDirectory = file("$projectDir/output")
            }
        }
        binaries.executable()
        // ...
    }
}

モジュール名 ​

対応する.jsおよび.d.tsファイルを含む、JavaScript モジュール(build/js/packages/myModuleNameに生成されます)の名前を調整するには、outputModuleNameオプションを使用します。

kotlin
kotlin {
    js {
        outputModuleName = "myModuleName"
    }
}

これはbuild/dist内のwebpackの出力には影響しないことに注意してください。

package.jsonのカスタマイズ ​

package.jsonファイルは、JavaScriptパッケージのメタデータを保持します。npmなどの一般的なパッケージレジストリでは、公開されるすべてのパッケージにこのようなファイルが含まれていることが求められます。これらはパッケージの公開を追跡および管理するために使用されます。

Kotlin Multiplatform Gradleプラグインは、ビルド時にKotlin/JSプロジェクト用のpackage.jsonを自動的に生成します。デフォルトでは、このファイルには名前、バージョン、ライセンス、依存関係、およびその他のパッケージ属性などの基本データが含まれています。

基本的なパッケージ属性だけでなく、package.jsonは実行可能なスクリプトの特定など、JavaScriptプロジェクトがどのように動作すべきかを定義することもできます。

Gradle DSLを介してプロジェクトのpackage.jsonにカスタムエントリを追加できます。package.jsonにカスタムフィールドを追加するには、コンパイルのpackageJsonブロック内でcustomField()関数を使用します。

kotlin
kotlin {
    js {
        compilations["main"].packageJson {
            customField("hello", mapOf("one" to 1, "two" to 2))
        }
    }
}

プロジェクトをビルドすると、このコードによってpackage.jsonファイルに次のブロックが追加されます。

json
"hello": {
    "one": 1,
    "two": 2
}

npmレジストリ向けのpackage.jsonファイルの記述の詳細については、npmのドキュメントを参照してください。