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

Среды выполнения

Проекты Kotlin/JS могут использовать две разные среды выполнения:

• Браузер для клиентской работы в браузере

• Node.js для запуска JavaScript-кода вне браузера, например, для серверной работы.

Для определения целевой среды выполнения для проекта Kotlin/JS добавьте раздел js со значением browser {} или nodejs {}.

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

Инструкция binaries.executable() явно указывает Kotlin-компилятору на создание исполняемых .js файлов. Это поведение по умолчанию при использовании текущего Kotlin/JS-компилятора, но инструкция явным образом требуется, если вы работаете с Kotlin/JS IR-компилятором или установили kotlin.js.generate.executable.default=false в вашем gradle.properties. В этих случаях пропуск binaries.executable() заставит компилятор генерировать только внутренние Kotlin-библиотечные файлы, которые могут использоваться другими проектами, но не выполняться самостоятельно. (Это, как правило, быстрее, чем создание исполняемых файлов, и может быть оптимизацией при работе с нелистовыми модулями вашего проекта.)

Плагин Kotlin/JS автоматически настраивает свои задачи для работы с выбранной средой. Это включает в себя загрузку и установку необходимой среды и зависимостей для запуска и тестирования приложения. Это позволяет разработчикам собирать, запускать и тестировать простые проекты без дополнительной настройки. Для проектов, ориентированных на Node.js, также есть возможность использования существующей установки Node.js. Узнайте, как использовать предварительно установленную Node.js.

Зависимости

Как и любые другие Gradle-проекты, проекты Kotlin/JS поддерживают традиционные Gradle декларации зависимостей в разделе dependencies файла сборки.

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

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

Плагин Kotlin Multiplatform Gradle также поддерживает объявление зависимостей для определенных наборов исходного кода в разделе kotlin файла сборки.

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

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

Обратите внимание, что не все библиотеки, доступные для языка программирования Kotlin, доступны при нацеливании на JavaScript: можно использовать только библиотеки, содержащие артефакты для Kotlin/JS.

Если используемая вами библиотека имеет зависимости от пакетов npm, Gradle автоматически разрешит эти транзитивные зависимости.

kotlin {
    sourceSets {
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test")) // This brings all the platform dependencies automatically
            }
        }
    }
}

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

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

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

запуск задачи

Плагин Kotlin/JS предоставляет задачу jsRun, которая позволяет запускать чистые проекты Kotlin/JS без дополнительной настройки.

Для запуска проектов Kotlin/JS в браузере, эта задача является псевдонимом для задачи browserDevelopmentRun (которая также доступна в проектах Kotlin multiplatform). Она использует webpack-dev-server для предоставления ваших JavaScript-артефактов. Если вы хотите настроить конфигурацию, используемую webpack-dev-server, например, изменить порт, на котором работает сервер, используйте файл конфигурации webpack.

Для запуска проектов Kotlin/JS, нацеленных на Node.js, используйте задачу jsRun, которая является псевдонимом для задачи nodeRun.

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

./gradlew jsRun

Чтобы автоматически запускать повторную сборку вашего приложения после внесения изменений в исходные файлы, используйте функцию непрерывной сборки Gradle: непрерывная сборка

./gradlew jsRun --continuous

или

./gradlew jsRun -t

После успешной сборки вашего проекта webpack-dev-server автоматически обновит страницу браузера.

задача тестирования

Плагин Kotlin Multiplatform Gradle автоматически настраивает инфраструктуру тестирования для проектов. Для проектов браузера он загружает и устанавливает инструмент тестирования Karma вместе с другими необходимыми зависимостями; для проектов Node.js используется фреймворк тестирования Mocha.

Плагин также предоставляет полезные функции тестирования, например:

• Генерация карт исходного кода

• Генерация отчётов о тестировании

• Результаты выполнения тестов в консоли

Для запуска тестов браузера плагин использует 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

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

Обратите внимание, что плагин Kotlin Multiplatform Gradle не устанавливает эти браузеры автоматически, а только использует те, которые доступны в среде выполнения. Если вы выполняете тесты Kotlin/JS на сервере непрерывной интеграции, например, убедитесь, что браузеры, с которыми вы хотите проводить тестирование, установлены.

Если вы хотите пропустить тесты, добавьте строку enabled = false в testTask.

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

