Настройка проекта Kotlin/JS

Стандартные библиотеки Kotlin

Зависимости от стандартной библиотеки добавляются автоматически. Версия стандартной библиотеки совпадает с версией плагина Kotlin Multiplatform.

Для многоплатформенных тестов доступен API kotlin.test. При создании многоплатформенного проекта можно добавить зависимости для тестирования во все исходные наборы с помощью одной зависимости в commonTest:

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

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

Зависимости npm

В мире JavaScript наиболее распространенный способ управления зависимостями — это npm. В нем находится крупнейший общедоступный репозиторий модулей JavaScript.

Плагин Gradle для Kotlin Multiplatform позволяет объявлять зависимости npm в скрипте сборки Gradle так же, как и любые другие зависимости.

Чтобы объявить зависимость npm, передайте ее имя и версию функции npm() внутри объявления зависимости. Также можно указать один или несколько диапазонов версий, используя синтаксис semver в npm.

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

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

По умолчанию плагин использует отдельный экземпляр менеджера пакетов Yarn для загрузки и установки зависимостей npm. Он работает без дополнительной настройки, но его можно настроить под конкретные задачи.

Кроме того, вместо этого можно напрямую работать с зависимостями npm с помощью менеджера пакетов npm. Чтобы использовать npm в качестве менеджера пакетов, задайте в файле gradle.properties следующее свойство:

kotlin.js.yarn=false

Помимо обычных зависимостей, из DSL Gradle можно использовать еще три типа зависимостей. Подробнее о том, когда лучше использовать каждый из типов, см. в официальной документации npm:

• devDependencies — с помощью devNpm(...),

• optionalDependencies — с помощью optionalNpm(...) и

• peerDependencies — с помощью peerNpm(...).

После установки зависимости npm ее API можно использовать в коде, как описано в разделе Вызов JS из Kotlin.

Karma

Чтобы настроить средство запуска тестов Karma, добавьте блок useKarma {} внутрь testTask браузера в файле build.gradle(.kts). Например, чтобы запускать тесты в определенных браузерах, используйте:

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

В качестве альтернативы можно добавить цели браузеров для тестирования в файл gradle.properties:

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

Это позволяет определить список браузеров для всех модулей, а затем добавить отдельные браузеры в файлы сборки конкретных модулей.

Плагин Gradle для Kotlin Multiplatform автоматически создает файл конфигурации Karma в build/js/packages/projectName-test/karma.conf.js во время сборки. Файл содержит настройки, заданные в блоке useKarma {} файла сборки.

Также можно поместить дополнительные файлы конфигурации в директорию karma.config.d в корне проекта. Все файлы конфигурации .js в этой директории будут обнаружены и автоматически объединены с файлом karma.conf.js, создаваемым во время сборки.

Подробнее о конфигурации Karma см. в документации Karma.

DSL для тестирования в браузере

Kotlin предлагает экспериментальный DSL для запуска тестов Kotlin/JS в браузере. Он разработан независимо от конкретных технологий. В текущей реализации используются следующие инструменты:

• Playwright служит драйвером браузера и менеджером дистрибутивов, поддерживающим движки браузеров Chromium, Firefox и WebKit (Safari).

• Mocha служит средством запуска тестов.

• webpack служит сборщиком пакетов (в будущих выпусках его заменит Vite).

Чтобы попробовать новый DSL для тестирования в браузере, добавьте блок test {} для целевого объекта Kotlin/JS внутрь browser {}:

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

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                // Configures the default timeout for all runners with kotlin.Duration
                timeout = 30.seconds
                // Configures headless mode using Gradle providers
                headless = providers
                    .environmentVariable("IS_IN_CI")
                    .map { it.toBoolean() }
                    .orElse(false)
                // Enables and configures a custom Chromium runner
                chromium("chromium-no-webgl2") {
                    // Overrides the default timeout for this runner
                    timeout = 10.seconds

                    // Chromium-specific extra launch argument
                    launchArgs.add("--disable-webgl2")
                }
                // Enables the Firefox runner
                firefox()
                // Enable WebKit (Safari) test runner
                webkit()
                // Enables and configures a custom WebKit runner
                webkit("headful") {
                    headless = false
                }
            }
        }
    }
}

