Настройка проекта 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, доступны при использовании JavaScript: можно использовать только библиотеки, которые содержат артефакты для 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')
}

задача run

Плагин 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 автоматически обновит страницу браузера.

задача test

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

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

• Генерация source map

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

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

Для запуска тестов браузера плагин по умолчанию использует Headless Chrome. Вы также можете выбрать другой браузер для запуска тестов, добавив соответствующие записи в раздел useKarma скрипта сборки:

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

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

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

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

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

./gradlew check

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

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

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

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

webpackTask {
   cssSupport.enabled = true
}
runTask {
   cssSupport.enabled = true
}
testTask {
   useKarma {
      // . . .
      webpackConfig.cssSupport.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. Здесь вы можете указать список 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'
}

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. Это известная проблема, обходное решение предлагается здесь.