Supercharge Your Scala.js Apps: A Deep Dive into the Experimental WebAssembly Backend

Ready to take your Scala.js projects to the next level? The experimental WebAssembly (Wasm) backend offers a glimpse into the future of high-performance web applications. This comprehensive guide will walk you through everything you need to know, from the benefits and limitations to setup and optimization strategies. Dive in and discover how to harness the power of Wasm for your Scala.js projects.

What is the Scala.js WebAssembly Backend?

Introduced in Scala.js 1.17.0, the experimental WebAssembly backend provides an alternative to the standard JavaScript backend. Wasm promises near-native performance in the browser and other environments. The key idea is that, under ideal circumstances, and with necessary configurations, it could serve as a seamless substitute for the existing JavaScript backend.

Why Use the Experimental Wasm Backend? Exploring the Potential Benefits

While still experimental, the Wasm backend holds significant promise. It aims to boost performance and efficiency. Though it may not be better than the JS backend right now, it provides many possibilities. Here's what you can expect:

Enhanced Performance: In certain scenarios, Wasm can significantly outperform JavaScript, leading to snappier applications.
Future-Proofing: Embracing Wasm positions your projects at the forefront of web technology. This will make your projects ready for future advancements.
Code Size Reduction: Though currently larger, future optimizations aim to shrink the Wasm code size, leading to faster load times.

Understanding the Experimental Status: Risks and Considerations

Before diving in, be aware of the "experimental" label. This translates into a few key considerations:

Potential Removal: The Wasm backend might be removed in later Scala.js updates, highlighting the need to stay updated if you're integrating it.
Evolving Requirements: Future Scala.js versions could require newer Wasm engines, potentially dropping support for older environments. It is important to make sure you can support the newest versions.
Ongoing Development: Performance and code size might not yet match the optimized JavaScript backend. This means it might be slower.

Wasm Backend Requirements: What You Need to Get Started

To use the Wasm backend, ensure your environment meets these prerequisites:

JavaScript Host: Standalone Wasm isn't generated; a JavaScript host environment is mandatory.
Wasm Engine Support: Your engine must support Wasm 3.0, Wasm GC, and exception handling.
ESModule Module Kind: The ESModule module kind is required for compatibility.
Strict Floats: Enabled by default since Scala.js 1.9.0, strict floats are necessary.

Supported engines include Node.js 22+, Chrome, and Firefox (with specific flags enabled).

Key Limitations of the Wasm Backend: What Doesn't Work (Yet)

Currently, the Wasm backend has a couple of notable limitations:

No @JSExport Support: The @JSExport and @JSExportAll annotations are ignored. This prevents JavaScript code from directly calling exported Scala methods.
Single Module Emission Only: The backend only supports emitting single modules. This requires setting the module split style to ModuleSplitStyle.FewestModules.

Minimal Setup: Configuring Your sbt Project for Wasm

Enabling the Wasm backend is straightforward. Add the following to your sbt build:

scalaJSLinkerConfig := {
  scalaJSLinkerConfig.value
    .withExperimentalUseWebAssembly(true)
    .withModuleKind(ModuleKind.ESModule)
},

jsEnv := {
  val config = NodeJSEnv.Config()
    .withArgs(List(
      "--experimental-wasm-exnref",
      "--experimental-wasm-imported-strings",
      "--turboshaft-wasm",
    ))
  new NodeJSEnv(config)
},

Supported Engines: Configuring Node.js, Chrome, and Firefox

To unleash the Wasm backend, you may need to configure your local environment and browser. Here’s how to configure each browser.

Node.js 22+: Use the --experimental-wasm-exnref, --experimental-wasm-imported-strings, and --turboshaft-wasm flags.
Chrome: Enable "Experimental WebAssembly" in chrome://flags/.
Firefox: Enable javascript.options.wasm_exnref in about:config and disable javascript.options.wasm_js_string_builtins.

Performance Considerations: What to Expect

Wasm backend performance can vary. Performance of the generated code may either be faster or slower than the JS backend, depending on the codebase. Further optimizations are underway.

Decoding Code Size: Comparing Wasm to JavaScript

Currently, the Wasm backend generates code approximately twice the size of the JavaScript backend in fullLink mode. Future optimizations using wasm-opt aim to reduce this significantly.

Diving Deeper: Implementation Details and Resources

Interested in the inner workings? Start with the technical readme of the Wasm backend. Additional resources include:

By understanding the capabilities and limitations of the experimental Scala.js WebAssembly backend, you can strategically leverage its power to create cutting-edge web applications.