Kotlin Help

Interoperability with JavaScript

Kotlin/Wasm allows you to both use JavaScript code from Kotlin and Kotlin code from JavaScript.

The Kotlin/JS compiler already provides the ability to transpile your Kotlin code to JavaScript. The Kotlin/Wasm interoperability with JavaScript is designed in a similar way, taking into account that JavaScript is a dynamically typed language compared to Kotlin. Follow our guide to configure interoperability in your projects.

Remember that Kotlin/Wasm is still Experimental, and some features are not supported yet. We're planning to improve interoperability with JavaScript by implementing some of the missing features or similar functionality.

Use JavaScript code from Kotlin

external modifier

To access JavaScript declarations defined in the global scope, mark them with the external modifier. Consider this JavaScript code sample:

// JavaScript function consoleLogExample() { console.log("Hello"); } let externalInt = 0; let Counter = { value: 0, step: 1, increment() { this.value += this.step; } }; class Rectangle { constructor(height, width) { this.height = height; this.width = width; } get area() { return this.calcArea(); } calcArea() { return this.height * this.width; } }

Here's how you can use this JavaScript code in Kotlin:

// Kotlin/Wasm // Use external functions to call JS functions defined in global scope external fun consoleLogExample(): Unit // In addition to functions, you can have external top-level properties external var externalInt: Int // External objects external object Counter { fun increment(): Unit val value: Int var step: Int } // External class external class Rectangle(height: Double, width: Double) { val height: Double val width: Double val area: Double fun calcArea(): Double }

See the full code in the example project Kotlin/Wasm browser.

@JsFun annotation

To include a small piece of JS code in your Kotlin/Wasm module, use the @JsFun annotation with external top-level functions. The annotation argument should be a string with JS code that evaluates a function with a matching signature:

@JsFun("function count(x) { return x + 10; }") external fun count(x: Int): Int

To make it shorter, use arrow syntax:

@JsFun("x => x + 10") external fun count(x: Int): Int

The Kotlin compiler doesn't verify these JavaScript snippets and evaluates them as-is. Syntax errors, if any, will be reported when running your JavaScript.


To indicate that an external class, package, function, or property is a JavaScript module, use the @JsModule annotation. Consider this JavaScript code sample:

// jsModule.mjs let maxUsers = 10; function getActiveUsers() { return 10; }; class User { constructor(maxUsers) { this.maxUsers = maxUsers; } } export {maxUsers, getActiveUsers, User};

Here's how you can use this JavaScript code in Kotlin:

// kotlin @file:JsModule("./jsModule.mjs") package example external val maxUsers: Int external fun getActiveUsers(): Int external class User { constructor(username: String) val username : String }

Use Kotlin code from JavaScript

@JsExport annotation

To make the Kotlin/Wasm declaration available from JavaScript, use the @JsExport annotation with external top-level functions:

// Kotlin/Wasm @JsExport fun addOne(x: Int): Int = x + 1

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

// JavaScript import exports from "module.mjs" exports.addOne(10)

Functions marked at @JsExport are visible as properties on a default export of the generated .mjs module. Kotlin types in JavaScript In Kotlin/JS, values are implemented internally as JavaScript primitives and objects. They are passed to and from JavaScript without wrapping or copying.

However, in Kotlin/Wasm, objects have a different representation and are not interchangeable with JavaScript. When you pass a Kotlin object to JavaScript, it's considered as an empty opaque object by default.

The only thing you can do is store it and pass Kotlin objects back to Wasm. However, for primitive types, Kotlin/Wasm can adapt these values so that they can be useful in JavaScript by either copying or wrapping. For efficiency purposes, this is done statically. It's important that these special concrete types are present in function signatures. For example:

external fun convertIntAndString(num: Int, text: String) external fun convertAnyAndChars(num: Any, text: CharSequence) // ... convertIntAndString(10, "Hello") // Converts Int and String to JS Number and String convertAnyAndChars(10, "Hello") // No conversion // values are passed as opaque references to Wasm objects

Kotlin types in JavaScript

Supported types

See how Kotlin types are mapped to JavaScript ones:




Byte, Short, Int, Char


Float, Double








String content is copied. In the future, the stringref proposal could allow the zero-copy string interop.



Only when non-nullable and in functions returning position.

Function type, for example (int, String) → Int

Function reference

Parameters and return values of function types follow the same type of conversion rules.

external interface

Any JS value with given properties

external class or external object

Corresponding JS class

Other Kotlin types

Not supported

This includes type Any, arrays, the Throwable class, collections, and so on.

Nullable Type?

Type / null / undefined

Type parameters <T : U>

Same as the upper bound

In interop declarations, only external types, like JsAny, are supported as upper bounds of type parameters.

Exception handling

The Kotlin/Wasm try-catch expression can't catch the JavaScript exceptions.

If you try to use JavaScript try-catch expression to catch the Kotlin/Wasm exceptions, it'll look like a generic WebAssembly.Exception without directly accessible messages and data.

Workarounds for Kotlin/JS features non-supported in Kotlin/Wasm

Dynamic type

Kotlin/JS dynamic type used for interoperability with untyped or loosely typed objects is not supported yet. In many cases, you can use external interfaces and the @JsFun annotation instead:

// Kotlin/JS val user: dynamic val age: Int = 0 user.profile.updateAge(age); // Kotlin/Wasm external interface User @JsFun("(user, age) => user.profile.updateAge(age)") external fun updateUserAge(user: User, age: Int) val user: User val age: Int = 0 updateUserAge(user, age);

Inline JavaScript

The js() function used to inline JavaScript code to Kotlin code is not supported yet. Use the @JsFun annotation instead:

// Kotlin/JS fun jsTypeOf(obj: Any): String { return js("typeof obj") } // Kotlin/Wasm @JsFun("(obj) => typeof obj") external fun jsTypeOf(obj: SomeExternalInterfaceType): String

Extending external interfaces and classes with non-external classes

Extending JavaScript classes and using external interfaces is not supported yet. Use the @JsFun annotation instead:

external interface DataProcessor { fun processData(input: String): String fun processResult(input: String): String } class DataHandler(val handlerData: String) { fun processData(input: String): String = input + handlerData fun processResult(input: String): String = handlerData + input } @JsFun("(processData, processResult) => ({ processData, processResult })") external fun createDataProcessor( processData: (String) -> String, processResult: (String) -> String ): DataProcessor fun convertHandlerToProcessor(handler: DataHandler): DataProcessor = createDataProcessor( processData = { input -> handler.processData(input) }, processResult = { input -> handler.processResult(input) } )
Last modified: 07 June 2023