设置 Kotlin/JS 工程(Project)

执行环境

要为 Kotlin/JS 工程定义目标运行环境, 需要添加 js {} 代码段, 其中包含 browser {} 或 nodejs {}:

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

binaries.executable() 指令明确的指示 Kotlin 编译器输出可执行的 .js 文件. 使用当前的 Kotlin/JS 编译器时, 这是默认的行为, 但如果你使用 Kotlin/JS IR 编译器, 或者在 gradle.properties 文件中设置过 kotlin.js.generate.executable.default=false, 则需要明确的指定这条指令. 这些情况下, 省略 binaries.executable() 会导致编译器只生成 Kotlin-internal 库文件, 这些库文件可以被其他项目使用, 但不能独立运行.

支持 ES2015 功能

你可以向你的 build.gradle(.kts) 文件添加 es2015 编译目标, 一次性启用所有支持的 ES2015 功能:

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

依赖项目

与其他 Gradle 工程一样, Kotlin/JS 工程编译脚本的 dependencies {} 代码段内, 支持添加传统的 Gradle 依赖项目声明:

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

Kotlin Multiplatform Gradle 插件也支持在编译脚本的 kotlin {} 代码段中添加特定源代码集合(source set)的依赖项目声明:

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

Kotlin 标准库

对于跨平台的测试, 可以使用 kotlin.test API. 当你创建跨平台项目时, 你可以在 commonTest 中使用一个依赖项, 对所有的源代码集添加测试依赖项:

kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // 会自动引入所有的平台依赖项
        }
    }
}

npm 依赖项目

要声明一个 npm 依赖项目, 可以在一个依赖项目声明中使用 npm() 函数指定依赖项目的名称和版本. 也可以使用 npm semver 语法, 指定一个或多个版本范围.

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

你也可以通过 npm 包管理器直接使用 npm 依赖项. 要使用 npm 作为你的包管理器, 请在你的 gradle.properties 文件中, 设置以下属性:

kotlin.js.yarn=false

run 任务

Kotlin Multiplatform Gradle 插件提供了一个 jsRun 任务, 它可以运行你的纯 Kotlin/JS 工程, 无需额外的配置.

对于在浏览器内运行 Kotlin/JS 工程的情况, 这个是 browserDevelopmentRun 任务的一个别名(在 Kotlin 跨平台项目也可以使用). 它使用 webpack DevServer 来提供你的 JavaScript artifact. 如果你想要自定义 DevServer 的配置, 例如, 改变端口号, 请使用 webpack 配置文件.

对于在 Node.js 平台运行 Kotlin/JS 项目的情况, 请使用 jsRun 任务, 它是 nodeRun 任务的别名.

要运行一个工程, 请执行 Gradle 编译周期(lifecycle)中标准的 jsRun 任务, 或者运行它作为别名对应的真实的任务:

./gradlew jsRun

./gradlew jsRun --continuous

./gradlew jsRun -t

工程构建成功后, webpack-dev-server 会自动刷新浏览器页面.

test 任务

为了运行浏览器中的测试, 插件会默认使用 Headless Chrome. 你也可以选择其他浏览器来运行测试, 方法是在编译脚本的 useKarma {} 代码段中添加相应的设置:

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

或者你也可以在 gradle.properties 文件中添加测试的目标浏览器:

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

如果想要跳过测试, 可以在 testTask {} 代码段中添加 enabled = false 设置.

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

要运行测试, 请执行 Gradle 编译周期(lifecycle)中标准的 check 任务:

./gradlew check

如果要指定你的 Node.js 测试运行器使用的环境变量 (比如, 向你的测试代码传递外部信息, 或对包的解析进行微调), 可以在你的构建脚本的 testTask {} 代码段中使用 environment() 函数, 参数是键-值对:

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 文件中.

webpack 打包(Bundling)

webpack 版本

如果你的项目通过 plugin 1.5.0 以前版本创建, 那么可以在你的项目的 gradle.properties 文件中添加以下设置, 临时切换回这些版本使用的 webpack 4:

kotlin.js.webpack.major.version=4

webpack 任务

