Wasm: probe runtime for exnref, rename to JSRuntime, test Deno/Bun on CI, add guide

- Rename WasmRuntime -> JSRuntime and move --js-wasm-runtime into the JS option group
- Detect whether each runtime accepts --experimental-wasm-exnref instead of hardcoding or version-gating it. The Scala.js Wasm backend compiles exceptions with the exnref proposal, but whether a runtime needs the flag is non-monotonic across versions: a throwing program runs unflagged on Node 22.22 and 24 yet crashes on Node 22.0 and 23.11, while Deno 2.8 (V8 14.9) removed the flag entirely (passing it aborts). So Scala CLI probes the binary once and passes the flag only when accepted - injected where exnref is still gated, skipped where it was removed. Node takes it as a CLI arg, Deno via DENO_V8_FLAGS; both log when applied. Bun runs on JavaScriptCore and needs no flag.
- Add integration tests exercising real exception handling under Wasm on deno and bun (a throwing program, unlike println, actually needs exnref)
- Log implicit ES-module enabling only when --js-module-kind is unset; only warn "module-kind ignored" when the chosen kind isn't ES
- Install Deno and Bun in all five jvm-tests CI jobs so the guarded Deno/Bun Wasm tests actually run
- Add guides/advanced/scala-wasm.md and regenerate the reference docs

Author: lostflydev

.github/workflows/ci.yml

@@ -202,6 +202,10 @@ jobs:
     - uses: actions/setup-node@v6
       with:
         node-version: 24
+    - uses: denoland/setup-deno@v2
+      with:
+        deno-version: v2.x
+    - uses: oven-sh/setup-bun@v2
     - name: JVM integration tests
       if: env.SHOULD_RUN == 'true'
       run: ./mill -i integration.test.jvm
@@ -243,6 +247,10 @@ jobs:
     - uses: actions/setup-node@v6
       with:
         node-version: 24
+    - uses: denoland/setup-deno@v2
+      with:
+        deno-version: v2.x
+    - uses: oven-sh/setup-bun@v2
     - name: JVM integration tests
       if: env.SHOULD_RUN == 'true'
       run: ./mill -i integration.test.jvm
@@ -284,6 +292,10 @@ jobs:
     - uses: actions/setup-node@v6
       with:
         node-version: 24
+    - uses: denoland/setup-deno@v2
+      with:
+        deno-version: v2.x
+    - uses: oven-sh/setup-bun@v2
     - name: JVM integration tests
       if: env.SHOULD_RUN == 'true'
       run: ./mill -i integration.test.jvm
@@ -325,6 +337,10 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 24
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+      - uses: oven-sh/setup-bun@v2
       - name: JVM integration tests
         if: env.SHOULD_RUN == 'true'
         run: ./mill -i integration.test.jvm
@@ -366,6 +382,10 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 24
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+      - uses: oven-sh/setup-bun@v2
       - name: JVM integration tests
         if: env.SHOULD_RUN == 'true'
         run: ./mill -i integration.test.jvm

modules/build/src/main/scala/scala/build/internal/Runner.scala

@@ -189,36 +189,31 @@ object Runner {
       run(command, logger, cwd = cwd, extraEnv = extraEnv)
   }
 
