Web Targets: Kotlin/Wasm, Kotlin/JS and Compose for Web

KMP offers three targets that can run in or near a browser. They differ in what they compile to, where they run and how mature they are.

The decision is mostly about the front end. If a web team already owns a React, Vue or Angular application and you want to give it your domain code, choose js with TypeScript definitions. If you want one Compose UI on every screen, choose wasmJs. If you need both, and many teams do, a project can declare js and wasmJs together and share most of the code between them, as the next section shows. wasmWasi is mentioned for completeness: it targets WASI hosts and has no DOM, so TrailMate does not use it. See Kotlin docs — Get started with Kotlin/Wasm and WASI.

Since Kotlin 2.2.20 the default hierarchy template creates a shared source set named webMain (and webTest) as soon as a module declares both js and wasmJs. It sits between commonMain and the two web leaves, exactly like iosMain sits above the iOS targets, and it is where browser-only code that works on both targets belongs.

Code in webMain can use the Kotlin standard library’s browser API (kotlinx.browser.window, document, localStorage) that is shared by both web targets. Code that must differ, such as raw interop that uses dynamic on js but typed JsAny on wasmJs, goes into the leaf source sets through expect/actual (see Expect/Actual and Platform APIs and Project Structure and Source Sets).

On Android the entry point is an Activity, on iOS a UIViewController and on desktop a Window. On the web the entry point is a DOM element: ComposeViewport attaches a Compose canvas to an element of your index.html and renders the composable tree into it. The Compose UI is drawn by Skia (through Skiko, compiled to WebAssembly) onto a <canvas>, which is why the app looks identical on every browser but is not made of real HTML elements.

See Kotlin docs — Create your Compose Multiplatform app.

ComposeViewport is Beta together with the web target and is annotated ExperimentalComposeUiApi in current releases. Called without an id it fills the whole <body>, which is the simplest option and the one the project wizard generates. Passing viewportContainerId lets the Compose canvas live inside a part of a larger HTML page, for example a card on a documentation site.

See Kotlin docs — Compose Multiplatform for web: CSS and HTML integration.

The container needs an explicit size: a <div> with no height collapses to zero and the app appears blank, which is one of the most common first-run mistakes. Everything else about the UI, such as theming, layouts and state, is ordinary Compose that you wrote once in sharedUI; the web-specific code is the entry point and the HTML around it.

A browser without WasmGC would show a blank page. The Compose Multiplatform Gradle plugin therefore offers a second distribution task that produces both a WebAssembly build and a plain JavaScript build, plus a small loader that picks the right one at start-up. To use it the web module declares the js target next to wasmJs; the shared modules must declare both too.

See Kotlin docs — Set up an environment for Compose Multiplatform.

With both targets declared, the distribution tasks are:

The trade-off is size and build time: the compatibility build compiles the whole application twice and the user downloads only one of the two, but you maintain a single deployment. For an internal tool on managed browsers, wasmJsBrowserDistribution alone is enough. The same task names exist for development servers (wasmJsBrowserDevelopmentRun, jsBrowserDevelopmentRun), which start a webpack dev server with hot reload of the compiled output.

Because the Compose UI is a canvas, it cannot show a video player, an <iframe>, a map widget or a rich-text editor natively. HtmlElementView is Compose’s escape hatch on the web: it places a real DOM element on top of a rectangle of the canvas and keeps it positioned and clipped with the composable. It is the web counterpart of UIKitView on iOS (see Compose Multiplatform on iOS) and of SwingPanel on desktop. The API is Experimental at the time of writing.

See Kotlin docs — Compose Multiplatform for web: resources and HTML integration.

The factory creates the element once, and update runs on recomposition so a changed embedUrl reaches the DOM. Keep such views few and small. Each one is a separate compositing layer, it does not take part in Compose’s semantics tree automatically (set title or ARIA attributes yourself), and it draws above or below the canvas rather than blending into it, so Compose popups cannot overlap it. The shared code reaches it through an expect composable TrailMap, so Android uses the Google Maps Compose library, iOS an MKMapView and the web this iframe.

CMP’s composeResources (images, strings, fonts) work on the web, and the generated Res class is the same one used on other targets. The web adds two considerations. First, resources are fetched over HTTP at run time, so the first painterResource or stringResource call can appear after a short delay; preloading with the resource APIs hides it. Second, the browser has no system font fallback inside a canvas: if the app displays emoji or non-Latin scripts you must bundle a font that covers them in composeResources/font, or those glyphs render as empty boxes. See Resources and Localization in Compose Multiplatform for qualifiers and localization, and Kotlin docs — Compose Multiplatform for web: resources.

A web app lives behind a URL, and users expect the back button, bookmarks and deep links to work. A canvas app does not change the URL by itself, so navigation must be connected to the browser history. With Navigation Compose, the bindToBrowserNavigation() function (Experimental) links the NavController back stack to window.history, so navigating pushes an entry and the browser’s back button pops it. The routes are the same type-safe @Serializable destinations used on Android and iOS.

See Kotlin docs — Navigation and routing.

