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.jetbrains'
version '1.0-SNAPSHOT'

buildscript {
    ext.kotlin_version = '${kotlinVersion}'
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin: 'kotlin2js'

compileKotlin2Js {
    kotlinOptions.outputFile = "output.js"
}

sourceSets {
    main.kotlin.srcDirs += "src/main/kotlin"
}

repositories {
    mavenCentral()
}

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

where ${kotlinVersion} is the version of Kotlin we want to use. It's important to note that if we're using an EAP build, we need to have the corresponding repository referenced in the buildscript section (usually EAP builds are located on Bintray)

The compiler option is defined under compileKotlin2Js and in particular kotlinOptions.outputFile is required to indicate the output of our compiled application. We can also use these options to define module kinds.

On compiling, Gradle will produce the output of our application, which is the {appname}.js file.

In order to use this, we also need to include the Kotlin standard library in our application, i.e. kotlin.js, which was included as a dependency. By default, Gradle does not expand the JAR as part of the build process, so we would need to add an additional step in our build to do so.

build.doLast {
    configurations.compile.each { File file ->
        copy {
            includeEmptyDirs = false

            from zipTree(file.absolutePath)
            into "${projectDir}/web"
            include { fileTreeElement ->
                def path = fileTreeElement.path
                path.endsWith(".js") && (path.startsWith("META-INF/resources/") || !path.startsWith("META-INF/"))
            }
        }
    }
}

For more information on the output generated 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

groovy compileKotlin2Js { kotlinOptions.outputFile = "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.