scalajs-webpack-loader

Webpack loader for Scala.js.
Import Scala.js code in a Webpack project, without having to set up a separate Scala build.

scalajs-webpack-loader is similar to scalajs-bundler in that it is a tool that uses Webpack to bundle Scala.js code alongside JavaScript code. Use scalajs-bundler if your build tool is SBT, and use scalajs-webpack-loader if your build tool is Webpack.

The loader supports Scala.js 1.x. It should also work on Scala.js 0.6.15 – 0.6.33, but note that only 1.x is tested for and explicitly supported.

Installing

Install scalajs-webpack-loader as a dev-dependency of your NPM package by running:

$ npm install --save-dev scalajs-webpack-loader

scalajs-webpack-loader currently requires at least Node v10.0. Check your version using:

$ node -v

Usage

Basic usage

This example assumes the following directory structure:

├── src/
|   ├── js/
|   |   └── index.js
|   └── scala/
|       ├── .sjsproject
|       └── HelloWorld.scala
├── webpack.config.js
└── package.json

scalajs-webpack-loader allows you to import a Scala.js module into another Webpack module. A Scala.js module is a directory containing *.scala files, with an empty .sjsproject file at the root. Here, we can define HelloWorld.scala as follows:

import scalajs.js.annotation._

@JSExportTopLevel("HelloWorld")
object HelloWorld {
  @JSExport
  def sayHello(): Unit = {
    println("Hello world!")
  }
}

You can then import the Scala.js module in index.js as follows:

import { HelloWorld } from "../scala/.sjsproject";

HelloWorld.sayHello();

You should add scalajs-webpack-loader to your webpack.config.js:

module.exports = {
  // Configure entry and output paths:
  entry: "src/js/index.js",
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "bundle.js"
  },
  // ...
  // Add scalajs-webpack-loader:
  module: {
    rules: [
      {
        test: /\.sjsproject$/,
        use: [
          {
            loader: "scalajs-webpack-loader",
            options: {
              // verbosity: "warn",
              // mainMethod: "Main.main",
              // etc. See "Loader options" below
            }
          }
        ]
      }
    ]
  }
};

Run npx webpack to create the output bundle. The loader will download dependencies, compile the Scala.js code to the target folder, and bundle it with the JS module. Executing the output bundle in Node.js gives the following output:

$ node dist/bundle.js
Hello world!

Loader options

Option key	Type	Default	Description
mainMethod	string or undefined	undefined	Execute the specified main(Array[String]) method on startup
verbosity	"trace", "debug", "info", "warn", "error" or "silent"	"info"	Do not display log levels below specified verbosity
targetDirectory	string	"target"	Target directory for intermediary Scala build artifacts
scalaVersion	string	"2.13.1"	Version of the Scala compiler
scalaJSVersion	string	"1.0.0"	Version of the Scala.js compiler
libraryDependencies	array of strings	[]	List of Scala.js dependencies, e.g. ["com.lihaoyi:::upickle:0.9.9"]
scalacOptions	array of strings	[]	List of scalac options, e.g. ["-Xfatal-warnings"]

For the libraryDependencies options, use the Mill format for dependencies. You can use Scaladex to see what that looks like for your specific dependencies. Use ::: to get the Scala.js artifact (e.g. com.lihaoyi:::upickle:0.9.9), and :: for the Scala artifact (e.g. org.scala-lang.modules::scala-async:0.10.0).

Development

To develop the code in this repo, you will need to have sbt and npm installed on your system. Run npm install after cloning the repo to get all JS dependencies of this project.

All development commands can be run with NPM. Note that some of these commands depend on the NODE_ENV environment variable, which can either be set to production or development; if it isn't set, it's interpreted as development. Depending on the environment variable, some commands will execute in development (fast) mode or in production (slow, optimized) mode.

npm run ...	Description
build	Run a full build
build:scalajs	Build Scala.js sources in mode dictated by NODE_ENV
build:scalajs:production	Build Scala.js sources in production mode (fullOptJS)
build:scalajs:development	Build Scala.js sources in development mode (fastOptJS)
build:bundle	Build final output bundle in mode dictated by NODE_ENV
test	Run all tests
test:package	Test that package.json is valid
test:format:scala	Test formatting of Scala files with scalafmt
test:format:js	Test formatting of JS and config files
test:integration	Run integration tests
test:unit	Run Scala.js unit tests
fix	Run all automatic fixes
fix:format:scala	Run scalafmt fixes for all Scala files
fix:format:js	Run Prettier fixes for all JS and config files
clean	Delete all build artifacts
clean:scalajs	Delete Scala.js build artifacts
clean:bundle	Clean Webpack's dist/bundle.js
clean:fixtures	Clean local caches and build artifacts from integration test fixtures

Remember to build before testing.

Scalafmt commands try to run the CLI, and fall back to using SBT. If you run these commands frequently, you may want to install the scalafmt CLI for faster execution of these commands (coursier install scalafmt if you have Coursier installed on your PATH).

To release a new version, run npm version patch, npm version minor or npm version major. Travis CI will automatically deploy the new version once the CI build passes.