Home

Awesome

sbt-rjs

Build Status

Setup

An SBT plugin to perform RequireJs optimization.

To use this plugin use the addSbtPlugin command within your project's plugins.sbt file:

addSbtPlugin("com.github.sbt" % "sbt-rjs" % "2.0.0")

Your project's build file also needs to enable sbt-web plugins. For example with build.sbt:

lazy val root = (project in file(".")).enablePlugins(SbtWeb)

As with all sbt-web asset pipeline plugins you must declare their order of execution e.g.:

pipelineStages := Seq(rjs)

You can include your scripts into the web page with the conventional RequireJS setup. E.g.:

<script data-main="/javascripts/main.js"
        src="/lib/requirejs/require.js"></script>

WebJars are treated specially. If a path is referenced that is part of a path belong to a Webjar then the webjarCdn setting is used to translate it to the CDN. This is all fully automatic and provided as part of a buildWriter function. Furthermore if a .bin or -bin equivalent of the resource is available then it is used. The end result is that all WebJar sourced resources are located via a CDN along with their minified versions.

Options

RequireJs optimization permits build profiles to be declared that specify what needs to be done. A standard build profile for the RequireJS optimizer is provided. You are able to use and/or customize settings already made, and add your own. Here are a list of relevant settings and their meanings:

OptionDescription
appBuildProfileThe project build profile contents.
appDirThe top level directory that contains your app js files. In effect, this is the source folder that rjs reads from.
baseUrlThe dir relative to the assets or public folder where js files are housed. Will default to "js", "javascripts" or "." with the latter if the other two cannot be found.
buildProfileBuild profile key -> value settings in addition to the defaults supplied by appBuildProfile. Any settings in here will also replace any defaults.
dirBy default, all modules are located relative to this path. In effect this is the target directory for rjs.
generateSourceMapsBy default, source maps are generated.
mainConfigBy default, 'main' is used as the module for configuration.
mainConfigFileThe full path to the above.
mainModuleBy default, 'main' is used as the module.
modulesThe json array of modules.
optimizeThe name of the optimizer, defaults to uglify2.
pathsRequireJS path mappings of module ids to a tuple of the build path and production path. By default all WebJar libraries are made available from a CDN and their mappings can be found here (unless the cdn is set to None).
preserveLicenseCommentsWhether to preserve comments or not. Defaults to false given source maps (see http://requirejs.org/docs/errors.html#sourcemapcomments).
webJarCdnsCDNs to be used for locating WebJars. By default "org.webjars" is mapped to "jsdelivr".
webJarModuleIdsA sequence of webjar module ids to be used.

Supposing that your application does not use "main.js" as its main entry point and instead uses app.js:

RjsKeys.mainModule := "app"

(note the absence of the file extension).

If you wish to add a property that this plugin does not provide, but is available to rjs then you can provide a map of additional properties. Supposing that you wish to specify the locale to be used:

import WebJs._
import RjsKeys._

...

buildProfile := JS.Object("locale" -> "en-au")

buildProfile is a JS.Object, a map of String -> JS values. WebJs.JS is required to be imported.

WebJs automatically converts common types, like strings, numbers, maps, and sequences, to the JS type. For example, given an example from the rjs documentation you can express:

import WebJs._
import RjsKeys._

...

modules += JS.Object("name" -> "foo/bar/bip", "exclude" -> Seq("foo/bar/bop"))

The plugin is built on top of JavaScript Engine which supports different JavaScript runtimes.