Month: October 2014

Intro to sbt-web

Inside sbt-web: Part I – Using sbt-web


sbt-web is an sbt-based web infrastructure for handling client-side files. It serves as the new foundation for the Playframework and potentially any other sbt-based web project. sbt-web defines a basic directory structure (overriden in Play), and it offers an API for processing sources, static files, and reporting errors.


Why do we need a new web infrastructure, why was the old one not good enough?

When Play 2.0 was conceived in 2011, the developers chose to integrate several client-side technologies: CoffeeScript, LESS, Google Closure, and later RequireJS. These were tightly integrated into Play, so everyone who wanted to use something different (e.g. SASS or Dust) had to first learn sbt, write a plugin, and somehow deal with integrating that framework into Play’s build mechanism. This obviously wasn’t a flexible enough solution.

Additionally, no-one could foresee the activity and speed of innovation in the JavaScript world1. Every week there’s a new framework coming out, and existing ones make steady progress. The Node.js community alone is around 10x bigger than the Play community, so keeping CoffeeScript and LESS inside Play up-to-date was a daunting task.

It became more and more difficult to catch up. At some point it wasn’t even possible to update Twitter Bootstrap because of newer LESS features that weren’t supported by Play. And the Play team simply didn’t have the resources to update client-side dependencies every couple of weeks.

So with Play 2.3 the decision was made to factor out any client-side concerns into a new independent project called sbt-web. sbt-web introduces the notion of assets to sbt. Taken from the Rails world, assets are simply files that are served to and displayed or otherwise processed by the web browser.

sbt-web is organized via sbt plugins that use sbt-web’s infrastructure to make integrating and updating the latest tools easier.

Project Layout

The basic project structure2 defined by sbt-web adapts to the standard sbt (or Maven) conventions and essentially adds the assets folder to the mix.

The input folder is src/main/assets for source files that are potentially converted (e.g. from CoffeeScript to JavaScript) or otherwise processed both while developing and in production. src/main/public is for static assets. When preparing for production-readiness (staging), the two will be merged and processed.

Please note that the subfolder organization below assets is only an example, sbt-web doesn’t require you to use a specific naming scheme (or any subfolder at all for that matter).

There is also a src/main/test/assets folder indicating that sbt-web also supports testing client-side code.

+ src --+ main ----+ assets ------+ js ----+ public ------+ css ------+ images ------+ js --+ test ----+ assets ------+ js ----+ public ------+ css ------+ images ------+ js ▸ Read more...