Миграция проектов Kotlin/JS на компилятор IR

Преобразование классов и интерфейсов, связанных с JS и React, во внешние интерфейсы

Проблема: Использование Kotlin-интерфейсов и классов (включая data-классы), которые наследуются от чисто JS-классов, таких как React's State и Props, может привести к ClassCastException. Такие исключения появляются, потому что компилятор пытается работать с экземплярами этих классов как с Kotlin-объектами, тогда как на самом деле они происходят из JS.

Решение: преобразуйте все классы и интерфейсы, которые наследуются от чисто JS-классов, во внешние интерфейсы:

// 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
}

В IntelliJ IDEA вы можете использовать эти шаблоны структурного поиска и замены, чтобы автоматически пометить интерфейсы как external:

• Шаблон для State

• Шаблон для Props

Преобразование свойств внешних интерфейсов в var

Проблема: свойства внешних интерфейсов в коде Kotlin/JS не могут быть только для чтения (val) свойствами, потому что их значения могут быть присвоены только после создания объекта с помощью js() или jso() (вспомогательная функция из kotlin-wrappers):

import kotlinx.js.jso

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

Решение: преобразуйте все свойства внешних интерфейсов в var:

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

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

Преобразование функций с получателями во внешних интерфейсах в обычные функции

Проблема: внешние объявления не могут содержать функции с получателями, такие как расширяющие функции или свойства с соответствующими функциональными типами.

Решение: преобразуйте такие функции и свойства в обычные функции, добавив объект получателя в качестве аргумента:

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

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

Создание простых JS-объектов для взаимодействия

Проблема: свойства Kotlin-объекта, реализующего внешний интерфейс, не являются перечисляемыми. Это означает, что они не видны для операций, которые итерируют по свойствам объекта, например:

• for (var name in obj)

• console.log(obj)

• JSON.stringify(obj)

Хотя они все еще доступны по имени: 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"}
}

Решение 1: создайте простые JavaScript-объекты с js() или jso() (вспомогательная функция из 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 {}

Решение 2: создайте объекты с kotlin.js.json():

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

Замена вызовов toString() на ссылках на функции с .name

Проблема: в бэкенде IR вызов toString() на ссылках на функции не генерирует уникальные значения.

Решение: используйте свойство name вместо toString().

Явно укажите binaries.executable() в скрипте сборки

Проблема: компилятор не генерирует исполняемые .js файлы.

Это может произойти, потому что по умолчанию компилятор генерирует JavaScript-исполняемые файлы, а компилятор IR требует явного указания. Подробнее см. в инструкциях по настройке проекта Kotlin/JS.

Решение: добавьте строку binaries.executable() в build.gradle(.kts) проекта.

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

Дополнительные советы по устранению неполадок при работе с компилятором Kotlin/JS IR

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?
}