@JsExport Kotlin을 JS에 노출하기 위한 가이드

@JsExport is the annotation you need to tell the compiler to generate JavaScript code, and @ExperimentalJsExport is an opt-in marker annotation to use @JsExport as it is experimental to use.

You can get rid of the requirement of adding @ExperimentalJsExport in code by declaring it as OptIn in languageSettings for all source sets in your kotlin block.

kotlin {
    sourceSets {
        all {
            languageSettings.apply {
                optIn("kotlin.js.ExperimentalJsExport")
            }
        }
    }
}

As of Kotlin 1.6.10 , there are heavy limitations on what Kotlin types one can export to JavaScript.

You will most likely face one of these limitations if you add JS support in an existing KMP library.

Whenever something is not-exportable , you would get either an error or a warning:

• Code does not compile with such errors
• Code compiles with such warnings, but you might have run-time issues

Kotlin's collections APIs are not exportable, so you would have to come up with different strategies to deal with them. Some examples would be:

Long is not mapped to anything as there is no equivalent in the JavaScript world. You would see the non-exportable warning if you export Long via Kotlin .

If you ignore the warning, then Long still kinda works. It just takes any value from JS. Kotlin will receive the input as Long if JavaScript code sends a BigInt .

It will not work for Typescript unless you set skipLibCheck = true in the config as type kotlin.Long is not available.

// Kotlin 
@JsExport
class Greeting {
    @Suppress("NON_EXPORTABLE_TYPE")
    fun printLong(value: Long) {
        print(value)
    }
}

// Generated .js
Greeting.prototype.printLong = function (value) {
  print(value);
  };

// Generated .d.ts
printLong(value: kotlin.Long): void;

// Usage from JS
const value = "0b11111111111111111111111111111111111111111111111111111"
Greeting().printLong(BigInt(value)) // This works

You can use @Suppress("NON_EXPORTABLE_TYPE") to suppress the exportable warning

Kotlin interfaces are not exportable. It gets annoying when a library has an interface-driven design, where it exposes the interface in public API rather than a specific implementation.

@JsExport
interface HelloInterface {
    fun hello()
}

The above code would show the non-exportable error. You can use the interface indirectly via its implementation class to work around that problem.

@JsExport
object Hello : HelloInterface {
    override fun hello() {
        console.log("HELLO from HelloInterface")
    }
}

Another idea for using interfaces is to use the expect-actual pattern to define a Kotlin interface in common and mobile platforms and define an external interface for the JS side. This approach might not scale well but can be very useful for simple cases.

// commonMain
expect interface Api {
    fun getProfile(callback: (Profile) -> Unit)
}

// jsMain
// Here external makes it a normal JS object in generated code
actual external interface Api {
    actual fun getProfile(callback: (Profile) -> Unit)
}

// mobileMain
actual interface Api {
    actual fun getProfile(callback: (Profile) -> Unit)
}

These examples showcase workarounds that might or might not work for a particular project.

As of Kotlin 1.6.10, enums are not exportable. It can create issues for projects that have a lot of existing enums.

Good news is that its support coming in Kotlin 1.6.20

There is also a trick to export and use enums on JS. It requires defining a JS-specific object with attributes that point to actual enums.

For example, this code won't compile,

@JsExport
enum Gender {
    MALE,
    FEMALE
}

Instead, you can do this indirectly by re-defining them through object fields. It works with a non-exportable warning. Note the warning suppression with annotation.

@Suppress("NON_EXPORTABLE_TYPE")
@ExperimentalJsExport
@JsExport
object GenderType {
    val male = Gender.MALE
    val female = Gender.FEMALE
}

Sealed classes are exportable, but they’re buggy as of Kotlin 1.6.10

You can export a data or regular class as subclasses inside a Sealed class body, but not an object.

@JsExport
sealed class State {
    object Loading: State() // This won't be visible 
    data class Done(val value: String): State() // This would be visible
}

You can work around this problem by moving the subclasses outside the body of the sealed class, but then you cannot write it like State.Loading . It is more of a readability issue in that case.

Also, sealed classes have known issues with typescript binding as well.

The Kotlin compiler mangles the names of the functions and attributes. It can be frustrating to deal with mangled names.

For example,

@JsExport
object Hello : HelloInterface {
    override fun hello() {
        console.log("HELLO from HelloInterface")
    }
}

Generated JS code for hello method looks like,

Hello.prototype.hello_sv8swh_k$ = function () {
  console.log('HELLO from HelloInterface');
};

You cannot expose suspended functions to JS. You would need to convert them into JavaScript Promise object.

The easiest way to do that would be to wrap suspend calls inside,

GlobalScope.promise {
  // suspend call
}

This function comes from Promise.kt in the coroutine library . It returns a generic type.

As mentioned earlier, some of these issues would get resolved with Kotlin 1.6.20, so keep that in mind.

In the next post, we will look at different ways to distribute Kotlin/JS library since we've some JS exportable code.