Для запуска тестов выполните стандартную задачу жизненного цикла check:

./gradlew check

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

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

Сборка webpack

kotlin.js.webpack.major.version=4

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

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

./gradlew browserProductionWebpack

CSS

Подключаемый модуль Kotlin Multiplatform Gradle также поддерживает загрузчики CSS и стилей webpack. Все параметры можно изменить, непосредственно отредактировав файлы конфигурации webpack, используемые для сборки проекта, но наиболее часто используемые параметры доступны непосредственно в файле build.gradle(.kts).

Чтобы включить поддержку CSS в проекте, установите параметр cssSupport.enabled в файле Gradle build в блоке commonWebpackConfig. Эта конфигурация также включена по умолчанию при создании нового проекта с помощью мастера.

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

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

Кроме того, вы можете добавить поддержку CSS независимо для webpackTask, runTask, и testTask.

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

browser {
    webpackTask {
        cssSupport {
            it.enabled.set(true)
        }
    }
    runTask {
        cssSupport {
            it.enabled.set(true)
        }
    }
    testTask {
        useKarma {
            // ...
            webpackConfig.cssSupport {
                it.enabled.set(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

Для проектов Kotlin/JS, нацеленных на Node.js, плагин автоматически загружает и устанавливает среду Node.js на хосте. Вы также можете использовать существующую установку Node.js, если она у вас есть.

rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin> {
    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootExtension>().download = false
    // or true for default behavior
}
 

rootProject.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin) {
    rootProject.extensions.getByType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootExtension).download = false
}

Yarn

Для загрузки и установки объявленных зависимостей во время сборки, плагин управляет собственным экземпляром менеджера пакетов Yarn. Он работает без дополнительной конфигурации, но вы можете настроить его или использовать Yarn, уже установленный на вашем хосте.

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

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

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

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
}

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
}

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
}

Директория назначения дистрибутива

По умолчанию результаты сборки проекта Kotlin/JS находятся в директории /build/dist/<targetName>/<binaryName> в корне проекта.

Чтобы установить другое местоположение для файлов дистрибутива проекта, добавьте блок distribution внутри browser в скрипте сборки и присвойте значение свойству directory. После выполнения задачи сборки проекта, Gradle сохранит выходной пакет в этом месте вместе с ресурсами проекта.

kotlin {
    js {
        browser {
            distribution {
                directory = File("$projectDir/output/")
            }
        }
        binaries.executable()
        // ...
    }
}

kotlin {
    js {
        browser {
            distribution {
                directory = file("$projectDir/output/")
            }
        }
        binaries.executable()
        // ...
    }
}

Имя модуля

Чтобы изменить имя JavaScript модуля (который генерируется в build/js/packages/myModuleName), включая соответствующие файлы .js и .d.ts, используйте параметр moduleName:

js {
    moduleName = "myModuleName"
}

Обратите внимание, что это не влияет на результат работы webpack в build/dist.

Настройка package.json

Файл package.json содержит метаданные пакета JavaScript. Популярные реестры пакетов, такие как npm, требуют, чтобы все опубликованные пакеты содержали такой файл. Они используют его для отслеживания и управления публикациями пакетов.

Плагин Kotlin Multiplatform Gradle автоматически генерирует package.json для проектов Kotlin/JS во время сборки. По умолчанию файл содержит важную информацию: имя, версию, лицензию и зависимости, а также некоторые другие атрибуты пакета.

Помимо базовых атрибутов пакета, package.json может определять поведение проекта JavaScript, например, определяя доступные скрипты для выполнения.

Вы можете добавить пользовательские записи в package.json проекта с помощью DSL Gradle. Чтобы добавить пользовательские поля в свой package.json, используйте функцию customField в блоке компиляции packageJson:

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

При сборке проекта этот код добавит следующий блок в файл package.json:

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

Узнайте больше о написании файлов package.json для реестра npm в документации npm.

Устранение неполадок

При сборке проекта Kotlin/JS с использованием Kotlin 1.3.xx вы можете столкнуться с ошибкой Gradle, если одна из ваших зависимостей (или любая транзитивная зависимость) была скомпилирована с использованием Kotlin 1.4 или более поздней версии: Could not determine the dependencies of task ':client:jsTestPackageJson'. / Cannot choose between the following variants. Это известная проблема, обходной путь приведен здесь.