Подробнее о настройке нового DSL для тестирования в браузере см. в разделе Запуск тестов в Kotlin/JS.

Node.js

Для проектов Node.js плагин Gradle для Kotlin Multiplatform автоматически настраивает фреймворк тестирования Mocha.

Чтобы указать переменные среды, используемые средствами запуска тестов Node.js (например, чтобы передать тестам внешнюю информацию или настроить разрешение пакетов), используйте функцию environment() с парой «ключ-значение» внутри блока testTask {} в файле сборки:

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

Запуск тестов

По умолчанию плагин Gradle для Kotlin Multiplatform использует Headless Chrome для запуска браузерных тестов. Плагин не включает браузеры в свой состав; средства запуска тестов по-разному обрабатывают отсутствие браузеров:

• При использовании Karma любой другой браузер должен быть установлен на вашем компьютере, чтобы плагин мог использовать его для запуска тестов. Если вы запускаете тесты Kotlin/JS на сервере непрерывной интеграции, убедитесь, что нужные браузеры установлены и там.

• При использовании нового DSL для тестирования в браузере плагин при первом запуске устанавливает необходимые браузеры с помощью команды playwright install. Playwright управляет расположением этих браузеров и не использует браузеры, установленные локально.

Чтобы запустить тесты, выполните стандартную задачу жизненного цикла check:

./gradlew check

Чтобы пропустить тесты, отключите их в блоке testTask {} файла сборки:

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

Задача webpack

Наиболее распространенные настройки webpack можно задать непосредственно в блоке конфигурации kotlin.js.browser.webpackTask {} файла сборки Gradle:

• mainOutputFileName − имя выходного файла webpack. Он будет создан в <projectDir>/build/kotlin-webpack/<targetName>/<binaryName> после выполнения задачи webpack. По умолчанию используется имя проекта.

• output.libraryTarget − система модулей для выходных файлов webpack. Подробнее о доступных системах модулей для проектов Kotlin/JS. По умолчанию используется значение umd.

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

Также можно настроить общие параметры webpack, используемые задачами сборки пакетов, запуска и тестирования, в блоке commonWebpackConfig {}.

Файл конфигурации webpack

Плагин Gradle для Kotlin Multiplatform автоматически создает стандартный файл конфигурации webpack во время сборки. Он находится в build/js/packages/projectName/webpack.config.js.

Чтобы дополнительно настроить webpack, поместите файлы конфигурации в директорию webpack.config.d в корне проекта. При сборке проекта все файлы конфигурации .js будут автоматически объединены в файл build/js/packages/projectName/webpack.config.js. Например, чтобы добавить новый загрузчик webpack, добавьте следующий код в файл .js в директории webpack.config.d:

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

Все возможности настройки webpack подробно описаны в его документации.

Сборка исполняемых файлов

Для создания исполняемых артефактов JavaScript с помощью webpack плагин Gradle для Kotlin Multiplatform предоставляет задачи Gradle jsBrowserDevelopmentWebpack и jsBrowserProductionWebpack.

• jsBrowserDevelopmentWebpack создает артефакты для разработки: они больше по размеру, но создаются быстро. Поэтому используйте задачи jsBrowserDevelopmentWebpack во время активной разработки.

• jsBrowserProductionWebpack применяет удаление неиспользуемого кода к созданным артефактам и минифицирует итоговый файл JavaScript. Это занимает больше времени, но позволяет получить исполняемые файлы меньшего размера. Поэтому используйте задачу jsBrowserProductionWebpack при подготовке проекта к эксплуатации.

Выполните одну из этих задач, чтобы получить соответствующие артефакты для разработки или эксплуатации. Созданные файлы будут доступны в build/kotlin-webpack, если не указано иное.

./gradlew jsBrowserProductionWebpack

Обратите внимание: эти задачи доступны только в том случае, если целевой объект настроен на создание исполняемых файлов (с помощью binaries.executable()).

