Настройка проекта 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/JS Gradle также поддерживает объявления зависимостей для определенных наборов исходных файлов в разделе kotlin скрипта сборки.

kotlin {
    sourceSets["main"].dependencies {
        implementation("org.example.myproject", "1.1.0")
    }
}

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

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

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

dependencies {
    testImplementation(kotlin("test-js"))
}

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test-js'
}

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

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

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

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

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

Для запуска проектов Kotlin/JS, нацеленных на Node.js, задача run является псевдонимом для задачи nodeRun (которая также доступна в проектах Kotlin multiplatform).

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

./gradlew run

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

./gradlew run --continuous

или

./gradlew run -t

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

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

Плагин Kotlin/JS 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/JS 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.

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/JS Gradle также поддерживает загрузчики CSS и стилей webpack'a CSS и стилей. Хотя все параметры можно изменить, напрямую модифицировав файлы конфигурации webpack, используемые для сборки проекта, наиболее часто используемые настройки доступны непосредственно из файла build.gradle(.kts).

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

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

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

В качестве альтернативы, вы можете добавить поддержку 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/distribution в корне проекта.

Чтобы установить другое местоположение для файлов дистрибутива проекта, добавьте блок 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"
}

Обратите внимание, что это не повлияет на выходные данные webpacked в build/distributions.

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

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

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

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

Вы можете добавить пользовательские записи в package.json проекта через Gradle DSL. Для добавления пользовательских полей в ваш 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. Это известная проблема, обходной путь представлен здесь.