Kotlin Web

Kotlin Web Frontend

Patterns for building web frontends in Kotlin. Three approaches with clear selection criteria.

Current Versions (May 2026)

Do not write pre.886 or other floating wrapper versions; use the BOM pattern: implementation(platform("org.jetbrains.kotlin-wrappers:kotlin-wrappers-bom:2026.5.2")) then non-versioned dependencies.

Targets at a glance — do not confuse them

Two distinct Kotlin targets sit behind "web", and each picks a different framework family:

When Decision Tree picks Compose WASM → use wasmJs("web"). When it picks React/Vue → use js(IR). Do not try to put React on wasmJs or Compose for Web on js(IR) — different ecosystems entirely.

A KMP project can host both targets simultaneously (e.g. an internal admin via WASM and a public-facing site via JS+React); they are separate Gradle modules with separate build.gradle.kts files.

Decision Tree

Правило выбора: Compose WASM — для быстрых MVP и внутренних инструментов. Для продакшн-приложений с серьёзными требованиями к UX, производительности и доступности — Kotlin/JS + React или Vue.

Option 1: Compose for Web (WASM) — MVP / Internal Tools

Choose when:

• Быстрый MVP или прототип с максимальным переиспользованием мобильного UI
• Internal tools, admin panels, dashboards (ограниченная аудитория)
• Team is Kotlin-first, нет JS/TS экспертизы и не планируется нанимать
• Допустимы ограничения: большой бандл, нет SEO, ограниченная доступность (a11y)

Don't choose when:

• Production-facing продукт с внешними пользователями
• Need SSR/SEO
• Нужна полноценная доступность (screen readers, ARIA) — Compose WASM рендерит в canvas, DOM-based a11y отсутствует
• Need extensive npm ecosystem (charting, rich text editors, maps)
• Bundle size is critical (Compose WASM ~2-5MB initial)
• Need to integrate into existing JS/TS app
• Ожидается длительная поддержка и развитие фронтенда

Limitations to be aware of:

• Canvas-based rendering: нет нативных DOM-элементов, нет инспектора элементов в браузере
• Accessibility: практически отсутствует (no screen reader support)
• Mobile web: тяжёлый бандл на мобильных сетях
• Ecosystem maturity: Compose for Web всё ещё в активной разработке, API может меняться

Option 2: Kotlin/JS + React — Production Web Apps

Choose when:

• Production-facing продукт, нужна зрелая экосистема
• Need React ecosystem (existing components, npm libraries)
• Team knows React patterns or willing to learn
• Integrating Kotlin business logic into React frontend
• Need SSR via Next.js
• Нужна полная доступность (a11y), SEO, performance

Don't choose when:

• No React experience on team AND tight deadlines
• Pure Kotlin stack preferred AND это внутренний инструмент (→ Compose WASM)

Option 3: Kotlin/JS + Vue — Production Web Apps

Choose when:

• Production-facing продукт, предпочитается Vue ecosystem
• Need Vue ecosystem (Vuetify, Quasar, PrimeVue)
• Vue's reactivity model feels natural (similar to Kotlin Flow)
• Single File Components (SFC) preferred
• Team knows Vue patterns

Don't choose when:

• No Vue experience on team
• Need maximum community support (React has larger Kotlin/JS community)

Comparison Matrix

Compose WASM Setup

Project Structure

composeApp/
└── src/
    ├── commonMain/kotlin/       # Shared UI + logic
    ├── wasmJsMain/kotlin/       # Web entry point
    │   ├── Main.kt
    │   └── platform/
    │       ├── WasmStorage.kt   # localStorage
    │       └── WasmPlatform.kt  # Browser APIs
    └── wasmJsMain/resources/
        └── index.html

Entry Point

// wasmJsMain/kotlin/Main.kt
import androidx.compose.ui.ExperimentalComposeUiApi
import androidx.compose.ui.window.CanvasBasedWindow

@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    CanvasBasedWindow(canvasElementId = "ComposeTarget") {
        App()
    }
}