-  // Detects the major version of Node.js on PATH; cached for the JVM lifetime (lazy val).
-  // Returns None if node is not found or version cannot be parsed.
-  private lazy val nodeMajorVersion: Option[Int] =
+  // The Scala.js Wasm backend compiles exceptions using the Wasm exnref proposal. Whether a runtime
+  // needs --experimental-wasm-exnref is not predictable from its version: a throwing program runs
+  // unflagged on Node 22.22 and 24 but crashes on Node 23.11 and Node 22.0, while Deno 2.8 removed the
+  // flag entirely (passing it aborts). So we neither hardcode the flag nor detect versions; we ask the
+  // runtime whether it accepts the flag and pass it only then - never withholding it where exceptions
+  // need it, never passing it where it was removed. Bun runs on JavaScriptCore and needs no such flag.
+  private val wasmExnrefFlag = "--experimental-wasm-exnref"
+
+  // Whether `command` (which passes the exnref flag) exits successfully, i.e. the runtime accepts it.
+  private def acceptsWasmExnref(command: Seq[String], extraEnv: Map[String, String]): Boolean =
     try {
-      val process = new ProcessBuilder("node", "--version")
-        .redirectErrorStream(true)
-        .start()
-      val output = new String(process.getInputStream.readAllBytes()).trim
-      process.waitFor()
-      // Node version format: "v22.5.0" -> extract 22
-      if (output.startsWith("v"))
-        output.drop(1).takeWhile(_.isDigit) match {
-          case s if s.nonEmpty => Some(s.toInt)
-          case _               => None
-        }
-      else None
-    }
-    catch {
-      case _: Exception => None
+      val builder = new ProcessBuilder(command*)
+        .redirectOutput(ProcessBuilder.Redirect.DISCARD)
+        .redirectError(ProcessBuilder.Redirect.DISCARD)
+      extraEnv.foreach { case (k, v) => builder.environment().put(k, v) }
+      builder.start().waitFor() == 0
     }
+    catch { case _: Exception => false }
 
-  // Pre-V8 13.x runtimes need --experimental-wasm-exnref for the Scala.js Wasm exception model.
-  // V8 13.x ships in Node 25+ (Node 24 is still on V8 12.x where exnref is gated behind the flag).
-  // In Node 26+, the flag may be removed from the CLI. Only pass it when Node < 25.
-  // None.forall(_ < 25) == true — safe fallback when version detection fails.
-  private def nodeNeedsWasmFlag: Boolean = nodeMajorVersion.forall(_ < 25)
+  // Node takes the flag as a CLI arg; Deno takes it via the DENO_V8_FLAGS env var.
+  private def nodeAcceptsWasmExnref(nodePath: String): Boolean =
+    acceptsWasmExnref(Seq(nodePath, wasmExnrefFlag, "-e", ""), Map.empty)
 
-  // Deno 2.x bundles V8 12.x where wasm-exnref is gated behind a flag; symmetrical reasoning to Node.
-  // We always set DENO_V8_FLAGS=--experimental-wasm-exnref on Wasm output until V8 13.x lands in Deno.
-  private def denoNeedsWasmFlag: Boolean = true
+  private def denoAcceptsWasmExnref(denoPath: String): Boolean =
+    acceptsWasmExnref(Seq(denoPath, "eval", "0"), Map("DENO_V8_FLAGS" -> wasmExnrefFlag))
 
   private def endsWithCaseInsensitive(s: String, suffix: String): Boolean =
     s.length >= suffix.length &&
