skip to content

What is the @ExperimentalWasmDsl marker and when do you need to opt in to it?

level: juniorimportance: should knowfreq 40%

answer

  1. Opt-in marker on the Wasm Gradle DSL
  2. Built on @RequiresOptIn; use @OptIn
  3. Compile-time only, no runtime effect
  4. Package org.jetbrains.kotlin.gradle
  5. Different from WasmGC/exception proposals

basics

~20 s

It is an annotation that marks the Wasm parts of the Gradle build DSL as experimental. You add an opt-in (like @OptIn) when calling wasmJs() or wasmWasi(), acknowledging that this configuration API may still change.

solid answer

~40 s

`@ExperimentalWasmDsl` (in `org.jetbrains.kotlin.gradle.ExperimentalWasmDsl`) is a Kotlin **opt-in requirement annotation** applied to the Kotlin Gradle plugin's Wasm DSL — `wasmJs { }`, `wasmWasi { }` and related configuration. Because the Wasm targets are still experimental, the compiler refuses to compile your `build.gradle.kts` against these APIs unless you explicitly opt in, which signals you accept that the API surface may change in a future Kotlin release. You opt in per call site with `@OptIn(org.jetbrains.kotlin.gradle.ExperimentalWasmDsl::class)`, or project-wide via the Kotlin opt-in mechanism. It's part of Kotlin's general experimental-API machinery (`@RequiresOptIn`), the same pattern used for things like `@ExperimentalCoroutinesApi`. It does not affect runtime behavior — it's a build-time signal only.

go deeper

for a junior

Knows you must add an opt-in to use the Wasm targets in Gradle.

for a middle

Explains it is a @RequiresOptIn-based marker on the Gradle DSL, compile-time only, with per-call or project-wide opt-in.

for a senior

Distinguishes the DSL marker from Wasm runtime proposals and from stdlib opt-in markers, and knows where to configure project-wide opt-in.

for a principal

Frames experimental opt-in as part of API-stability governance and weighs the risk of building production tooling on experimental DSLs.

## Kotlin's opt-in system Kotlin lets library authors mark unstable APIs with an **opt-in requirement annotation**, defined using **`@RequiresOptIn`**. Any code that touches such an API must explicitly acknowledge it, otherwise the compiler raises an error (or warning). You acknowledge it either: - locally with **`@OptIn(SomeMarker::class)`** on the using declaration, or - globally by listing the marker in the compiler's opt-in options. This is purely a **compile-time contract** — it does not change generated code or runtime behavior. It exists so that experimental APIs can evolve without silently breaking unaware users. ## @ExperimentalWasmDsl specifically `@ExperimentalWasmDsl` lives in the **Kotlin Gradle plugin** (package `org.jetbrains.kotlin.gradle`). It marks the **Gradle DSL for the Wasm targets** as experimental: declaring `wasmJs { }` or `wasmWasi { }` and configuring them touches annotated members, so your build script must opt in. ```kotlin kotlin { @OptIn(org.jetbrains.kotlin.gradle.ExperimentalWasmDsl::class) wasmJs { browser() } } ``` Without the opt-in, the build fails to configure with an error telling you the Wasm DSL requires opt-in. ## Why it matters - It signals that the **build configuration API** (not necessarily your runtime code) may change between Kotlin versions — a real concern while Wasm targets stabilize. - It is distinct from experimental markers that gate **runtime/stdlib** APIs; this one only gates the **Gradle DSL**. - It is unrelated to Wasm's own experimental proposals (WasmGC, exception handling) — those are runtime/toolchain concerns, while `@ExperimentalWasmDsl` is a Kotlin opt-in convention. ## Practical tips - You can apply `@OptIn` directly above the `wasmJs`/`wasmWasi` call, or opt in for the whole script. - Keep the fully qualified name handy: `org.jetbrains.kotlin.gradle.ExperimentalWasmDsl`.

  • Does @ExperimentalWasmDsl change anything at runtime?
    No. It is a build-time opt-in marker; it only forces you to acknowledge the experimental Gradle DSL and has zero effect on the emitted Wasm.
  • How do you opt in for the whole project instead of per call site?
    Add the marker to the Kotlin compiler's opt-in options (e.g. via compilerOptions optIn) so you don't repeat @OptIn at each call site.

saying these in an interview costs you the question

  • Saying it enables WasmGC or the exception-handling proposal
  • Thinking it affects runtime behavior or output binary
  • Confusing it with stdlib markers like @ExperimentalCoroutinesApi in purpose
  • Believing you can use wasmJs/wasmWasi without any opt-in

context

resolving links…