Чтобы создать дистрибутив в директории build/dist/<targetName>/<binaryName>, выполните вместо этого задачу jsBrowserDistribution:

./gradlew jsBrowserDistribution

Эта задача создает готовый к использованию дистрибутив, включающий ресурсы проекта.

Изменение версии Node.js

В настоящее время версия Node.js по умолчанию — 24.16.0, но для конкретного подпроекта можно использовать другую версию. Добавьте следующие строки в файл build.gradle(.kts) подпроекта. Например:

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

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 {}. Например:

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

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

Если Node.js уже установлен на хост-компьютере, на котором вы собираете проекты Kotlin/JS, можно настроить плагин Kotlin Multiplatform Gradle так, чтобы он использовал эту версию Node.js, а не устанавливал собственную.

Чтобы использовать предварительно установленный экземпляр Node.js, добавьте следующие строки в файл build.gradle(.kts):

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
}

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
}

Дополнительные возможности Yarn: .yarnrc

Чтобы настроить дополнительные возможности Yarn, поместите файл .yarnrc в корневой каталог проекта. Во время сборки он будет автоматически обнаружен.

Например, чтобы использовать пользовательский реестр пакетов npm, добавьте следующую строку в файл с именем .yarnrc в корневом каталоге проекта:

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

Подробнее о .yarnrc см. в официальной документации Yarn.

Использование предварительно установленного Yarn

Если Yarn уже установлен на хост-компьютере, на котором вы собираете проекты Kotlin/JS, можно настроить плагин Kotlin Multiplatform Gradle так, чтобы он использовал эту версию 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.YarnRootEnvSpec>().download = false
    // "true" for default behavior
}

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 в корневом каталоге проекта автоматически создаётся плагином Kotlin Multiplatform Gradle для хранения файла yarn.lock, необходимого для фиксации версий. Файлом блокировки полностью управляет плагин Yarn; он обновляется при выполнении задачи Gradle kotlinNpmInstall.

В соответствии с рекомендуемой практикой добавьте kotlin-js-store и его содержимое в систему контроля версий. Это гарантирует, что приложение будет собираться с одним и тем же деревом зависимостей на всех компьютерах.

При необходимости можно изменить имя каталога и файла блокировки в build.gradle(.kts):

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

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 предоставляет настройки Gradle, которые могут уведомить вас об изменении файла yarn.lock. Эти настройки можно использовать, если вы хотите получать уведомления о незаметном изменении yarn.lock во время сборки CI:

• YarnLockMismatchReport определяет, как сообщать об изменениях файла yarn.lock. Можно использовать одно из следующих значений:

  • FAIL приводит к сбою соответствующей задачи Gradle. Это значение используется по умолчанию.

  • WARNING записывает сведения об изменениях в журнал предупреждений.

  • NONE отключает уведомления.

• reportNewYarnLock явно сообщает о недавно созданном файле yarn.lock. По умолчанию этот параметр отключён: обычно новый файл yarn.lock создаётся при первом запуске. Этот параметр можно использовать, чтобы убедиться, что файл добавлен в репозиторий.

• yarnLockAutoReplace автоматически заменяет yarn.lock при каждом запуске задачи Gradle.

Чтобы использовать эти параметры, обновите 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> {
    rootProject.the<YarnRootExtension>().yarnLockMismatchReport =
        YarnLockMismatchReport.WARNING // NONE | FAIL
    rootProject.the<YarnRootExtension>().reportNewYarnLock = false // true
    rootProject.the<YarnRootExtension>().yarnLockAutoReplace = false // true
}

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
}

Установка зависимостей npm с параметром --ignore-scripts по умолчанию

Чтобы снизить вероятность выполнения вредоносного кода из скомпрометированных пакетов npm, плагин Kotlin Multiplatform Gradle по умолчанию запрещает выполнение сценариев жизненного цикла при установке зависимостей npm.

Чтобы явно разрешить выполнение сценариев жизненного цикла, добавьте следующие строки в 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
}

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