@@ -257,7 +252,7 @@ object Runner {
   ): Seq[String] = {
 
     val nodePath  = findInPath("node").fold("node")(_.toString)
-    val nodeFlags = if (emitWasm && nodeNeedsWasmFlag) List("--experimental-wasm-exnref") else Nil
+    val nodeFlags = if (emitWasm && nodeAcceptsWasmExnref(nodePath)) List(wasmExnrefFlag) else Nil
     val command   = Seq(nodePath) ++ nodeFlags ++ Seq(entrypoint.getAbsolutePath) ++ args
 
     if (jsDom)
@@ -282,10 +277,10 @@ object Runner {
       value(findInPath("node")
         .map(_.toString)
         .toRight(NodeNotFoundError()))
-    val nodeFlags = if (emitWasm && nodeNeedsWasmFlag) List("--experimental-wasm-exnref") else Nil
-    if (emitWasm && nodeFlags.nonEmpty)
+    val nodeFlags = if (emitWasm && nodeAcceptsWasmExnref(nodePath)) List(wasmExnrefFlag) else Nil
+    if (nodeFlags.nonEmpty)
       logger.log(
-        s"Wasm: adding ${nodeFlags.mkString(" ")} (required for Wasm exception handling on Node.js < 25)"
+        s"Wasm: adding ${nodeFlags.mkString(" ")} to Node.js (required by the Scala.js Wasm backend for exception handling)"
       )
     if !jsDom && allowExecve && Execve.available() then {
       val command = Seq(nodePath) ++ nodeFlags ++ Seq(entrypoint.getAbsolutePath) ++ args
@@ -367,18 +362,23 @@ object Runner {
         .map(_.toString)
         .toRight(DenoNotFoundError()))
     val denoFlags = Seq("run", "--allow-read")
-    val wasmFlag  = "--experimental-wasm-exnref"
     val extraEnv  =
-      if (emitWasm && denoNeedsWasmFlag) {
+      if (emitWasm && denoAcceptsWasmExnref(denoPath)) {
         // Append to any existing DENO_V8_FLAGS rather than replacing them.
         val existing = sys.env.get("DENO_V8_FLAGS").filter(_.nonEmpty)
-        val merged   = existing.fold(wasmFlag)(f => s"$f $wasmFlag")
+        val merged   = existing.fold(wasmExnrefFlag)(f => s"$f $wasmExnrefFlag")
         logger.log(
           s"Wasm: setting DENO_V8_FLAGS=$merged (required for Wasm exception handling)"
         )
         Map("DENO_V8_FLAGS" -> merged)
       }
-      else Map.empty[String, String]
+      else {
+        if (emitWasm)
+          logger.debug(
+            "Wasm: Deno does not accept --experimental-wasm-exnref; assuming exnref is enabled by default"
+          )
+        Map.empty[String, String]
+      }
 
     if (allowExecve && Execve.available()) {
       val command = Seq(denoPath) ++ denoFlags ++ Seq(entrypoint.getAbsolutePath) ++ args

modules/cli/src/main/scala/scala/cli/commands/run/Run.scala

@@ -18,7 +18,7 @@ import scala.build.internal.{Constants, Runner, ScalaJsLinkerConfig}
 import scala.build.internals.ConsoleUtils.ScalaCliConsole
 import scala.build.internals.ConsoleUtils.ScalaCliConsole.warnPrefix
 import scala.build.internals.EnvVar
-import scala.build.options.{BuildOptions, JavaOpt, PackageType, Platform, Scope, WasmRuntime}
+import scala.build.options.{BuildOptions, JSRuntime, JavaOpt, PackageType, Platform, Scope}
 import scala.cli.CurrentParams
 import scala.cli.commands.package0.Package
 import scala.cli.commands.setupide.SetupIde
@@ -478,9 +478,12 @@ object Run extends ScalaCommand[RunOptions] with BuildCommandHelpers {
 
           // Check if Wasm mode is requested
           if jsOpts.jsEmitWasm then {
-            val runtime  = jsOpts.wasmRuntime
+            val runtime  = jsOpts.jsRuntime
             val esModule = true // Wasm backend uses ES modules
-            logger.log("Wasm mode enabled: using ES module output on JS platform")
+            if (jsOpts.moduleKindStr.isEmpty)
+              logger.log(
+                "Wasm mode: ES module output is enabled implicitly (required by the Scala.js Wasm backend)"
+              )
             scratchDirOpt.foreach(os.makeDir.all(_))
             val jsDest = os.temp(
               dir = scratchDirOpt.orNull,
@@ -504,25 +507,25 @@ object Run extends ScalaCommand[RunOptions] with BuildCommandHelpers {
             ).map { outputPath =>
               if showCommand then
                 runtime match {
-                  case WasmRuntime.Deno =>
+                  case JSRuntime.Deno =>
                     Left(Runner.denoCommand(outputPath.toIO, args))
-                  case WasmRuntime.Node =>
+                  case JSRuntime.Node =>
                     Left(Runner.jsCommand(outputPath.toIO, args, jsDom = false, emitWasm = true))
-                  case WasmRuntime.Bun =>
+                  case JSRuntime.Bun =>
                     Left(Runner.bunCommand(outputPath.toIO, args))
                 }
               else {
                 val process = value {
                   runtime match {
-                    case WasmRuntime.Deno =>
+                    case JSRuntime.Deno =>
                       Runner.runDeno(
                         outputPath.toIO,
                         args,
                         logger,
                         allowExecve = effectiveAllowExecve,
                         emitWasm = true
                       )
-                    case WasmRuntime.Node =>
+                    case JSRuntime.Node =>
                       Runner.runJs(
                         outputPath.toIO,
                         args,
@@ -533,7 +536,7 @@ object Run extends ScalaCommand[RunOptions] with BuildCommandHelpers {
                         esModule = esModule,
                         emitWasm = true
                       )
-                    case WasmRuntime.Bun =>
+                    case JSRuntime.Bun =>
                       Runner.runBun(
                         outputPath.toIO,
                         args,

modules/cli/src/main/scala/scala/cli/commands/shared/ScalaJsOptions.scala

@@ -64,7 +64,7 @@ final case class ScalaJsOptions(
   @HelpMessage("Enable Wasm output (Scala.js Wasm backend). Uses Node.js by default. To show more options for Wasm pass `--help-wasm`")
     jsEmitWasm: Option[Boolean] = None,
 
-  @Group(HelpGroup.Wasm.toString)
+  @Group(HelpGroup.ScalaJs.toString)
   @Tag(tags.experimental)
   @HelpMessage("Wasm runtime to use: node (default), deno, bun")
     jsWasmRuntime: Option[String] = None,

modules/cli/src/main/scala/scala/cli/commands/shared/SharedOptions.scala

@@ -251,15 +251,15 @@ final case class SharedOptions(
     opts: ScalaJsOptions
   ): Either[BuildException, options.ScalaJsOptions] = {
     import opts._
-    val parsedWasmRuntime = jsWasmRuntime.fold(
-      Right(options.WasmRuntime.default): Either[BuildException, options.WasmRuntime]
+    val parsedJSRuntime = jsWasmRuntime.fold(
+      Right(options.JSRuntime.default): Either[BuildException, options.JSRuntime]
     ) { rt =>
-      options.WasmRuntime.parse(rt).toRight {
-        val validValues = options.WasmRuntime.all.map(_.name).mkString(", ")
-        new scala.build.errors.UnrecognizedWasmRuntimeError(rt, validValues)
+      options.JSRuntime.parse(rt).toRight {
+        val validValues = options.JSRuntime.all.map(_.name).mkString(", ")
+        new scala.build.errors.UnrecognizedJSRuntimeError(rt, validValues)
       }
     }
-    parsedWasmRuntime.map(wasmRuntime =>
+    parsedJSRuntime.map(jsRuntime =>
       options.ScalaJsOptions(
         version = jsVersion,
         mode = options.ScalaJsMode(jsMode),
@@ -279,7 +279,7 @@ final case class SharedOptions(
         remapEsModuleImportMap =
           jsEsModuleImportMap.filter(_.trim.nonEmpty).map(os.Path(_, Os.pwd)),
         jsEmitWasm = jsEmitWasm.getOrElse(false),
-        wasmRuntime = wasmRuntime
+        jsRuntime = jsRuntime
       )
     )
   }

modules/core/src/main/scala/scala/build/errors/UnrecognizedJSRuntimeError.scala

@@ -0,0 +1,4 @@
+package scala.build.errors
+
+class UnrecognizedJSRuntimeError(runtime: String, validValues: String)
+    extends BuildException(s"Unrecognized JS runtime: '$runtime'. Valid values: $validValues")

modules/core/src/main/scala/scala/build/errors/UnrecognizedWasmRuntimeError.scala

@@ -2,8 +2,8 @@ package scala.build.preprocessing.directives
 
 import scala.build.Positioned
 import scala.build.directives.*
-import scala.build.errors.{BuildException, UnrecognizedWasmRuntimeError}
-import scala.build.options.{BuildOptions, Platform, ScalaJsOptions, ScalaOptions, WasmRuntime}
+import scala.build.errors.{BuildException, UnrecognizedJSRuntimeError}
+import scala.build.options.{BuildOptions, JSRuntime, Platform, ScalaJsOptions, ScalaOptions}
 import scala.cli.commands.SpecificationLevel
 
 @DirectiveGroupName("Wasm options")
@@ -29,10 +29,10 @@ final case class Wasm(
 ) extends HasBuildOptions {
   def buildOptions: Either[BuildException, BuildOptions] = {
     val parsedRuntime =
-      wasmRuntime.fold(Right(WasmRuntime.default): Either[BuildException, WasmRuntime]) { rt =>
-        WasmRuntime.parse(rt).toRight {
-          val validValues = WasmRuntime.all.map(_.name).mkString(", ")
-          new UnrecognizedWasmRuntimeError(rt, validValues)
+      wasmRuntime.fold(Right(JSRuntime.default): Either[BuildException, JSRuntime]) { rt =>
+        JSRuntime.parse(rt).toRight {
+          val validValues = JSRuntime.all.map(_.name).mkString(", ")
+          new UnrecognizedJSRuntimeError(rt, validValues)
         }
       }
     parsedRuntime.map { runtime =>
@@ -46,7 +46,7 @@ final case class Wasm(
           ScalaOptions()
       BuildOptions(
         scalaOptions = scalaOptions,
-        scalaJsOptions = ScalaJsOptions(jsEmitWasm = wasmEnabled, wasmRuntime = runtime)
+        scalaJsOptions = ScalaJsOptions(jsEmitWasm = wasmEnabled, jsRuntime = runtime)
       )
     }
   }

modules/directives/src/main/scala/scala/build/preprocessing/directives/Wasm.scala

@@ -476,6 +476,49 @@ trait RunScalaJsTestDefinitions { this: RunTestDefinitions =>
       }
     }
 
+  // Exception handling exercises the Wasm exnref proposal, which older V8 gates behind a flag and
+  // newer V8 has removed. A throwing program (unlike a plain println) actually needs exnref, so this
+  // verifies it works on deno/bun (the node case is covered by "Wasm exception handling").
+  def wasmExceptionHandlingTest(runtime: String): Unit = {
+    val inputs = TestInputs(
+      os.rel / "Hello.scala" ->
+        """object Hello {
+          |  def riskyOp(x: Int): Int =
+          |    if (x == 0) throw new IllegalArgumentException("zero!")
+          |    else 100 / x
+          |
+          |  def main(args: Array[String]): Unit = {
+          |    val caught = try riskyOp(0).toString catch { case e: Exception => s"caught: ${e.getMessage}" }
+          |    println(caught)
+          |  }
+          |}
+          |""".stripMargin
+    )
+    inputs.fromRoot { root =>
+      val output = os.proc(
+        TestUtil.cli,
+        "--power",
+        "run",
+        "Hello.scala",
+        "--js-emit-wasm",
+        "--js-wasm-runtime",
+        runtime,
+        extraOptions
+      ).call(cwd = root).out.trim()
+      expect(output.linesIterator.toSeq.contains("caught: zero!"))
+    }
+  }
+
+  if (TestUtil.fromPath("deno").isDefined)
+    test("Wasm exception handling on deno") {
+      wasmExceptionHandlingTest("deno")
+    }
+
+  if (TestUtil.fromPath("bun").isDefined)
+    test("Wasm exception handling on bun") {
+      wasmExceptionHandlingTest("bun")
+    }
+
   test("Wasm multiple source files") {
     val inputs = TestInputs(
       os.rel / "Greeter.scala" ->

modules/integration/src/test/scala/scala/cli/integration/RunScalaJsTestDefinitions.scala

@@ -0,0 +1,32 @@
+package scala.build.options
+
+import java.util.Locale
+
+/** JS-based runtimes for Scala.js Wasm backend execution. All embed a Wasm engine. */
+sealed abstract class JSRuntime(val name: String)
+
+object JSRuntime {
+  case object Node extends JSRuntime("node")
+  case object Deno extends JSRuntime("deno")
+  case object Bun  extends JSRuntime("bun")
+
+  val all: Seq[JSRuntime] = Seq(Node, Deno, Bun)
+
+  def default: JSRuntime = Node
+
+  def parse(s: String): Option[JSRuntime] =
+    s.trim.toLowerCase(Locale.ROOT) match {
+      case "node" | "nodejs" => Some(Node)
+      case "deno"            => Some(Deno)
+      case "bun"             => Some(Bun)
+      case _                 => None
+    }
+
+  implicit val hashedType: HashedType[JSRuntime] = runtime => runtime.name
+
+  implicit val hasHashData: HasHashData[JSRuntime] = HasHashData.asIs
+
+  implicit val monoid: ConfigMonoid[JSRuntime] = ConfigMonoid.instance[JSRuntime](default) {
+    (a, b) => if (b == default) a else b
+  }
+}