Edit Page

Getting Started with Kotlin and JavaScript with Gradle

Last Updated 4 November 2016
A look at how to use Gradle to target JavaScript.

In this tutorial we'll see how to

In order to use Gradle to target JavaScript, we need to use the kotlin2js plugin as opposed to the kotlin plugin.

Our build.gradle file should look like the following

group 'org.example'
version '1.0-SNAPSHOT'

buildscript {
    ext.kotlin_version = '1.3.61'
    repositories {
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"

apply plugin: 'kotlin2js'

repositories {

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-js:$kotlin_version"

To use an EAP build instead, we need to specify its version in ext.kotlin_version and add the corresponding repository to the buildscript section (usually EAP builds are located on Bintray)

On compiling, Gradle will produce the output of our application, which is by default placed under the build/classes/main directory. This can be overridden using the compiler options.

In order to assemble an application, we also need to include the Kotlin standard library, i.e. kotlin.js, which was included as a dependency, and the other libraries if any.

By default, Gradle does not expand the JARs in the build process, so we need to add an additional step in our build to do so:

task assembleWeb(type: Sync) {
    configurations.compile.each { File file ->
        from(zipTree(file.absolutePath), {
            includeEmptyDirs = false
            include { fileTreeElement ->
                def path = fileTreeElement.path
                path.endsWith(".js") && (path.startsWith("META-INF/resources/") || 
    from compileKotlin2Js.destinationDir
    into "${projectDir}/web"

    dependsOn classes

assemble.dependsOn assembleWeb

This task copies both dependencies runtime files and the compilation output to the web directory.

For more information on the output generated and the instructions for running the application, please see Kotlin to JavaScript

Configuring Compiler Options

Similar to when we're using IntelliJ IDEA build system or the command line, we can have the compiler output JavaScript to comply with a specific module system such as AMD, CommonJS or UMD.

In order to specify the module kind, we can add a configuration to our plugin as below

compileKotlin2Js {
    kotlinOptions.outputFile = "${projectDir}/web/output.js"
    kotlinOptions.moduleKind = "amd"
    kotlinOptions.sourceMap = true

where moduleKind can be

  • plain (default)
  • amd
  • commonjs
  • umd

For more information about the different types of module outputs, please see Working with Modules

We can also see how we can define whether we want the compiler to generate sourcemaps for us by indicating this via the sourceMap option.