在 Gradle 编译脚本的 kotlin.js.browser.webpackTask {} 配置代码段中, 可以直接调整最常见的 webpack 配置:

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

还可以在 commonWebpackConfig {} 代码段中配置 webpack 的共通设置, 用于打包(bundling), 运行, 以及测试任务.

webpack 配置文件

Kotlin Multiplatform Gradle plugin 在构建时会自动生成一个标准的 webpack 配置文件. 位置是 build/js/packages/projectName/webpack.config.js.

如果还想对 webpack 配置进行进一步的调整, 请将你的额外的配置文件放在你的工程的 webpack.config.d 目录内. 编译你的工程时, 所有的 .js 配置文件都会被自动合并到 build/js/packages/projectName/webpack.config.js 文件内. 比如, 如果要添加一个新的 webpack loader, 请要把以下内容添加到 webpack.config.d 目录内的一个 .js 中:

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

构建可执行文件

要通过 webpack 编译可执行的 JavaScript artifact, Kotlin Multiplatform Gradle 插件包含 Gradle 任务 browserDevelopmentWebpack 和 browserProductionWebpack.

执行这两个任务可以分别得到开发模式和生产模式的 artifact 文件. 生成的文件会在 build/dist 目录下, 除非另有设置.

./gradlew browserProductionWebpack

注意, 只有在你的编译目标设置为生成可执行文件 (通过 binaries.executable()) 时, 这些任务才可用.

CSS

Kotlin Multiplatform Gradle 创建还支持 webpack 的 CSS 和 style 装载器. 虽然所有的选项都可以直接修改构建你的项目的 webpack 配置文件, 但最常用的方法是使用 build.gradle(.kts) 中直接可用的设定.

要在你的项目中打开 CSS 支持, 请在 Gradle 构建文件的 commonWebpackConfig {} 代码段中设置 cssSupport.enabled 选项. 通过 IDE 向导创建新工程时, 这个配置也会默认启用.

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

或者, 也可以单独对 webpackTask {}, runTask {}, 和 testTask {} 添加 CSS 支持:

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

对你的项目打开 CSS 支持, 有助于防止在未配置的项目中使用样式表时发生的常见错误, 比如 Module parse failed: Unexpected character '@' (14:0).

可以使用 cssSupport.mode 来指定 CSS 应该如何处理. 可选的设定值如下:

如果要对同一个项目使用不同的模式, 请使用 cssSupport.rules. 这里, 你可以指定一组 KotlinWebpackCssRules, 其中每一项定义一个 mode, 以及 include 和 exclude pattern.

Node.js

配置 Node.js 的设置

例如, 要对某个子项目设置 Node.js 版本, 请在你的 build.gradle(.kts) 文件中, 向它的 Gradle 代码块添加以下内容:

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

要对整个项目设置版本, 包括所有的子项目, 请将同样的代码添加到 allProjects {} 代码块:

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

使用已安装的 Node.js

要使用已安装的 Node.js, 请向 build.gradle(.kts) 文件添加以下内容:

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 的更多功能: .yarnrc

如果要配置 Yarn 的更多功能, 请将一个 .yarnrc 文件放在你的工程根目录. 编译时, 会自动使用它.

比如, 如果要对 npm 包使用一个自定义的仓库, 请将以下内容添加到工程根目录下的一个 .yarnrc 文件中:

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

关于 .yarnrc 文件的更多信息, 请参见 Yarn 官方文档.

使用已安装的 Yarn

要使用已安装的 Yarn, 请向 build.gradle(.kts) 文件添加以下内容:

rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> {
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension>().download = false
    // 默认设置为 "true"
}

通过 kotlin-js-store 锁定版本

项目根目录下的 kotlin-js-store 目录由 Kotlin Multiplatform Gradle 插件自动生成, 存储 yarn.lock 文件, 这个文件用来锁定版本. lock 文件完全由 Yarn plugin 管理, 并在 Gradle 任务 kotlinNpmInstall 执行时被更新.

为了遵循 Yarn 推荐的最佳实践, 请将 kotlin-js-store 和其中的内容提交到你的版本管理系统. 这样可以保证你的应用程序在所有的机器上都使用完全相同的依赖项目树来进行构建.

