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

Kotlin/JSプロジェクトはビルドシステムとしてGradleを使用します。開発者がKotlin/JSプロジェクトを簡単に管理できるように、JavaScript開発に特有のルーチンを自動化するヘルパータスクとプロジェクト構成ツールを提供するkotlin.multiplatform Gradleプラグインを用意しています。

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

Gradleプロジェクトにorg.jetbrains.kotlin.multiplatformプラグインを手動で適用するには、build.gradle(.kts)ファイルに以下を記述します。

KotlinGroovy

kotlin

plugins {
    kotlin("multiplatform") version "2.3.0"
}

groovy

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.3.0'
}

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

groovy

kotlin {
    // ...
}

kotlin {}ブロック内では、以下の側面を管理できます。

ターゲット実行環境: ブラウザまたはNode.js
ES2015機能のサポート: クラス、モジュール、ジェネレーター
出力の粒度の設定
TypeScript宣言ファイルの生成
プロジェクトの依存関係: Mavenおよびnpm
実行構成
テスト構成
バンドルおよびブラウザプロジェクト用のCSSサポート
ターゲットディレクトリおよびモジュール名
プロジェクトのpackage.jsonファイル

実行環境

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

ブラウザ：ブラウザでのクライアントサイドスクリプト用
Node.js：ブラウザ外でJavaScriptコードを実行するため（例：サーバーサイドスクリプト）

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

groovy

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

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

これは通常、実行可能ファイルを作成するよりも高速であり、プロジェクトの末端ではない（non-leaf）モジュールを扱う際の最適化として利用できます。

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

ES2015機能のサポート

Kotlinは、以下のES2015機能に対して実験的（Experimental）なサポートを提供しています。

モジュール：コードベースを簡素化し、メンテナンス性を向上させます。
クラス：OOPの原則を取り入れることができ、よりクリーンで直感的なコードになります。
ジェネレーター：サスペンド関数のコンパイルに使用され、最終的なバンドルサイズを改善し、デバッグを容易にします。

build.gradle(.kts)ファイルにes2015コンパイルターゲットを追加することで、サポートされているすべてのES2015機能を一度に有効にできます。

kotlin

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

ES2015 (ECMAScript 2015, ES6) の詳細については、公式ドキュメントを参照してください。

出力の粒度の設定

コンパイラがプロジェクト内の.jsファイルをどのように出力するかを選択できます。

モジュールごとに1つ（One per module）。デフォルトでは、JSコンパイラはコンパイル結果として、プロジェクトのモジュールごとに個別の.jsファイルを出力します。
プロジェクトごとに1つ（One per project）。gradle.propertiesファイルに以下の行を追加することで、プロジェクト全体を単一の.jsファイルにコンパイルできます。
none
```
kotlin.js.ir.output.granularity=whole-program // デフォルトは 'per-module'
```
ファイルごとに1つ（One per file）。Kotlinファイルごとに1つ（ファイルにエクスポートされた宣言が含まれている場合は2つ）のJavaScriptファイルを生成する、よりきめ細かい出力を設定できます。ファイルごとのコンパイルモードを有効にするには：
1. プロジェクトでES2015機能をサポートするために、es2015をコンパイルターゲットとして設定します。
2. gradle.propertiesファイルに以下の行を追加します。
  none
```
kotlin.js.ir.output.granularity=per-file // デフォルトは 'per-module'
```

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()
    }
}

定義ファイルは、build/js/packages/<package_name>/kotlinディレクトリに、対応するwebpack前のJavaScriptコードと一緒に生成されます。

依存関係

他のGradleプロジェクトと同様に、Kotlin/JSプロジェクトはビルドスクリプトのdependencies {}ブロックでの伝統的なGradle依存関係宣言をサポートしています。

KotlinGroovy

kotlin

dependencies {
    implementation("org.example.myproject", "1.1.0")
}

groovy

dependencies {
    implementation 'org.example.myproject:1.1.0'
}

Kotlin Multiplatform Gradleプラグインは、ビルドスクリプトのkotlin {}ブロック内で特定のソースセットに対する依存関係宣言もサポートしています。

KotlinGroovy

kotlin

kotlin {
    sourceSets {
        val jsMain by getting {
            dependencies {
                implementation("org.example.myproject:1.1.0")
            }
        }
    }
}

groovy

