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.
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.
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/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