A deep link such as https://example.github.io/trailmate//trail/42 must be resolved at start-up from the current location. The destination graph, NavHost and back-stack behaviour are covered in Lifecycle, ViewModel and Navigation in Compose Multiplatform, and the Android equivalent in Android: Navigation with Compose. Navigation 3 does not yet have a built-in browser-history binding in CMP, so apps that use it map the back stack to the URL themselves. A static host such as GitHub Pages returns 404 for unknown paths, so prefer hash-based URLs (/trail/42) there, or add a 404.html that redirects to index.html.

Eventually the app needs a browser feature that Kotlin has no wrapper for: geolocation, the Clipboard API, a JavaScript library. Kotlin/Wasm talks to JavaScript through typed declarations, which is stricter than Kotlin/JS’s dynamic. There are three tools: external declarations for existing JavaScript objects and functions, js("…​") for short inline snippets, and @JsModule to import a JavaScript module.

See Kotlin docs — Interoperability with JavaScript.

This is the LocationProvider from the running example: Android and iOS implement it with their platform location services (see Expect/Actual and Platform APIs) and the web implements it with navigator.geolocation. Four rules explain the shape of the code. Types that cross the boundary must be JsAny subtypes or a small set of primitives (Int, Double, Boolean, String); you cannot pass a Kotlin Trail directly. external declarations contain no bodies and describe JavaScript, not Kotlin. A js("…​") call must be the whole body of a top-level function or property. And Promise.await() bridges to coroutines so the Wasm code stays suspend. The browser will ask the user for permission on the first call, and the call fails on non-HTTPS origins (except localhost).

Not every web project should render Compose. A company may have a React or Angular front end, an established design system and SEO needs that a canvas cannot meet, and still want TrailMate’s Trail model, validation and repository logic written once. Kotlin/JS (Stable) compiles sharedLogic into an ES module and, optionally, a TypeScript declaration file, so TypeScript code can call it with full type checking.

See Kotlin docs — Set up a Kotlin/JS project.

binaries.library() produces a library rather than an application, useEsModules() emits modern import/export modules, and generateTypeScriptDefinitions() writes the .d.ts file next to the compiled JavaScript. Only declarations annotated with @JsExport appear in the output; everything else is stripped or mangled, which is deliberate so internal refactoring cannot break a JavaScript consumer.

See Kotlin docs — Use Kotlin code from JavaScript.

The restrictions on @JsExport are what shape the facade. Exported signatures may use primitives, strings, arrays, Promise, exported classes and interfaces, but not Kotlin collections (List, Map), suspend functions, Flow, sealed classes or extension functions. That is why the example converts to TrailJs, returns an Array and wraps the coroutine in promise { }. The same facade pattern appears on iOS with SKIE or KMP-NativeCoroutines, which turn suspend and Flow into async and AsyncSequence; see Coroutines and Flow from Swift. The generated declaration then makes the Kotlin API feel native in TypeScript.

See Kotlin docs — JavaScript modules.

To publish the module to a TypeScript project, either consume build/dist/js/productionLibrary as a local package or publish it to npm; a Gradle plugin for npm publishing is described in the Kotlin/JS documentation. For the opposite direction, calling JavaScript from Kotlin/JS, use external declarations or dynamic. See also React Native, which solves the same "shared logic behind a JavaScript UI" problem with a different runtime.

Browser DevTools can debug Kotlin directly through source maps, which the Gradle plugin generates for development builds. Run wasmJsBrowserDevelopmentRun (or jsBrowserDevelopmentRun), open the page, then open DevTools and find your Kotlin files under the Sources panel, where breakpoints and stepping work. For Wasm, enable the DevTools custom formatters setting so Kotlin objects display as Kotlin values rather than opaque WasmGC references. Chromium-based browsers have the most complete Wasm debugging; Firefox and Safari can step through code but show less detail.

See Kotlin docs — Debug Kotlin/Wasm code.

Three habits save time. Read the browser console first: an unhandled Kotlin exception appears there with a Kotlin stack trace. Check the Network tab for the .wasm file: a wrong Content-Type (it must be application/wasm) or a failed compressed download prevents instantiation. And test the production build occasionally, because dead-code elimination and optimisation (Binaryen) can expose bugs that the development build hides.

A web app is a folder of static files, so any static host works. Build the production distribution, then upload the folder. For TrailMate the demo is hosted on GitHub Pages with a workflow that builds on every push to main.

See Kotlin docs — Publish your application.

See GitHub Docs — Using custom workflows with GitHub Pages.

GitHub Pages serves the app from a sub-path (/trailmate/), so keep asset and script references relative, as the index.html above does, rather than starting them with a slash. GitHub Pages does not let you set response headers, so it cannot send Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy; the Kotlin/Wasm app does not require them, but libraries that need SharedArrayBuffer do. Hosts like Netlify, Cloudflare Pages or your own server can set them. Large downloads benefit from gzip or Brotli compression enabled on the host. The general publishing and CI picture, including iOS and Android, is in the section’s publishing pages; the sibling workflow for building the Kotlin code itself is described in Getting Started and Tooling.