Depending on Scala.js libraries

To be able to use a Scala library in Scala.js, it has to be separately compiled for Scala.js. You then can add it to your library dependencies as follows:

  1. libraryDependencies += "org.scala-js" %%% "scalajs-dom" % "1.0.0"

Note the %%% (instead of the usual %%) which will add the current Scala.js version to the artifact name. This allows to

  • Cross-publish libraries to different Scala.js versions
  • Disambiguate Scala.js artifacts from their JVM counterparts

Some Scala.js core libraries (such as the Scala.js library itself) do not need the %%% since their version number is the Scala.js version number itself.

Note that you can also use %%% in a Scala/JVM project, in which case it will be the same as %%. This allows you to use the same libraryDependencies settings when cross compiling Scala/JVM and Scala.js.

Deprecated: Depending on JavaScript libraries

The jsDependencies mechanism should be considered deprecated.Use scalajs-bundler instead.

Scala.js 1.x note: since Scala.js 1.x, this functionality is not part of the core Scala.js sbt plugin.Instead, it is provided by sbt-jsdependencies.

The rest of this section applies to Scala.js 0.6.x only.

Thanks to WebJars, you can easily fetch a JavaScript library like so:

  1. libraryDependencies += "org.webjars" % "jquery" % "2.1.4"

This will fetch the required JAR containing jQuery. However, it will not include it once you run your JavaScript code, since there is no class-loading process for JavaScript.

The Scala.js sbt plugin has jsDependencies for this purpose. You can write:

  1. jsDependencies += "org.webjars" % "jquery" % "2.1.4" / "2.1.4/jquery.js"

This will make your project depend on the respective WebJar and include a file named **/2.1.4/jquery.js in the said WebJar when your project is run or tested. We are trying to make the semantics of “include” to be as close as possible to writing:

  1. <script type="text/javascript" src="..."></script>

All jsDependencies and associated metadata (e.g. for ordering) are persisted in a file (called JS_DEPENDENCIES) and shipped with the artifact your project publishes. For example, if you depend on the scalajs-jquery package for Scala.js, you do not need to explicitly depend or include jquery.js; this mechanism does it for you.

Note: This will not dump the JavaScript libraries in the file containing your compiled Scala.js code as this would not work across all JavaScript virtual machines. However, the Scala.js plugin can generate a separate file that contains all raw JavaScript dependencies (see below).

Scoping to a Configuration

You may scope jsDependencies on a given configuration, just like for normal libraryDependencies:

  1. jsDependencies += "org.webjars" % "jquery" % "2.1.4" / "jquery.js" % "test"

CommonJS name

Some (most?) JavaScript libraries try to adapt the best they can to the environment in which they are being executed.When they do so, you have to specify explicitly the name under which they are exported in a CommonJS environment (such as Node.js), otherwise they won’t work when executed in Node.js.This is the purpose of the commonJSName directive, to be used like this:

  1. jsDependencies += "org.webjars" % "mustachejs" % "0.8.2" / "mustache.js" commonJSName "Mustache"

which essentially translates to a prelude

  1. var Mustache = require("mustache.js");

when running with Node.js from sbt (with run, test, etc.).

Dependency Ordering

Since JavaScript does not have a class loading mechanism, the order in which libraries are loaded may matter. If this is the case, you can specify a library’s dependencies like so:

  1. jsDependencies += "org.webjars" % "jasmine" % "1.3.1" / "jasmine-html.js" dependsOn "jasmine.js"

Note that the dependee must be declared as explicit dependency elsewhere, but not necessarily in this project (for example in a project the current project depends on).

Local JavaScript Files

If you need to include JavaScript files which are provided in the resources of your project, use:

  1. jsDependencies += ProvidedJS / "myJSLibrary.js"

This will look for myJSLibrary.js in the resources and include it. It is an error if it doesn’t exist. You may use ordering and scoping if you need.

Write a Dependency File

If you want all JavaScript dependencies to be concatenated to a single file (for easy inclusion into a HTML file for example), you can set:

  1. skip in packageJSDependencies := false

in your project settings. The resulting file in the target folder will have the suffix -jsdeps.js.