RequireJs optimizer plugin for sbt-web
Scala JavaScript HTML CoffeeScript
Pull request Compare This branch is 96 commits ahead of huntc:master.
Latest commit abd912a Jun 5, 2016 @huntc huntc Update README.md

README.md

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.typesafe.sbt" % "sbt-rjs" % "1.0.8")

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:

Option Description
appBuildProfile The project build profile contents.
appDir The top level directory that contains your app js files. In effect, this is the source folder that rjs reads from.
baseUrl The 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.
buildProfile Build profile key -> value settings in addition to the defaults supplied by appBuildProfile. Any settings in here will also replace any defaults.
dir By default, all modules are located relative to this path. In effect this is the target directory for rjs.
generateSourceMaps By default, source maps are generated.
mainConfig By default, 'main' is used as the module for configuration.
mainConfigFile The full path to the above.
mainModule By default, 'main' is used as the module.
modules The json array of modules.
optimize The name of the optimizer, defaults to uglify2.
paths RequireJS 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).
preserveLicenseComments Whether to preserve comments or not. Defaults to false given source maps (see http://requirejs.org/docs/errors.html#sourcemapcomments).
webJarCdns CDNs to be used for locating WebJars. By default "org.webjars" is mapped to "jsdelivr".
webJarModuleIds A 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.

© Typesafe Inc., 2014