Skip to content

Kotlin/Wasm doc updates for 2.3.0 release #5191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: 2-3-0-doc-update
Choose a base branch
from
Open

Kotlin/Wasm doc updates for 2.3.0 release #5191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a5f4295
Wasi: handling proposal update
AlejandraPedroza Nov 20, 2025
7e7dc05
Fully qualified names update
AlejandraPedroza Nov 20, 2025
a9c738f
Zalim review
AlejandraPedroza Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 23 additions & 6 deletions docs/topics/wasm/wasm-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,15 +88,24 @@ For this reason, we strongly recommend that you update your Wasm projects to the

### Exception handling proposal

The Kotlin toolchain uses the [legacy exception handling proposal](https://github.com/WebAssembly/exception-handling/blob/master/proposals/exception-handling/legacy/Exceptions.md) by default which allows running produced Wasm binaries in wider range of environments.
The Kotlin toolchain supports both the [legacy](https://github.com/WebAssembly/exception-handling/blob/master/proposals/exception-handling/legacy/Exceptions.md)
and the [new](https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/Exceptions.md)
versions of the exception handling proposal. This allows Kotlin-produced Wasm binaries to run in a wider range of environments.

Since Kotlin 2.0.0, we have introduced support for the new version of Wasm [exception handling proposal](https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/Exceptions.md) within Kotlin/Wasm.
The [`wasmJs` target](wasm-overview.md#kotlin-wasm-and-compose-multiplatform) uses the legacy exception handling proposal by default.
The new proposal is turned off for this target, but
Copy link
Collaborator

@koshachy koshachy Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous sentence already stated that the wasmJS uses the legacy exception handilng proposal.
Maybe we could rephrase the second part as

"To enable the new proposal for wasmJs target, use the ... compiler option."

you can enable it manually using the `-Xwasm-use-new-exception-proposal` compiler option.

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 [`wasmWasi` target](wasm-overview.md#kotlin-wasm-and-wasi) uses the new proposal by default,
ensuring better compatibility with modern WebAssembly runtimes.
You can manually switch to the old proposal by
Copy link
Collaborator

@koshachy koshachy Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To switch to the old (is it old or legacy? what is the right name?) proposal, use the ... compiler option"

using the `-Xwasm-use-new-exception-proposal=false` compiler option.

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

<p>&nbsp;</p>
For the `wasmWasi` target, it is safe to adopt
the new exception handling proposal.
Applications targeting this environment usually run in a less diverse runtime environment
(often running on a single specific VM) that is typically controlled by the user,
reducing the risk of compatibility issues.

> Learn more about setting up projects, using dependencies, and other tasks with our
> [Kotlin/Wasm examples](https://github.com/Kotlin/kotlin-wasm-examples#readme).
Expand Down Expand Up @@ -170,6 +179,14 @@ kotlin {

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

### Fully qualified names

On Kotlin/Wasm targets, fully qualified names (FQNs) are available at runtime without any additional configuration.
This means that the `KClass.qualifiedName` property is enabled by default.

Having FQNs improves code portability from JVM to Wasm targets and makes runtime errors more informative by displaying
Copy link
Collaborator

@koshachy koshachy Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to use more common verbs here:

Using FQNs improves code portability from JVM to Wasm targets and makes runtime errors more informative by showing the full qualified name.

WDYT?

the full qualified name.

## 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.
Expand Down
5 changes: 4 additions & 1 deletion docs/topics/wasm/wasm-wasi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@ You can find examples of an application running on [Node.js](https://nodejs.org/
and [WasmEdge](https://wasmedge.org/) virtual machines. The output is a simple application that uses the standard WASI API.

Currently, Kotlin/Wasm supports WASI 0.1, also known as Preview 1.
[Support for WASI 0.2 is planned for future releases](https://youtrack.jetbrains.com/issue/KT-64568).
[Support for WASI 0.2 is planned for future releases](https://youtrack.jetbrains.com/issue/KT-64568).
Copy link
Collaborator

@koshachy koshachy Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's explain better what behind the link. Smth like:

Follow this YouTrack issue for updates on WASI 0.2 support.

WDYT?


The [`wasmWasi`](wasm-overview.md#kotlin-wasm-and-wasi) target
[uses the new exception handling proposal by default](wasm-configuration.md#exception-handling-proposal), ensuring better compatibility with modern WebAssembly runtimes.

> The Kotlin/Wasm toolchain provides Node.js tasks (`wasmWasiNode*`) out of the box.
> Other task variants in the project, such as those utilizing Deno or WasmEdge, are included as custom tasks.
Expand Down