kotlin {
    sourceSets {
        jsMain {
            dependencies {
                implementation 'org.example.myproject:1.1.0'
            }
        }
    }
}

Kotlinプログラミング言語で利用可能なすべてのライブラリがJavaScriptをターゲットにできるわけではありません。Kotlin/JS用のアーティファクトを含むライブラリのみが使用可能です。

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

Kotlin標準ライブラリ

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

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

KotlinGroovy

kotlin

kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // すべてのプラットフォーム依存関係を自動的に取り込みます
        }
    }
}

groovy

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // すべてのプラットフォーム依存関係を自動的に取り込みます
            }
        }
    }
}

npm依存関係

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

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

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

KotlinGroovy

kotlin

dependencies {
    implementation(npm("react", "> 14.0.0 <=16.9.0"))
}

groovy

dependencies {
    implementation npm('react', '> 14.0.0 <=16.9.0')
}

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

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

none

kotlin.js.yarn=false

通常の依存関係以外に、Gradle DSLから使用できる3つの依存関係タイプがあります。それぞれの依存関係タイプをいつ使用するのが最適かについては、npmからリンクされている公式ドキュメントを参照してください。

devDependencies: devNpm(...) 経由
optionalDependencies: optionalNpm(...) 経由
peerDependencies: peerNpm(...) 経由

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

runタスク

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

ブラウザでKotlin/JSプロジェクトを実行する場合、このタスクはbrowserDevelopmentRunタスク（Kotlinマルチプラットフォームプロジェクトでも利用可能）のエイリアスです。これは、JavaScriptアーティファクトを提供するために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テストランナーとその他の必要な依存関係をダウンロードしてインストールします。Node.jsプロジェクトの場合、Mochaテストフレームワークが使用されます。

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

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

ブラウザテストを実行するために、プラグインはデフォルトでHeadless Chromeを使用します。ビルドスクリプトのuseKarma {}ブロック内に対応するエントリを追加することで、テストを実行する別のブラウザを選択することもできます。

groovy

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プラグインは、これらのブラウザを自動的にインストールするわけではなく、実行環境で利用可能なブラウザのみを使用することに注意してください。例えば、継続的インテグレーション（CI）サーバーでKotlin/JSテストを実行している場合は、テスト対象のブラウザがインストールされていることを確認してください。

テストをスキップしたい場合は、testTask {}にenabled = falseという行を追加します。

groovy

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

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

bash

./gradlew check

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

groovy

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

Karma構成

Kotlin Multiplatform Gradleプラグインは、ビルド時にKarma構成ファイルを自動的に生成します。これには、build.gradle(.kts)のkotlin.js.browser.testTask.useKarma {}ブロックからの設定が含まれます。ファイルはbuild/js/packages/projectName-test/karma.conf.jsにあります。 Karmaが使用する構成を調整するには、プロジェクトのルートにあるkarma.config.dというディレクトリ内に追加の構成ファイルを配置します。このディレクトリ内のすべての.js構成ファイルが取得され、ビルド時に生成されたkarma.conf.jsに自動的にマージされます。

Karmaのすべての構成機能は、Karmaのドキュメントで詳しく説明されています。

webpackによるバンドル

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

webpackのバージョン

Kotlin Multiplatformプラグインはwebpack 5を使用します。

バージョン1.5.0より前のプラグインで作成されたプロジェクトがある場合は、プロジェクトのgradle.propertiesに以下の行を追加することで、それらのバージョンで使用されていたwebpack 4に一時的に戻すことができます。

none

kotlin.js.webpack.major.version=4

webpackタスク

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

outputFileName - webpack出力ファイルの名前。webpackタスクの実行後、<projectDir>/build/dist/<targetName>に生成されます。デフォルト値はプロジェクト名です。
output.libraryTarget - webpack出力のモジュールシステム。 Kotlin/JSプロジェクトで利用可能なモジュールシステムの詳細を確認してください。デフォルト値はumdです。

groovy

webpackTask {
    outputFileName = "mycustomfilename.js"
    output.libraryTarget = "commonjs2"
}

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

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プラグインにはbrowserDevelopmentWebpackおよびbrowserProductionWebpack Gradleタスクが含まれています。

