Skip to content

Kotlin/Wasm web application

Use the wasm-js/app product type in a module to build a WebAssembly application that can run in browsers using the Kotlin/Wasm technology.

Module layout

Here is an overview of the module layout for a Kotlin/Wasm application:

my-module/
├─ resources # (1)!
│  ╰─ index.html # (2)!
├─ src/
│  ├─ main.kt
│  ╰─ Util.kt
├─ test/
│  ╰─ UtilTest.kt
╰─ module.yaml
  1. Resources placed here are packaged together with the resulting application
  2. index.html is the entrypoint for your web application. It is optional to include it—see index.html configuration for more details

Entry point

The entry point of a Kotlin/Wasm application is a top-level main function in the src folder.

Multiple main functions are not supported. If you have multiple main functions, the one chosen by the compiler as an entry point is unspecified.

index.html configuration

By default, the Kotlin Toolchain provides a minimal index.html for the application. It is the entry point that the browser should load to open the application. If you want to customize it (e.g., to add an analytics script or CSS), you can put your own version of it under the resources folder of the module. There are several template variables that are available for use in the index.html:

  • {{kotlin.moduleName}} — the name of the module
  • {{kotlin.moduleFile}} — the name of the mjs wrapper that loads your Wasm application
  • {{kotlin.scripts}} — the minimal required set of scripts to properly load your application. Includes {{kotlin.moduleFile}} and import map loader for loading third-party dependencies.

The default index.html looks like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <style> /*(1)!*/
        html, body {
            width: 100%;
            height: 100%;
            margin: 0;
            padding: 0;
            overflow: hidden;
        }
    </style>
    <title>{{kotlin.moduleName}}</title>
    {{kotlin.scripts}}
</head>
<body>

</body>
</html>
  1. Styles required for the content to fill the entire screen. See Compose Multiplatform documentation for explanation.

Dependencies

Currently, defining direct NPM dependencies for your application is not supported. However, if you use a Kotlin Multiplatform library that requires such a dependency (e.g., @js-joda/core for kotlinx-datetime), the dependency will be downloaded and packed together with your application.

Running your application

You can run your application in a browser using the kotlin run command.

There are no prerequisites for this command. It will automatically:

  • download Maven dependencies and their transitive npm dependencies
  • provision the Skiko Wasm runtime
  • compile the module and its local dependencies
  • generate all the relevant files (see the packaging section below)
  • start a local server to serve those files
  • launch a browser with the /index.html file

Packaging

Using the build command packages your application under the build/tasks/_<module-name>_buildWasmJsAppWasmJs<Debug|Release> folder, but this is subject to change.

The package includes:

  • a <module-name>.wasm file with your app module's code
  • a set of .mjs files to load it
  • all required JS dependencies
  • the Skiko Wasm runtime
  • the index.html page that serves as the entrypoint of the application

There are no extra packaging facilities at the moment, and the package command is not supported for this product type.

Testing

Tests targeting Wasm JS target are not supported yet, but we are working on it.