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

Проекты Kotlin/JS используют Gradle в качестве системы сборки. Чтобы разработчикам было проще управлять своими проектами Kotlin/JS, мы предлагаем плагин Gradle, который предоставляет инструменты конфигурации проекта вместе с вспомогательными задачами для автоматизации задач, типичных для разработки JavaScript. Например, плагин скачивает менеджер пакетов Yarn для управления зависимостями npm в фоновом режиме и может сгенерировать JavaScript-сборку из Kotlin-проекта с использованием webpack. Управление зависимостями и корректировку настроек можно в значительной степени выполнять непосредственно из файла сборки Gradle, с возможностью переопределения автоматически сгенерированных настроек для полного контроля.

Чтобы создать проект Kotlin/JS в IntelliJ IDEA, перейдите в Файл | Новый | Проект и выберите Gradle | Kotlin/JS для браузера или Kotlin/JS для Node.js. Убедитесь, что вы сняли флажок Java. Если вы хотите использовать Kotlin DSL для Gradle, убедитесь, что выбран пункт Kotlin DSL build script.

В качестве альтернативы вы можете вручную применить плагин org.jetbrains.kotlin.js к проекту Gradle в файле сборки Gradle (build.gradle или build.gradle.kts).

plugins {
    id 'org.jetbrains.kotlin.js' version '1.4.10'
}

plugins {
     kotlin("js") version "1.4.10"
}

Плагин Kotlin/JS Gradle позволяет управлять аспектами вашего проекта в разделе kotlin файла сборки.

kotlin {
    //...
}

Внутри раздела kotlin вы можете управлять следующими аспектами:

• Целевая среда выполнения: браузер или Node.js
• Зависимости проекта: Maven и npm
• Настройка задачи запуска
• Настройка задачи тестирования
• Сборка и поддержка CSS для проектов браузера
• Целевая директория и имя модуля

Выбор среды выполнения

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

Управление зависимостями

Как и любые другие проекты 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 автоматически разрешит эти транзитивные зависимости.

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

Зависимость от стандартной библиотеки Kotlin/JS обязательна для всех проектов Kotlin/JS и поэтому является неявной — не нужно добавлять артефакты. Если ваш проект содержит тесты на Kotlin, добавьте зависимость от библиотеки kotlin.test:

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

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

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

В JavaScript-среде наиболее распространённый способ управления зависимостями — npm. Он предлагает самый большой публичный репозиторий JavaScript-модулей.

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

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

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

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

Для загрузки и установки объявленных зависимостей во время сборки плагин управляет собственной установкой менеджера пакетов Yarn.

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

• devDependencies, через devNpm(...),
• optionalDependencies через optionalNpm(...), и
• peerDependencies через peerNpm(...).

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

Настройка задачи запуска

Плагин 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()
        // . . .
    }
}

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

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

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

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

./gradlew check

Настройка Karma

Плагин Kotlin/JS Gradle автоматически генерирует конфигурационный файл Karma во время сборки, который включает ваши настройки из раздела kotlin.js.browser.testTask.useKarma в вашем build.gradle(.kts). Вы можете найти этот файл в build/js/packages/projectName-test/karma.conf.js. Чтобы внести изменения в конфигурацию, используемую Karma, поместите дополнительные конфигурационные файлы в директорию karma.config.d в корне вашего проекта. Все конфигурационные файлы .js в этой директории будут взяты и автоматически объединены в сгенерированный karma.conf.js во время сборки.

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

Настройка связывания webpack

Для целей браузера плагин Kotlin/JS использует широко известный модульный связующий компонент webpack.

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

Наиболее распространённые изменения в webpack можно внести напрямую через блок конфигурации kotlin.js.browser.webpackTask в файле Gradle сборки.

Если вы хотите внести дополнительные изменения в конфигурацию 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, плагин Kotlin/JS содержит задачи Gradle browserDevelopmentWebpack и browserProductionWebpack.

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

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

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

./gradlew browserProductionWebpack

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

Настройка CSS

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

Чтобы включить поддержку CSS в вашем проекте, установите флаг cssSupport.enabled в файле сборки Gradle для 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 шаблоны.

Настройка Yarn

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

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

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

Чтобы узнать больше о .yarnrc, посетите официальную документацию Yarn.

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

По умолчанию результаты сборки проекта 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.

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

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