Supported versions and configuration

This page provides details about the WebAssembly proposals, supported browsers, and configuration recommendations for efficient development with Kotlin/Wasm.

Browser versions

Kotlin/Wasm relies on the latest WebAssembly proposals, such as garbage collection (WasmGC) and exception handling, to introduce improvements and new features within WebAssembly.

To make sure these features work properly, provide an environment that supports the latest proposals. Check if your browser version supports the new WasmGC by default or if you need to make changes to the environment.

Chrome

For version 119 or later:
Works by default.
For older versions:
To run applications in an older browser, you need a Kotlin version older than 1.9.20.
1. In your browser, go to chrome://flags/#enable-webassembly-garbage-collection.
2. Enable WebAssembly Garbage Collection.
3. Relaunch your browser.

Chromium-based

Including Chromium-based browsers such as Edge, Brave, Opera, or Samsung Internet.

For version 119 or later:
Works by default.
For older versions:
To run applications in an older browser, you need a Kotlin version older than 1.9.20.
Run the application with the --js-flags=--experimental-wasm-gc command line argument.

Firefox

For version 120 or later:
Works by default.
For version 119:
1. In your browser, go to about:config.
2. Enable javascript.options.wasm_gc option.
3. Refresh the page.

Safari/WebKit

For version 18.2 or later:
Works by default.
For older versions:
Not supported.

Wasm proposals support

Kotlin/Wasm improvements are based on WebAssembly proposals. Here you can find details about the support for WebAssembly's garbage collection and (legacy) exception handling proposals.

Garbage collection proposal

Since Kotlin 1.9.20, the Kotlin toolchain uses the latest version of the Wasm garbage collection (WasmGC) proposal.

For this reason, we strongly recommend that you update your Wasm projects to the latest version of Kotlin. We also recommend you use the latest versions of browsers with the Wasm environment.

Exception handling proposal

The Kotlin toolchain uses the legacy exception handling proposal by default which allows running produced Wasm binaries in wider range of environments.

Since Kotlin 2.0.0, we have introduced support for the new version of Wasm exception handling proposal within Kotlin/Wasm.

This update ensures the new exception handling proposal aligns with Kotlin requirements, enabling the use of Kotlin/Wasm on virtual machines that only support the latest version of the proposal.

The new exception handling proposal is activated using the -Xwasm-use-new-exception-proposal compiler option. It is turned off by default.

Use default import

Importing Kotlin/Wasm code into Javascript has shifted to named exports, moving away from default exports.

If you still want to use a default import, generate a new JavaScript wrapper module. Create a .mjs file with the following snippet:

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

export { moduleExports as default };

You can place your new .mjs file in the resources folder, and it will automatically be placed next to the main .mjs file during the build process.

You can also place your .mjs file in a custom location. In this case, you need to either manually move it next to the main .mjs file or adjust the path in the import statement to match its location.

Slow Kotlin/Wasm compilation

When working on Kotlin/Wasm projects, you may experience slow compilation times. This happens because the Kotlin/Wasm toolchain recompiles the entire codebase every time you make a change.

To mitigate this issue, Kotlin/Wasm targets support incremental compilation, which enables the compiler to recompile only those files relevant to changes from the last compilation.

Using incremental compilation reduces the compilation time. It doubles the development speed for now, with plans to improve it further in future releases.

In the current setup, incremental compilation for the Wasm targets is disabled by default. To enable it, add the following line to your project's local.properties or gradle.properties file:

kotlin.incremental.wasm=true

Diagnostics in fully qualified class names

On Kotlin/Wasm, the compiler does not store fully qualified names (FQNs) of classes in the generated binary by default, to avoid increasing the application size.

For this reason, the compiler reports an error when you call the KClass::qualifiedName property in Kotlin/Wasm projects, unless you explicitly enable the qualified names feature.

This diagnostic is enabled by default, and errors are reported automatically. To disable the diagnostic and allow qualifiedName in Kotlin/Wasm, instruct the compiler to store fully qualified names for all classes by adding the following option to your build.gradle.kts file:

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

Keep in mind that enabling this option increases the application size.

Array out-of-bounds access and traps

In Kotlin/Wasm, accessing an array with an index outside its bounds triggers a WebAssembly trap instead of a regular Kotlin exception. The trap immediately stops the current stack of execution.

When running in a JavaScript environment, these traps appear as WebAssembly.RuntimeError and can be caught on the JavaScript side.

You can avoid such traps in Kotlin/Wasm environments by using the following compiler option in the command line when linking an executable:

-Xwasm-enable-array-range-checks

Or add it to the compilerOptions {} block of your Gradle build file:

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

With the compiler option enabled, an IndexOutOfBoundsException is thrown instead of a trap.

See more details and share your feedback in this YouTrack issue.

Experimental annotations

Kotlin/Wasm provides several experimental annotations for general WebAssembly interoperability.

@WasmImport and @WasmExport let you call functions defined outside a Kotlin/Wasm module and expose Kotlin functions to the host or other Wasm modules, respectively.

Because these mechanisms are still evolving, all annotations are marked as experimental. You must explicitly opt in to use them, and their design or behavior may change in future Kotlin versions.

Reloads during debugging

Debugging your applications in modern browsers works out of the box. When you run development Gradle tasks (*DevRun), Kotlin automatically serves the source files to the browser.

However, serving sources by default may cause repeated reloads of the application in the browser before Kotlin compilation and bundling are complete. As a workaround, adjust your webpack configuration to ignore Kotlin source files and disable watching for served static files. Add a .js file with the following content into the webpack.config.d directory at the root of your project:

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

10 September 2025