Calling Kotlin from JavaScript

If you have explicitly set your module kind to be plain, Kotlin creates an object that contains all Kotlin declarations from the current module. This is done to prevent spoiling the global object. This means that for a module myModule, all declarations are available to JavaScript via the myModule object. For example:

Can be called from JavaScript like this:

alert(myModule.foo());

This is not applicable when you compile your Kotlin module to JavaScript modules like UMD (which is the default setting for both browser and nodejs targets), CommonJS or AMD. In this case, your declarations will be exposed in the format specified by your chosen JavaScript module system. When using UMD or CommonJS, for example, your call site could look like this:

alert(require('myModule').foo());

Check the article on JavaScript Modules for more information on the topic of JavaScript module systems.

Kotlin exposes its package structure to JavaScript, so unless you define your declarations in the root package, you have to use fully qualified names in JavaScript. For example:

When using UMD or CommonJS, for example, your callsite could look like this:

alert(require('myModule').my.qualified.packagename.foo())

alert(myModule.my.qualified.packagename.foo());

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:

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

// If necessary, import 'kjs' according to chosen module system
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$.

Note that there are some cases in which the Kotlin compiler does not apply mangling:

• declarations are not mangled.
• Any overridden functions in non-external classes inheriting from external classes are not mangled.

The parameter of @JsName is required to be a constant string literal which is a valid identifier. The compiler will report an error on any attempt to pass non-identifier string to @JsName. The following example produces a compile-time error:

@JsName("new C()")   // error here
external fun newC()

@JsExport annotation

To resolve ambiguities in exports (like overloads for functions with the same name), you can use the @JsExport annotation together with @JsName to specify the names for the generated and exported functions.

The @JsExport annotation is available in the current default compiler backend and the new IR compiler backend. If you are targeting the IR compiler backend, you must use the @JsExport annotation to make your functions visible from Kotlin in the first place.

For multiplatform projects, @JsExport is available in common code as well. It only has an effect when compiling for the JavaScript target, and allows you to also export Kotlin declarations that are not platform specific.

• Kotlin numeric types, except for kotlin.Long are mapped to JavaScript Number.
• kotlin.Char is mapped to JavaScript Number representing character code.

• Kotlin can’t distinguish between numeric types at run time (except for kotlin.Long), so the following code works:

• Kotlin preserves overflow semantics for kotlin.Int, kotlin.Byte, kotlin.Short, and kotlin.Long.

• kotlin.String is mapped to JavaScript String.
• kotlin.Any is mapped to JavaScript Object (new Object(), {}, etc).
• kotlin.Array is mapped to JavaScript Array.
• Kotlin collections (List, Set, Map, etc.) are not mapped to any specific JavaScript type.
• kotlin.Throwable is mapped to JavaScript Error.
• Kotlin preserves lazy object initialization in JavaScript.
• Kotlin does not implement lazy initialization of top-level properties in JavaScript.

Starting with version 1.1.50 primitive array translation utilizes JavaScript TypedArray:

• kotlin.ByteArray, -.ShortArray, -.IntArray, -.FloatArray, and -.DoubleArray are mapped to JavaScript Int8Array, Int16Array, Int32Array, Float32Array, and Float64Array correspondingly.
• kotlin.BooleanArray is mapped to JavaScript Int8Array with a property $type$ == "BooleanArray"
• kotlin.CharArray is mapped to JavaScript UInt16Array with a property $type$ == "CharArray"