browserDevelopmentWebpackは開発用アーティファクトを作成します。これらはサイズは大きいですが、作成にかかる時間は短いです。そのため、活発な開発中にはbrowserDevelopmentWebpackタスクを使用してください。
browserProductionWebpackは、生成されたアーティファクトにデッドコード削除（Dead Code Elimination）を適用し、結果のJavaScriptファイルを最小化（minify）します。これには時間がかかりますが、サイズがより小さい実行可能ファイルが生成されます。そのため、本番環境での使用に向けてプロジェクトを準備する際にはbrowserProductionWebpackタスクを使用してください。

開発用または本番用のそれぞれのアーティファクトを取得するには、これらのタスクのいずれかを実行します。生成されたファイルは、別途指定しない限り、build/distで利用可能になります。

bash

./gradlew browserProductionWebpack

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

CSS

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

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

KotlinGroovy

kotlin

browser {
    commonWebpackConfig {
        cssSupport {
            enabled.set(true)
        }
    }
}

groovy

browser {
    commonWebpackConfig {
        cssSupport {
            it.enabled = true
        }
    }
}

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

KotlinGroovy

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を使用します。ここでは、モードを定義するKotlinWebpackCssRulesのリストと、includeおよびexcludeパターンを指定できます。

Node.js

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

Node.js設定の構成

各サブプロジェクトに対してNode.js設定を構成したり、プロジェクト全体に対して設定したりできます。

例えば、特定のサブプロジェクトのNode.jsバージョンを設定するには、build.gradle(.kts)ファイルのそのGradleブロックに以下の行を追加します。

KotlinGroovy

kotlin

project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
    project.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec>().version = "your Node.js version"
}

groovy

project.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin) {
    project.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec).version = "your Node.js version"
}

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

KotlinGroovy

kotlin

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

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 = "your Node.js version"
}

NodeJsRootPluginクラスを使用してプロジェクト全体のNode.js設定を構成することは非推奨となり、最終的にサポートが終了します。

プリインストールされたNode.jsの使用

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

プリインストールされたNode.jsインスタンスを使用するには、build.gradle(.kts)ファイルに以下の行を追加します。

KotlinGroovy

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)に以下の行を追加します。

KotlinGroovy

kotlin

rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> {
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension>().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.YarnRootExtension).download = false
}

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

kotlin-js-storeによるバージョンロックはKotlin 1.6.10以降で利用可能です。

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

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

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

KotlinGroovy

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)を以下のように更新します。

KotlinGroovy

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依存関係をインストールする

デフォルトで--ignore-scriptsを使用してnpm依存関係をインストールする機能は、Kotlin 1.6.10以降で利用可能です。

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

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

KotlinGroovy

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>ディレクトリに置かれます。

Kotlin 1.9.0以前は、デフォルトの配信ターゲットディレクトリは/build/distributionsでした。

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

KotlinGroovy

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オプションを使用します。

groovy

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ドキュメントを参照してください。

Dokkaを実行する

出力形式

取得

操作と演算子

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

実行環境 ​

ES2015機能のサポート ​

出力の粒度の設定 ​

TypeScript宣言ファイル（`d.ts`）の生成

依存関係 ​

Kotlin標準ライブラリ ​

npm依存関係 ​

runタスク ​

testタスク ​

Karma構成 ​

webpackによるバンドル ​

webpackのバージョン ​

webpackタスク ​

webpack構成ファイル ​

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

CSS ​

Node.js ​

Node.js設定の構成 ​

プリインストールされたNode.jsの使用 ​

Yarn ​

Yarnの追加機能：.yarnrc ​

プリインストールされたYarnの使用 ​

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

yarn.lockが更新されたことの報告 ​

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

配信ターゲットディレクトリ ​

モジュール名 ​

package.jsonのカスタマイズ ​

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

実行環境

ES2015機能のサポート

出力の粒度の設定

依存関係

Kotlin標準ライブラリ

npm依存関係

runタスク

testタスク

Karma構成

webpackによるバンドル

webpackのバージョン

webpackタスク

webpack構成ファイル

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

CSS

Node.js

Node.js設定の構成

プリインストールされたNode.jsの使用

Yarn

Yarnの追加機能：.yarnrc

プリインストールされたYarnの使用

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

yarn.lockが更新されたことの報告

デフォルトで --ignore-scripts を使用してnpm依存関係をインストールする

配信ターゲットディレクトリ

モジュール名

package.jsonのカスタマイズ