js-interop.md

type	layout	category	title
doc	reference	JavaScript	JavaScript Interoperability

JavaScript Interoperability

JavaScript Modules

Since Kotlin version 1.0.4 you can compile your Kotlin projects to JS modules for popular module systems. Here is the list of available options:

1. Plain. Don't compile for any module system. As usual, you can access module moduleName via kotlin.modules.moduleName, or by just moduleName identifier put in the global scope. This option is used by default.
2. Asynchronous Module Definition (AMD), which is in particular used by require.js library.
3. CommonJS convention, widely used by node.js/npm (require function and module.exports object)
4. Unified Module Definitions (UMD), which is compatible with both AMD and CommonJS, and works as "plain" when neither AMD nor CommonJS is available.

Choosing the target module system depends on your build environment:

From IDEA

Open File -> Settings, select "Build, Execution, Deployment" -> "Compiler" -> "Kotlin compiler". Choose appropriate module system in "Module kind" field.

From Maven

To select module system when compiling via Maven, you should set moduleKind configuration property, i.e. your pom.xml should look like this:

<plugin>
    <artifactId>kotlin-maven-plugin</artifactId>
    <groupId>org.jetbrains.kotlin</groupId>
    <version>${kotlin.version}</version>
    <executions>
        <execution>
            <id>compile</id>
            <goals>
                <goal>js</goal>
            </goals>
        </execution>
    </executions>
    <!-- Insert these lines -->
    <configuration>
        <moduleKind>commonjs</moduleKind>
    </configuration>
    <!-- end of inserted text -->
</plugin>

Available values are: plain, amd, commonjs, umd.

From Gradle

To select module system when compiling via Gradle, you should set moduleKind property, i.e.

compileKotlin2Js.kotlinOptions.moduleKind = "commonjs"

Available values are similar to Maven

Notes

We ship kotlin.js standard library as a single file, which is itself compiled as an UMD module, so you can use it with any module system described above.

Although for now we don't support WebPack and Browserify directly, we tested .js files produced by Kotlin compiler with WebPack and Browserify, so Kotlin should work with these tools properly.

@JsName Annotation

In some cases (for example, to support overloads), the Kotlin compiler mangles the names of generated functions and attributes in JavaScript code. To control the generated names, you can use the @JsName annotation:

// Module 'kjs'

class Person(val name: String) {
    fun hello() {
        println("Hello $name!")
    }

    @JsName("helloWithGreeting")
    fun hello(greeting: String) {
        println("$greeting $name!")
    }
}

Now you can use this class from JavaScript in the following way:

var person = new kjs.Person("Dmitry");   // refers to module 'kjs'
person.hello();                          // prints "Hello Dmitry!"
person.helloWithGreeting("Servus");      // prints "Servus Dmitry!"

If we didn't specify the @JsName annotation, the name of the corresponding function would contain a suffix calculated from the function signature, for example hello_61zpoe$.