Concatenation of JavaScript files is useful because JavaScript code bases are usually modularized so that the code is easier to reuse and maintain. Yet, the JavaScript language has no built-in support for modules, but several tools or libraries make modularization possible, such as Browserify or RequireJS.

At the time of writing this, there is only one plugin for RequireJS: sbt-rjs. This plugin runs the RequireJS optimizer on your code base to concatenate and minify it.

To use it, you first need to add it to the build in the project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-rjs" % "1.0.1")

Then, add it to the assets pipeline process in your build.sbt file:

pipelineStages := Seq(rjs)

You also need the require.js client-side runtime in order to load modules from the client side. Get it from http://requirejs.org and place it somewhere in your assets source directory, for example, in app/assets/lib/requirejs/require.js.

Now, let's modularize your code base. Define two modules, logic.coffee and ui.coffee, decoupling the application's behavior and user interface:

// ui.coffee
define(() ->
  (node) ->
    delete: () ->
      li = node.parentNode
      li.parentNode.removeChild(li)
    forEachClick: (callback) ->
      node.addEventListener('click', callback)
)

// logic.coffee
define(['ui'], (Ui) ->
(node, id) ->
    ui = Ui(node)
    ui.forEachClick(() ->
      xhr = new XMLHttpRequest()
      route = routes.controllers.Items.delete(id)
      xhr.open(route.method, route.url)
      xhr.addEventListener('readystatechange', () ->
        if xhr.readyState == XMLHttpRequest.DONE
          if xhr.status == 200
            ui.delete()
          else
            alert('Unable to delete the item!')
      )
      xhr.send()
    )
)

The ui module defines a function that takes as a parameter a root DOM node corresponding to an item's delete button and returns an object with two methods. The first one, delete, removes the item from the DOM, and the second one, forEachClick, registers a callback on click events on the item delete button. The logic module depends on the ui module and defines a function that takes an item delete button node and ID as parameters and sets up its behavior.

Finally, update the shop module to use the logic module:

require(['logic'], (Logic) ->
  for deleteBtn in document.querySelectorAll('button.delete-item')
    do (deleteBtn) -> Logic(deleteBtn, deleteBtn.dataset.id)
)

The preceding code finds all item delete buttons and sets up their logic.

CoffeeScriptKeys.bare := true

The RequireJS optimizer can usually be configured by command-line arguments or by using a JavaScript configuration object. With sbt-rjs, you can set up such a JavaScript configuration object from your build.sbt file. For instance, here is how we can set the main module's name to be shop, instead of the default main:

RjsKeys.mainModule := "shop"

Refer to the documentation of the sbt-rjs plugin for more information.

def javascriptRouter = Action { implicit request =>
    val router = Routes.javascriptRouter("routes")(
      routes.javascript.Items.delete
    )
Ok(JavaScript(
  s"""
    define(function )() { $router; return routes })
  """
))"
  }

define(['ui', 'routes'], (Ui, routes) ->
  …
)

RjsKeys.paths += "routes" -> ("routes", "empty:")

Now, if you run your application in the production mode (using the start sbt command), your JavaScript and CSS files will be minified and all the dependencies of the main module will be concatenated in a single resulting file.

pipelineStages in Assets := Seq(rjs)

Gzipping web assets can save some bandwidth. The sbt-gzip plugin compresses all the .html, .css, and .js assets of your application. For each asset, it produces a compressed file with the same name suffixed with .gz. The Play Assets controller handles these files for you; when it is asked to serve a resource, if a resource with the same name but suffixed with .gz is found and if the client can handle the gzip compression, the compressed resource is served.

To use it, add the plugin to your project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-gzip" % "1.0.0")

Add the gzip task to the asset's pipeline in your build.sbt file:

pipelineStages := Seq(rjs, gzip)

Now, run your application and request, for instance, the /assets/stylesheets/shop.css resource, and while setting this, you can handle the gzip compression (by using the Accept-Encoding header):

$ curl -H "Accept-Encoding: gzip" http://localhost:9000/assets/stylesheets/shop.css 
□□TH*-)□□□KI□I-I□□,I□U□□RP(□,□L□□□,□□R□□LIIͳ□□□□ɴ□□/K-"F□□□
□□owTg%

You get a compressed version of the resource, as expected. If you don't set the Accept-Encoding header, you get the uncompressed version, as expected too:

$ curl http://localhost:9000/assets/stylesheets/shop.css 
li button.delete-item {
  visibility: hidden;
}
li:hover button.delete-item {
  visibility: visible;
}

As explained previously, in the production mode, the Assets controller sets the Cache-Control header to max-age=3600, telling web browsers that they can cache the result for one hour before requesting it again.

However, typically your assets won't change until the next deployment, so web browsers can probably cache them for a duration longer than one hour. However, if a client makes a request in the hour preceding a redeployment, it will keep outdated assets in its cache.

You can solve this problem by following this principle: if you want a client to cache a resource, then this resource should never change. If you have a newer version of the resource, then you should use a different URL for it.

Assets fingerprinting helps you achieve this. The idea is that when your application is packaged for production, an MD5 hash of each web asset is computed from its contents and written in a file with the same name, but suffixed with .md5. When the application is running, if the Assets reverse router finds a resource along with its hash, it generates the resource URL by concatenating the file name to its hash. The next time the application is deployed, if an asset has changed, it also changes its hash and then its URL. So, web browsers can cache versioned assets for an infinite duration.

To enable assets versioning, you must use the versioned action of the Assets controller:

GET  /assets/*file   controllers.Assets.versioned(path="/public", file)

Also, update all the places (for example, in the HTML templates) where you reverse routed the Assets.at action to use the Assets.versioned action.

When reverse routed, this action looks for a resource with the same name as file, but suffixed with .md5, containing the file hash, to build a URL composed of the hash contents and the file name. So, you need to generate a hash for each of your web assets, and this is exactly what the sbt-digest plugin does.

Enable this plugin by adding it to your project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-digest" % "1.0.0")

Add the digest task to the assets pipeline in your build.sbt file:

pipelineStages := Seq(rjs, gzip, digest)

Now, when your application is prepared for production, a hash file is generated for each of your web assets so that the Assets controller can generate a unique URL for a given asset. Also, as your asset URLs refer to resources that never change, the caching policy is more aggressive; now, the Cache-Control header is set to max-age=31536000, thus telling web browsers that they can cache the result for one year.

If you are curious, take a look at the URLs generated by the reverse routing process. Consider, for instance, the following line in the layout.scala.html template:

@routes.Assets.versioned("stylesheets/shop.css")

It produces the following URL:

/assets/stylesheets/91d741f219aa65ac4f0fc48582553fdd-shop.css