Scalajs

Scala.js Skill

Scala.js compiles Scala source code to JavaScript, enabling type-safe, tooling-rich development for browsers and Node.js. This skill captures the canonical patterns, common pitfalls, and current (2025) ecosystem knowledge needed to produce high-quality Scala.js code and project setups.

Quick reference — read the right section

Core Concepts

How Scala.js works

Scala.js is a Scala compiler plugin + linker. The compiler emits an intermediate representation (IR), and the linker transforms IR into optimised JavaScript. Two linker modes exist:

• fastLinkJS — fast incremental link; used during development. Produces multiple small .js files (with ESModule split style) or one larger file.
• fullLinkJS — dead-code elimination + minification; used for production.

The Vite plugin @scala-js/vite-plugin-scalajs wires Vite to the linker output directory, so saving a .scala file triggers sbt's incremental compiler → linker → Vite HMR — giving a sub-second feedback loop.

Module kinds

Set via scalaJSLinkerConfig ~= _.withModuleKind(...):

Module split styles (ESModule only)

Project Setup

Prerequisites

• JDK 11+ (17 recommended)
• sbt 1.9+ or Mill 0.11+
• Node.js 18+ (for running/testing JS output)
• npm 9+ (for Vite and npm libraries)

Canonical sbt + Vite setup (Scala 3)

1. Bootstrap Vite project: npm create vite@latest myapp -- --template vanilla
2. Add sbt files — see references/sbt-build.md for full build.sbt, project/plugins.sbt, project/build.properties
3. Add Vite config: see references/sbt-build.md#vite-config
4. Write Scala entry point in src/main/scala/myapp/Main.scala
5. Run: two terminals — sbt ~fastLinkJS + npm run dev
6. Production: npm run build (triggers sbt fullLinkJS automatically via Vite plugin)

Canonical Mill + Vite setup

See references/mill-build.md.

Key Library Versions (2025)

Always use %%% (triple-percent) for cross-platform Scala.js libraries in sbt — it expands to the Scala.js artifact classifier. Use :: in Mill's ivy"..." syntax.

Writing Scala.js Code — Key Patterns

Entry point

// With scalaJSUseMainModuleInitializer := true in build.sbt:
@main def myApp(): Unit =
  // DOM is ready to use
  dom.document.querySelector("#app").textContent = "Hello!"

Accessing browser APIs

import org.scalajs.dom
import org.scalajs.dom.{document, window, console}

val el = document.getElementById("my-div")
console.log("debug", el)
window.setTimeout(() => println("deferred"), 1000)

Async / Futures

Scala.js supports Future and Promise natively. For Future:

import scala.concurrent.Future
import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue

val f: Future[String] = Future { "hello" }
f.foreach(s => console.log(s))

For full async/await-style ergonomics, prefer Cats Effect's IO or ZIO.

JavaScript interop — quick rules

• Use @js.native @JSImport(...) to import JS modules/values
• Use @js.native @JSGlobal(...) to reference global JS variables
• Use js.Dynamic.global for quick-and-dirty access (no type safety)
• Prefer typed façade traits over js.Dynamic in production code
• See references/interop.md for full façade patterns

Common Mistakes to Avoid

UI Framework Selection Guide

For new projects, Laminar is the community default. Read references/laminar.md for patterns.

When to Read Which Reference File

• Starting a project? Read references/sbt-build.md or references/mill-build.md first.
• Building a UI? Read references/laminar.md.
• Calling npm / JS libraries? Read references/interop.md + references/scalablytyped.md.
• Sharing code between JVM and JS? Read references/cross-build.md.
• Getting a build/link error? Read references/errors.md.
• Want Wasm output? Read references/wasm.md.