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

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

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

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

KotlinGroovy

kotlin

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

groovy

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

KotlinマルチプラットフォームGradleプラグインを使用すると、ビルドスクリプトのkotlin {}ブロックでプロジェクトの各側面を管理できます。

groovy

kotlin {
    // ...
}

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

ターゲット実行環境 (Execution environments)：ブラウザまたはNode.js
ES2015機能のサポート (Support for ES2015 features)：クラス、モジュール、ジェネレーター
プロジェクトの依存関係 (Project dependencies)：Mavenおよびnpm
実行設定 (Run configuration)
テスト設定 (Test configuration)
ブラウザプロジェクトのバンドル (Bundling) とCSSサポート (CSS support)
ターゲットディレクトリ (Target directory) とモジュール名 (module name)
プロジェクトのpackage.jsonファイル (Project's package.json file)

実行環境

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

ブラウザ：ブラウザでのクライアントサイドスクリプティング用
Node.js：ブラウザ外でJavaScriptコードを実行するため。たとえば、サーバーサイドスクリプティング用です。

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

groovy

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

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

TIP

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

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

ES2015機能のサポート

Kotlinは、以下のES2015機能に対する実験的サポートを提供します。

コードベースを簡素化し、保守性を向上させるモジュール。
OOPの原則を組み込むことを可能にし、よりクリーンで直感的なコードをもたらすクラス。
最終的なバンドルサイズを改善し、デバッグに役立つsuspend functionsをコンパイルするためのジェネレーター。

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

kotlin

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

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

依存関係

他の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マルチプラットフォーム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'
            }
        }
    }
}

NOTE

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

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

Kotlin標準ライブラリ

標準ライブラリへの依存関係は自動的に追加されます。標準ライブラリのバージョンは、Kotlinマルチプラットフォームプラグインのバージョンと同じです。

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

KotlinGroovy

kotlin

kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // Brings all the platform dependencies automatically
        }
    }
}

groovy

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // Brings all the platform dependencies automatically
            }
        }
    }
}

npm依存関係

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

Kotlinマルチプラットフォーム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')
}

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

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

none

kotlin.js.yarn=false

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

devNpm(...)を介したdevDependencies、
optionalNpm(...)を介したoptionalDependencies、
peerNpm(...)を介したpeerDependencies。

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

runタスク

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

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

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

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

bash

./gradlew jsBrowserDevelopmentRun

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

bash

./gradlew jsBrowserDevelopmentRun --continuous

または

bash

./gradlew jsBrowserDevelopmentRun -t

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

testタスク

Kotlinマルチプラットフォーム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マルチプラットフォームGradleプラグインはこれらのブラウザを自動的にインストールしないことに注意してください。実行環境で利用可能なブラウザのみを使用します。たとえば、継続的インテグレーションサーバーで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マルチプラットフォーム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マルチプラットフォームGradleプラグインは、広く知られているwebpackモジュールバンドラーを使用します。

webpackバージョン

Kotlinマルチプラットフォームプラグインは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マルチプラットフォーム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ファイルに以下を追加します。

NOTE

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

groovy

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

webpackのすべての設定機能は、そのドキュメントに詳細に記載されています。

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

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

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

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

bash

./gradlew browserProductionWebpack

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

CSS

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

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"
}

NOTE

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

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

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

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

KotlinGroovy

kotlin

project.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin) {
    // Set to `true` for default behavior
    project.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec).download = false
}

groovy

project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
    // Set to `true` for default behavior
    project.the<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がすでにインストールされている場合、KotlinマルチプラットフォームGradleプラグインを、独自のYarnインスタンスをインストールする代わりに、既存のYarnを使用するように構成できます。

プリインストールされた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" for default behavior
}

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によるバージョンロック

NOTE

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

プロジェクトルートのkotlin-js-storeディレクトリは、バージョンロックに必要となるyarn.lockファイルを保持するために、Kotlinマルチプラットフォーム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'
}

DANGER

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

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::class.java) {
    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依存関係のインストール

NOTE

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

侵害されたnpmパッケージからの悪意のあるコードの実行の可能性を減らすために、Kotlinマルチプラットフォーム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()
        // ...
    }
}

モジュール名

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

groovy

js {
    moduleName = "myModuleName"
}

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

package.jsonのカスタマイズ

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

Kotlinマルチプラットフォーム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ドキュメントを参照してください。

基本型

ビルダー

Spring

Spring Boot を使用して RESTful Web サービスとデータベースを作成する

Java から Kotlin への移行ガイド

C 相互運用

Objective-C 相互運用

メモリ管理

参照とヒント

JS プラットフォーム向け Kotlin

Gradle

Dokka の実行

出力形式

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のカスタマイズ

Spring Boot を使用して RESTful Web サービスとデータベースを作成する

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のカスタマイズ ​

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のカスタマイズ