CanvasBasedWindow (from Compose MP, ExperimentalComposeUiApi) mounts Skiko canvas into DOM element by id. ID string MUST match <canvas id="ComposeTarget"> in wasmJsMain/resources/index.html — mismatch = blank page, no error. Conventional id: ComposeTarget.

Build Configuration — wasmJs target

// composeApp/build.gradle.kts
kotlin {
    wasmJs("web") {
        browser {
            commonWebpackConfig {
                outputFileName = "composeApp.js"
            }
            devServer {
                port = 8080
                // optional:
                // open = true
                // static = mutableListOf("$rootDir/composeApp/src/wasmJsMain/resources")
            }
        }
        binaries.executable()
    }
}

Target-name string ("web" in wasmJs("web")) sets Gradle source-set prefix — produces webMain / webTest source sets alongside default wasmJsMain. Older docs show wasmJs(IR) — deprecated; named-target form (wasmJs("web") or bare wasmJs { ... }) is now standard. Pick one convention per module and stick to it; mixing breaks source-set resolution.

devServer.port defaults to a free port — set explicitly to avoid clashes with other dev servers (Vite 5173, CRA 3000, Spring 8080 — careful). static list adds extra resource roots beyond wasmJsMain/resources (rarely needed; default already serves index.html).

WASM Limitations

Browser API Interop

// Access browser APIs from WASM
import kotlinx.browser.window
import kotlinx.browser.document

fun getCurrentUrl(): String = window.location.href

fun setPageTitle(title: String) {
    document.title = title
}

// Using external JS functions
external fun fetch(url: String): Promise<Response>

Reference: references/compose-wasm.md for advanced patterns

Kotlin/JS Common Setup

Both React and Vue approaches share these fundamentals:

Gradle Configuration

// build.gradle.kts
plugins {
    alias(libs.plugins.kotlinMultiplatform)
}

kotlin {
    js(IR) {
        browser {
            commonWebpackConfig {
                cssSupport { enabled.set(true) }
            }
        }
        binaries.executable()
    }

    sourceSets {
        jsMain.dependencies {
            // Shared Kotlin modules
            implementation(projects.core.common)
            implementation(projects.core.network)

            // npm dependencies
            implementation(npm("axios", "1.7.0"))
        }
    }
}

npm Interop Pattern

// Declare external npm module
@JsModule("axios")
@JsNonModule
external fun axios(config: dynamic): Promise<dynamic>

// Type-safe wrapper
suspend fun <T> httpGet(url: String): T {
    val response = axios(js("{ method: 'get', url: url }")).await()
    return response.data.unsafeCast<T>()
}

State Bridging (Kotlin Flow → JS Framework)

// Bridge Kotlin StateFlow to framework-observable state

// Common pattern for both React and Vue:
class StateBridge<T>(private val flow: StateFlow<T>) {
    private val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())

    fun subscribe(callback: (T) -> Unit): () -> Unit {
        val job = scope.launch {
            flow.collect { callback(it) }
        }
        return { job.cancel() }
    }

    fun currentValue(): T = flow.value
}

Reference: references/kotlin-js-react.md for React-specific patterns

Reference: references/kotlin-js-vue.md for Vue-specific patterns

Shared Code Strategy

What to Share Between Mobile and Web

Module Structure for Shared Code

project/
├── shared/
│   ├── core/                    # Domain models, utils
│   │   └── src/commonMain/
│   ├── data/                    # Repository interfaces, DTOs
│   │   └── src/commonMain/
│   └── domain/                  # Use cases
│       └── src/commonMain/
│
├── composeApp/                  # Compose WASM + mobile
│   └── src/
│       ├── commonMain/          # Shared Compose UI
│       ├── androidMain/
│       ├── iosMain/
│       └── wasmJsMain/
│
└── webApp/                      # Kotlin/JS + React/Vue (if not using Compose WASM)
    └── src/jsMain/

Build & Run Commands

# Compose WASM
./gradlew :composeApp:wasmJsBrowserDevelopmentRun      # Dev server
./gradlew :composeApp:wasmJsBrowserDistribution        # Production

# Kotlin/JS
./gradlew :webApp:jsBrowserDevelopmentRun              # Dev server
./gradlew :webApp:jsBrowserDistribution                # Production

Integration with Other Skills