Edit Page

Setting up a Kotlin/JS project

Kotlin/JS projects use Gradle as a build system. To let developers easily manage their Kotlin/JS projects, we offer the Kotlin/JS Gradle plugin that provides project configuration tools together with helper tasks for automating routines typical for JavaScript development. For example, the plugin downloads the Yarn package manager for managing NPM dependencies in background and builds a JavaScript bundle from a Kotlin project using Webpack.

To create a Kotlin/JS project in IntelliJ IDEA, go to File | New | Project and select Gradle | Kotlin/JS for browser or Kotlin/JS for Node.js. Be sure to clear the Java checkbox.

New project wizard

Alternatively, you can apply the org.jetbrains.kotlin.js plugin to a Gradle project manually in the build.gradle file. If you use the Gradle Kotlin DSL, you can apply the plugin with kotlin(“js”).

plugins {
    id 'org.jetbrains.kotlin.js' version '1.3.61'
}
plugins {
     kotlin("js") version "1.3.61"
}

The Kotlin/JS plugin lets you manage aspects of your project in the kotlin section of the build script.

kotlin {
    //...
}

Inside the kotlin section, you can manage the following aspects:

Choosing execution environment

Kotlin/JS projects can target two different execution environments:

  • Browser for client-side scripting in browsers
  • Node.js for running JavaScript code outside of a browser, for example, for server-side scripting.

To define the target execution environment for a Kotlin/JS project, add the target section with browser {} or nodejs {} inside.

kotlin {
    target {
        browser {
        }       
    }
}    

The Kotlin/JS plugin automatically configures its tasks for working with the selected environment. This includes downloading and installing dependencies required for running and testing the application, and therefore lets developers build, run, and test simple projects without additional configuration.

Managing dependencies

Like any other Gradle projects, Kotlin/JS projects support traditional Gradle dependency declarations in the dependencies section of the build script.

dependencies {
    implementation 'org.example.myproject:1.1.0'
}
dependencies {
    implementation("org.example.myproject", "1.1.0")
}

The Kotlin/JS Gradle plugin also supports dependency declarations for particular source sets in the kotlin section of the build script.

kotlin {
    sourceSets {
        main {
            dependencies {
                implementation 'org.example.myproject:1.1.0'
            }
        }
    }
}
kotlin {
  sourceSets["main"].dependencies {
    implementation("org.example.myproject", "1.1.0")
  }
}

Kotlin standard libraries

The dependency on the Kotlin/JS standard library is mandatory for all Kotlin/JS projects. If your project contains tests written in Kotlin, you should also add the dependency on the kotlin.test library.

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib-js'
    testImplementation 'org.jetbrains.kotlin:kotlin-test-js'
}
dependencies {
    implementation(kotlin("stdlib-js"))
    testImplementation(kotlin("test-js"))
}

NPM dependencies

In the JavaScript world, the common way to manage dependencies is NPM. It offers the biggest public repositoryof JavaScript modules and a tool for downloading them. The Kotlin/JS plugin lets you declare NPM dependencies in the Gradle build script among other dependencies and does everything else automatically. Particularly, it installs the Yarn package manager and uses it to download the dependencies from the NPM repository to the node_modules directory of your project - the common location for NPM dependencies of a JavaScript project.

To declare an NPM dependency, use the npm() function inside the dependencies section of a source set.

kotlin {
    sourceSets {
        main {
            dependencies {
                implementation npm('react', '16.12.0')
            }
        }
    }
}
kotlin {
  sourceSets["main"].dependencies {
    implementation(npm("react", "16.12.0"))
  }
}

Once an NPM dependency is installed, you can use its API in your code as described in Calling JS from Kotlin.

Configuring run task

The Kotlin/JS plugin provides a run task that lets you run projects without additional configuration. For running Kotlin/JS projects, it uses Webpack DevServer. If you want to customize the DevServer configuration, for example, change its port, use the Webpack configuration file.

To run the project, execute the standard lifecycle run task:

./gradlew run

To see the source file changes in browser without restarting the DevServer, use the Gradle continuous build:

./gradlew run --continuous

or

./gradlew run -t

Configuring test task

The Kotin/JS Gradle plugin automatically sets up a test infrastructure for projects. For browser projects, it downloads and installs the Karma test runner with other required dependencies; for NodeJS projects, the Mocha test framework is used.

The plugin also provides useful testing features, for example:

  • Source maps generation
  • Test reports generation
  • Test run results in the console

By default, the plugin uses Headless Chrome for running browser tests. You can also run them in other browsers by adding the corresponding entries inside the useKarma section of the build script:

kotlin {
    target {
        browser {
            testTask {
                useKarma {
                    useIe()
                    useSafari()
                    useFirefox()
                    useChrome()
                    useChromeCanary()
                    useChromeHeadless()
                    usePhantomJS()
                    useOpera()
                }
            }
        }
    }
}

If you want to skip tests, add the line enabled = false to the testTask.

kotlin {
    target {
        browser {
            testTask {
                enabled = false
            }
        }
    }
}

To run tests, execute the standard lifecycle check task:

./gradlew check

Configuring Webpack bundling

For building executable JavaScript artifacts, the Kotlin/JS plugins contains the webpackTask.

To build a project artifact using Webpack, execute the build Gradle task:

./gradlew build