Настройка проекта 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.

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

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

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

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

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

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

The Kotlin/JS Gradle plugin also provides support for webpack's CSS and style loaders. While all options can be changed by directly modifying the webpack configuration files that are used to build your project, the most commonly used settings are available directly from the build.gradle(.kts) file.

To turn on CSS support in your project, set the cssSupport.enabled option in the Gradle build file in the commonWebpackConfig block. This configuration is also enabled by default when creating a new project using the wizard.

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

Alternatively, you can add CSS support independently for webpackTask, runTask, and testTask.

webpackTask {
   cssSupport.enabled = true
}
runTask {
   cssSupport.enabled = true
}
testTask {
   useKarma {
      // . . .
      webpackConfig.cssSupport.enabled = true
   }
}

Activating CSS support in your project helps prevent common errors that occur when trying to use style sheets from an unconfigured project, such as Module parse failed: Unexpected character '@' (14:0).

You can use cssSupport.mode to specify how encountered CSS should be handled. The following values are available:

• "inline" (default): styles are added to the global <style> tag.

• "extract": styles are extracted into a separate file. They can then be included from an HTML page.

• "import": styles are processed as strings. This can be useful if you need access to the CSS from your code (such as val styles = require("main.css")).

To use different modes for the same project, use cssSupport.rules. Here, you can specify a list of KotlinWebpackCssRules, each of which define a mode, as well as include and exclude patterns.

Node.js

For Kotlin/JS projects targeting Node.js, the plugin automatically downloads and installs the Node.js environment on the host. You can also use an existing Node.js instance if you have it.

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

To download and install your declared dependencies at build time, the plugin manages its own instance of the Yarn package manager. It works out of the box without additional configuration, but you can tune it or use Yarn already installed on your host.

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

Обратите внимание, что это не влияет на выходные данные webpack в 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. Это известная проблема, обходной путь описан здесь.