Migrating Kotlin/JS projects to the IR compiler

Issue: Using Kotlin interfaces and classes (including data classes) that derive from pure JS classes, such as React's State and Props, can cause a ClassCastException. Such exceptions appear because the compiler attempts to work with instances of these classes as if they were Kotlin objects, when they actually come from JS.

Solution: convert all classes and interfaces that derive from pure JS classes to external interfaces:

// Replace this
interface AppState : State { }
interface AppProps : Props { }
data class CustomComponentState(var name: String) : State

// With this
external interface AppState : State { }
external interface AppProps : Props { }
external interface CustomComponentState : State {
   var name: String
}

In IntelliJ IDEA, you can use these structural search and replace templates to automatically mark interfaces as external:

• Template for State

• Template for Props

Issue: properties of external interfaces in Kotlin/JS code can't be read-only (val) properties because their values can be assigned only after the object is created with js() or jso() (a helper function from kotlin-wrappers):

import kotlinx.js.jso

val myState = jso<CustomComponentState>()
myState.name = "name"

Solution: convert all properties of external interfaces to var:

// Replace this
external interface CustomComponentState : State {
   val name: String
}

// With this
external interface CustomComponentState : State {
   var name: String
}

Issue: external declarations can't contain functions with receivers, such as extension functions or properties with corresponding functional types.

Solution: convert such functions and properties to regular functions by adding the receiver object as an argument:

// Replace this
external interface ButtonProps : Props {
   var inside: StyledDOMBuilder<BUTTON>.() -> Unit
}

external interface ButtonProps : Props {
   var inside: (StyledDOMBuilder<BUTTON>) -> Unit
}

Issue: properties of a Kotlin object that implements an external interface are not enumerable. This means that they are not visible for operations that iterate over the object's properties, for example:

• for (var name in obj)

• console.log(obj)

• JSON.stringify(obj)

Although they are still accessible by the name: obj.myProperty

external interface AppProps { var name: String }
data class AppPropsImpl(override var name: String) : AppProps
fun main() {
   val jsApp = js("{name: 'App1'}") as AppProps // plain JS object
   println("Kotlin sees: ${jsApp.name}") // "App1"
   println("JSON.stringify sees:" + JSON.stringify(jsApp)) // {"name":"App1"} - OK

   val ktApp = AppPropsImpl("App2") // Kotlin object
   println("Kotlin sees: ${ktApp.name}") // "App2"
   // JSON sees only the backing field, not the property
   println("JSON.stringify sees:" + JSON.stringify(ktApp)) // {"_name_3":"App2"}
}

Solution 1: create plain JavaScript objects with js() or jso() (a helper function from kotlin-wrappers):

external interface AppProps { var name: String }
data class AppPropsImpl(override var name: String) : AppProps

// Replace this
val ktApp = AppPropsImpl("App1") // Kotlin object

// With this
val jsApp = js("{name: 'App1'}") as AppProps // or jso {}

Solution 2: create objects with kotlin.js.json():

// or with this
val jsonApp = kotlin.js.json(Pair("name", "App1")) as AppProps

Issue: in the IR backend, calling toString() on function references doesn't produce unique values.

Solution: use the name property instead of toString().

Issue: the compiler doesn't produce executable .js files.

This may happen because the default compiler produces JavaScript executables by default while the IR compiler needs an explicit instruction to do this. Learn more in the Kotlin/JS project setup instruction.

Solution: add the line binaries.executable() to the project's build.gradle(.kts).

kotlin {
    js(IR) {
        browser {
        }
        binaries.executable()
    }
}

These hints may help you when troubleshooting problems in your projects using the Kotlin/JS IR compiler.

external interface SomeExternal {
    var visible: Boolean
}

fun main() {
    val empty: SomeExternal = js("{}")
    println(empty.visible.toString()) // Uncaught TypeError: Cannot read properties of undefined (reading 'toString')
}

// Replace this
external interface SomeExternal {
    var visible: Boolean
}

// With this
external interface SomeExternal {
    var visible: Boolean?
}