Поддерживаемые версии и настройка

Версии браузеров

Kotlin/Wasm использует новейшие предложения WebAssembly, такие как сборка мусора (WasmGC) и обработка исключений, чтобы внедрять улучшения и новые функции в WebAssembly.

Чтобы эти функции работали правильно, используйте среду, поддерживающую новейшие предложения. Проверьте, поддерживает ли ваша версия браузера новую WasmGC по умолчанию или необходимо внести изменения в среду.

Поддержка предложений Wasm

Улучшения Kotlin/Wasm основаны на предложениях WebAssembly. Здесь приведены сведения о поддержке предложений WebAssembly по сборке мусора и обработке исключений (устаревшей).

Использование импорта по умолчанию

Импорт кода Kotlin/Wasm в JavaScript перешёл на именованные экспорты вместо экспортов по умолчанию.

Если вы всё же хотите использовать импорт по умолчанию, создайте новый модуль-обёртку JavaScript. Создайте файл .mjs со следующим фрагментом:

// Specifies the path to the main .mjs file
import * as moduleExports from "./wasm-test.mjs";

export { moduleExports as default };

Новый файл .mjs можно поместить в папку ресурсов — во время сборки он автоматически окажется рядом с основным файлом .mjs.

Файл .mjs также можно поместить в пользовательское расположение. В этом случае его нужно либо вручную переместить рядом с основным файлом .mjs, либо изменить путь в инструкции импорта, указав его расположение.

Инкрементальная компиляция Kotlin/Wasm

Цели Kotlin/Wasm поддерживают инкрементальную компиляцию, которая позволяет компилятору повторно компилировать только файлы, затронутые последними изменениями. Это помогает сократить время компиляции.

Инкрементальная компиляция для целей Wasm включена по умолчанию. Чтобы отключить её, добавьте следующую строку в файл local.properties или gradle.properties вашего проекта:

kotlin.incremental.wasm=false

Диагностика полных имён классов

В Kotlin/Wasm компилятор по умолчанию не сохраняет в созданном бинарном файле полные имена классов (FQN), чтобы не увеличивать размер приложения.

Поэтому компилятор сообщает об ошибке при вызове свойства KClass::qualifiedName в проектах Kotlin/Wasm, если только вы явно не включили функцию полных имён.

Эта диагностика включена по умолчанию, и об ошибках сообщается автоматически. Чтобы отключить диагностику и разрешить qualifiedName в Kotlin/Wasm, укажите компилятору сохранять полные имена всех классов, добавив следующий параметр в файл build.gradle.kts:

// build.gradle.kts
kotlin {
   wasmJs {
       ...
       compilerOptions {
           freeCompilerArgs.add("-Xwasm-kclass-fqn")
       }
   }
}

Учтите, что включение этого параметра увеличивает размер приложения.

Выход за границы массива и ловушки

В Kotlin/Wasm обращение к массиву по индексу за его границами вызывает ловушку WebAssembly вместо обычного исключения Kotlin. Ловушка немедленно останавливает текущий стек выполнения.

В среде JavaScript такие ловушки отображаются как WebAssembly.RuntimeError и могут быть перехвачены на стороне JavaScript.

Избежать таких ловушек в средах Kotlin/Wasm можно, указав следующий параметр компилятора в командной строке при компоновке исполняемого файла:

-Xwasm-enable-array-range-checks

Или добавьте его в блок compilerOptions {} файла сборки Gradle:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xwasm-enable-array-range-checks")
    }
}

Если параметр компилятора включён, вместо ловушки выбрасывается IndexOutOfBoundsException.

Подробнее и возможность поделиться отзывом доступны в этой задаче YouTrack.

Экспериментальные аннотации

Kotlin/Wasm предоставляет несколько экспериментальных аннотаций для общего взаимодействия с WebAssembly.

@WasmImport и @WasmExport позволяют вызывать функции, определённые вне модуля Kotlin/Wasm, и предоставлять функции Kotlin хост-среде или другим модулям Wasm соответственно.

Поскольку эти механизмы всё ещё развиваются, все аннотации помечены как экспериментальные. Чтобы использовать их, необходимо явно дать согласие на использование; их дизайн или поведение могут измениться в будущих версиях Kotlin.

Перезагрузка во время отладки

Отладка приложений в современных браузерах работает без дополнительной настройки. При запуске задач Gradle для разработки (*DevRun) Kotlin автоматически передаёт исходные файлы в браузер.

Однако передача исходников по умолчанию может привести к повторной перезагрузке приложения в браузере до завершения компиляции Kotlin и создания пакета. В качестве обходного решения измените конфигурацию webpack, чтобы исключить исходные файлы Kotlin и отключить отслеживание передаваемых статических файлов. Добавьте файл .js со следующим содержимым в каталог webpack.config.d в корне проекта:

config.watchOptions = config.watchOptions || {
    ignored: ["**/*.kt", "**/node_modules"]
}

if (config.devServer) {
    config.devServer.static = config.devServer.static.map(file => {
        if (typeof file === "string") {
            return {
                directory: file,
                watch: false,
            }
        } else {
            return file
        }
    })
}