如果需要, 你可以在 build.gradle(.kts) 文件修改目录和 lock 文件名称:

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

关于 .yarnrc 文件的更多信息, 请参见 Yarn 官方文档.

报告 yarn.lock 的变更

Kotlin/JS 提供了 Gradle 设置, 可以通知你 yarn.lock 文件是否发生变更. 如果你想要在 CI 构建过程中 yarn.lock 发生变更时收到通知, 你可以使用这些设置:

要使用这些选项, 请更新 build.gradle(.kts) 文件:

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
}

默认使用 --ignore-scripts 安装 npm 依赖项

你可以明确的允许 Life Cycle 脚本执行, 方法是在 build.gradle(.kts) 中添加以下设定:

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

设置发布目录

默认设置下, Kotlin/JS 工程编译的输出在工程根目录下的 /build/dist/<targetName>/<binaryName> 目录内.

如果要为工程设置另外的发布位置, 请在编译脚本的 browser {} 代码段内, 添加 distribution {} 代码段, 在这里使用 set() 方法为 outputDirectory 属性设置一个值. 当你运行工程的构建任务时, Gradle 会将输出的 bundle 文件和工程的资源文件一起, 保存到这个位置.

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

模块名称

如果要调整 JavaScript 模块(module) 名称 (模块将被生成在 build/js/packages/myModuleName 路径), 包括对应的 .js 和 .d.ts 文件名称, 请使用 moduleName 选项:

js {
    moduleName = "myModuleName"
}

注意, 这个设置不会影响位于 build/dist 的 webpacked 输出.

自定义 package.json 文件

package.json 文件包含 JavaScript 包的元数据(metadata). 常用的包登记系统, 比如 npm, 要求所有发布的包带有这个文件. 包登记系统会使用这个文件来追踪和管理包的发布.

对 Kotlin/JS 工程, Kotlin Multiplatform Gradle 插件在构建时会自动生成 package.json. 这个文件默认会包含最基本的数据: 名称, 版本, 许可证, 依赖项目, 以及包的一些其他属性.

除了基本的包属性之外, package.json 还可以定义 JavaScript 包应该如何动作, 比如, 标识可以运行的脚本.

你可以通过 Gradle DSL 向工程的 package.json 文件添加自定义的内容. 要添加自定义的项目到你的 package.json 文件, 可以在编译任务的 packageJson 代码段中使用 customField() 函数:

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

构建工程时, 这段代码会向 package.json 文件添加以下内容:

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

关于如何为 npm 登记项目编写 package.json 文件, 详情请参见 npm 文档.

设置 Kotlin/JS 工程(Project)﻿

执行环境﻿

tip

支持 ES2015 功能﻿

依赖项目﻿

note

Kotlin 标准库﻿

npm 依赖项目﻿

run 任务﻿

test 任务﻿

配置 Karma﻿

webpack 打包(Bundling)﻿

webpack 版本﻿

webpack 任务﻿

webpack 配置文件﻿

note

构建可执行文件﻿

CSS﻿

Node.js﻿

配置 Node.js 的设置﻿

note

使用已安装的 Node.js﻿

Yarn﻿

Yarn 的更多功能: .yarnrc﻿

使用已安装的 Yarn﻿

通过 kotlin-js-store 锁定版本﻿

note

warning

报告 yarn.lock 的变更﻿

默认使用 --ignore-scripts 安装 npm 依赖项﻿

note

设置发布目录﻿

note

模块名称﻿

自定义 package.json 文件﻿

执行环境

支持 ES2015 功能

依赖项目

Kotlin 标准库

npm 依赖项目

run 任务

test 任务

配置 Karma

webpack 打包(Bundling)

webpack 版本

webpack 任务

webpack 配置文件

构建可执行文件

CSS

Node.js

配置 Node.js 的设置

使用已安装的 Node.js

Yarn

Yarn 的更多功能: .yarnrc

使用已安装的 Yarn

通过 kotlin-js-store 锁定版本

报告 yarn.lock 的变更

默认使用 --ignore-scripts 安装 npm 依赖项

设置发布目录

模块名称

自定义 package.json 文件