Add WASM support: --wasm flag with Node.js and Deno runtimes by lostflydev · Pull Request #4176 · VirtusLab/scala-cli

lostflydev · 2026-03-11T14:26:10Z

Implements scala-cli issue #3316: integrate WebAssembly with Scala CLI.

--wasm CLI flag and //> using wasm directive to enable WASM output
--wasm-runtime <runtime> option and //> using wasmRuntime directive Supported values: node (default), deno, wasmtime, wasmedge, wasmer
--deno-version, --wasmtime-version, --wasmer-version options and corresponding directives for pinning runtime versions
Node.js (default): runs Scala.js WASM output with --experimental-wasm-exnref flag, requires Node.js >= 22
Deno: runs Scala.js WASM output; if not found on PATH, downloads from GitHub releases via Coursier cache
Wasmtime / WasmEdge / Wasmer: return UnsupportedWasmRuntimeError pending upstream Scala.js standalone WASM support (Make Scala.js Wasm backend suitable for standalone Wasm VMs (a.k.a. support "server-side Wasm") scala-js/scala-js#4991)

Gedochao · 2026-03-11T16:24:00Z

cc @tanishiking @Florian3k @sjrd @lbialy

Gedochao · 2026-03-11T16:34:44Z

@lostflydev I will go over the review in the coming days (this is a hefty one, might take a bit), but in the meantime - it seems the reference doc hasn't been generated.
Refer to https://github.com/VirtusLab/scala-cli/blob/main/CONTRIBUTING.md#rules-for-a-well-formed-pr

bishabosha · 2026-03-11T16:36:02Z

+  * Deno is first looked up on the system PATH. If not found, it is downloaded from GitHub releases
+  * and cached via Coursier's ArchiveCache.
+  */
+object WasmRuntimeDownloader {


what is the current behavior for scala-cli run --js foo.scala? i could be wrong but i would think it does not download a runtime

Yeah, I also wondering the current behavior for that command.
I'm not sure about the policy on downloading the runtime through scala-cli (I personally don't like it though), but I believe downloading runtime stuff should be in different PR, because it's not very relevant to "supporing wasm".

I'd treat WASM runtimes similar to how we treat node with Scala.js - the user needs to download it themselves, rather than Scala CLI doing it for them.

Scala-cli has --jvm flag and downloads jvm by itself. This behaviour with wasm runtime downloading looks similar.

@dos65 JVM is key to Scala CLI's core functionalities, and thus it's treated as a major dependency.
Node is considered necessary setup for Scala.js, similar to how clang is for Scala Native.
I understand this is blurry and vague, but I think we will expect the user to install WASM runtimes on their own, rather than do it out of the box here (certainly out of scope for this PR, but feel free to start a dedicated discussion or issue on this as a follow-up).

@Gedochao
Actually it was impelemented because it was written in #3316 - Additionally, I'd like to be able to choose a runtime and let Scala CLI download it for me.

I don't have any preference of having this functionality - I only want to clarify if this thing really isn't required.

You got me there. 😅
Not sure why did I define the requirements this way when creating the issue.
Will amend it there.
My bad.

tanishiking · 2026-03-12T02:56:35Z

+  * Deno is first looked up on the system PATH. If not found, it is downloaded from GitHub releases
+  * and cached via Coursier's ArchiveCache.
+  */
+object WasmRuntimeDownloader {


Yeah, I also wondering the current behavior for that command.
I'm not sure about the policy on downloading the runtime through scala-cli (I personally don't like it though), but I believe downloading runtime stuff should be in different PR, because it's not very relevant to "supporing wasm".

tanishiking · 2026-03-12T03:07:26Z

+  // Standalone runtimes (future - requires upstream Scala.js standalone WASM support)
+  case object Wasmtime extends WasmRuntime("wasmtime")
+  case object WasmEdge extends WasmRuntime("wasmedge")
+  case object Wasmer   extends WasmRuntime("wasmer")


If they don't work, I feel we don't need to add those options yet

Gedochao · 2026-03-12T09:47:17Z

(converted to a draft, as this clearly needs more work; feel free to change it back when it's ready to review)

Gedochao · 2026-03-17T08:06:13Z

(I can see the post-review changes, but a rebase will be necessary to re-run the CI)

lostflydev · 2026-03-18T11:14:51Z

(I can see the post-review changes, but a rebase will be necessary to re-run the CI)

Hi @Gedochao ! I`ve rebased onto actual main, could you pls re-run CI/CD

He-Pin · 2026-04-06T19:44:41Z

why not use bun as a runtime

lostflydev · 2026-04-19T10:12:41Z

why not use bun as a runtime

@He-Pin Thanks for comment, added bun as a runtime

Implements scala-cli issue VirtusLab#3316: integrate WebAssembly with Scala CLI. - `--wasm` CLI flag and `//> using wasm` directive to enable WASM output - `--wasm-runtime <runtime>` option and `//> using wasmRuntime` directive Supported values: node (default), deno - `--deno-version`, `--wasmtime-version`, `--wasmer-version` options and corresponding directives for pinning runtime versions - **Node.js** (default): runs Scala.js WASM output with `--experimental-wasm-exnref` flag, requires Node.js >= 22 - **Deno**: runs Scala.js WASM output

…imes - Move --wasm flag to dedicated Wasm help group with --help-wasm option - Simplify wasmOptions parsing with fold/toRight pattern - Add runtime validation with UnrecognizedWasmRuntimeError in directives - Auto-enable WASM when wasmRuntime directive is set - Update reference documentation Code style: simplify denoNeedsWasmFlag, explicit runtime match cases, clean type annotation, scalfmt

…smRuntime bun) - Add BunNotFoundError with install hint - Add integration test for Bun (conditional on bun being on PATH) - Add actions/setup-node@v6 node-version:24 to all Linux integration test jobs: the default Node.js on ubuntu-24.04 runners is too old for Scala.js WASM GC (which requires Node.js >= 22). Matches docs-tests job which already pins node-version: 24

@main

Node 24 still ships V8 12.x where wasm-exnref is gated behind --experimental-wasm-exnref; the flag only flips to default in V8 13.x (Node 25+). The previous nodeMajorVersion < 24 guard therefore left Node 24 (the version pinned in CI) without the flag, which made any Scala.js WASM code using exception bytecodes, runtime throws, JS interop or Scala 3 @main fail at runtime. Same reasoning applies to Deno (Deno 2.x = V8 12.x). Until V8 13.x is the default everywhere, just always set the flag, there is no any overhead

lostflydev · 2026-05-12T04:11:34Z

Hi @Gedochao, could you please re-run the failed native-windows-tests-default (https://github.com/VirtusLab/scala-cli/actions/runs/25658534589/job/75315398257?pr=4176#logs) job? I think it might be flaky
and not caused by the changes in this PR

Gedochao · 2026-05-12T06:30:42Z

Yep, almost certainly flaky. I restarted it.
There's a bunch of flaky tests and GitHub is very unstable this week, ping me if anything else needs restarting.

lostflydev · 2026-05-12T08:13:01Z

Hi @tanishiking @sjrd @Florian3k @lbialy @dos65 👋

Gentle ping — the PR is ready for another look. Addressed previous feedback: dropped runtime auto-download and unsupported standalone runtimes, added Bun support, rebased, fixed style and docs.
All required CI checks are green.

Whenever you have a spare moment, I'd really appreciate your feedback

tanishiking · 2026-05-12T08:47:42Z

+final case class WasmOptions(
+  @Group(HelpGroup.Wasm.toString)
+  @Tag(tags.experimental)
+  @HelpMessage("Enable WebAssembly output (Scala.js WASM backend). Uses Node.js by default. To show more options for WASM pass `--help-wasm`")


Let's use "Wasm" instead of "WASM" ;)

A contraction of “WebAssembly”, not an acronym, hence not using all-caps.
https://webassembly.github.io/spec/core/intro/introduction.html#wasm

tanishiking · 2026-05-12T09:18:15Z

    }
+    else if (emitWasm) {
+      // For WASM mode with ES modules, run node directly instead of NodeJSEnv.
+      // NodeJSEnv's stdin piping with "-" doesn't work with Input.ESModule.


I believe it works with ESModule, and we don't need this else if (emitWasm) branch. What didn't work here?

tanishiking · 2026-05-12T09:26:23Z


+  // 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] =


I'm not sure about scala-cli policy, but I feel like detecting node version if it supports wasm or not is too much.

my 2 cents: scala-cli should loosely couple with the runtime environment, just try to run and let them fail if it's too old.

tanishiking · 2026-05-12T09:34:04Z

+      nodeMajorVersion.foreach { v =>
+        if (v < 22) value(Left(new NodeVersionTooOldForWasmError(v)))
+      }
+    val nodeFlags = if (emitWasm && nodeNeedsWasmFlag) List("--experimental-wasm-exnref") else Nil


I don't think tools like scala-cli to hardcode Node options, and instead, let users explicitly specify Node options by themselves something like like: --node-args=--experimental-wasm-exnref,--experimental-wasm-imported-strings ?

in Node 26, options like --experimental-wasm-imported-strings is removed, and --experimental-wasm-exnref is now enabled by default (and may eventually be removed as well). If scala-cli hardcode options, we'll be in trouble when underlying runtime (node) removes options.

tanishiking · 2026-05-12T09:49:28Z

+  * @param runtime
+  *   The WASM runtime to use for execution (node, deno)
+  */
+final case class WasmOptions(


Making wasm a standalone option sounds like it's an another platform like JS/JVM/Native/Wasm, but in reality everything is passed as scala-js options.

It makes more sense to register it as one of the scala-js options, like --js-wasm under ScalaJSOptions. WDYT?

tanishiking · 2026-05-12T09:53:45Z

Just left some drive by comments. (Also, I think adding deno and bun should be in a separate issue/PR).
Anyway, good work, thank you :)

Gedochao linked an issue Mar 11, 2026 that may be closed by this pull request

Integrate WASM with Scala CLI #3316

Open

7 tasks

Gedochao requested review from Gedochao, tgodzik and zielinsky March 11, 2026 16:25

bishabosha reviewed Mar 11, 2026

View reviewed changes

tanishiking reviewed Mar 12, 2026

View reviewed changes

Gedochao marked this pull request as draft March 12, 2026 09:46

lostflydev force-pushed the scala-wasm-support branch from 80fe137 to 40df564 Compare March 18, 2026 11:05

lostflydev force-pushed the scala-wasm-support branch from 40df564 to f138e4c Compare March 22, 2026 08:30

lostflydev force-pushed the scala-wasm-support branch 3 times, most recently from 3358e24 to 7f43349 Compare April 2, 2026 15:27

lostflydev marked this pull request as ready for review April 2, 2026 15:28

lostflydev requested review from bishabosha, dos65 and tanishiking April 2, 2026 15:28

lostflydev force-pushed the scala-wasm-support branch from 7f43349 to 0794656 Compare April 7, 2026 10:42

lostflydev force-pushed the scala-wasm-support branch from 0794656 to 721bbcf Compare April 19, 2026 10:11

lostflydev marked this pull request as draft April 28, 2026 06:35

lostflydev force-pushed the scala-wasm-support branch from 721bbcf to 714e11a Compare May 6, 2026 09:01

lostflydev marked this pull request as ready for review May 6, 2026 09:02

lostflydev added 2 commits May 10, 2026 22:10

lostflydev added 3 commits May 10, 2026 22:10

scalafmt after rebase

077bf00

lostflydev force-pushed the scala-wasm-support branch from 714e11a to 077bf00 Compare May 11, 2026 08:16

tanishiking reviewed May 12, 2026

View reviewed changes

Conversation

lostflydev commented Mar 11, 2026

Uh oh!

Gedochao commented Mar 11, 2026

Uh oh!

Gedochao commented Mar 11, 2026

Uh oh!

bishabosha Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanishiking Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gedochao commented Mar 12, 2026

Uh oh!

Gedochao commented Mar 17, 2026

Uh oh!

lostflydev commented Mar 18, 2026

Uh oh!

He-Pin commented Apr 6, 2026

Uh oh!

lostflydev commented Apr 19, 2026

Uh oh!

lostflydev commented May 12, 2026

Uh oh!

Gedochao commented May 12, 2026

Uh oh!

lostflydev commented May 12, 2026

Uh oh!

tanishiking May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanishiking May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanishiking May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanishiking May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanishiking commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bishabosha Mar 11, 2026 •

edited

Loading

tanishiking Mar 12, 2026 •

edited

Loading

tanishiking May 12, 2026 •

edited

Loading

tanishiking May 12, 2026 •

edited

Loading

tanishiking May 12, 2026 •

edited

Loading

tanishiking May 12, 2026 •

edited

Loading

tanishiking commented May 12, 2026 •

edited

Loading