Category: Scala & Playframwork

Play’s Liaison with sbt

Have you ever wondered why you no longer play on the command line1, but execute sbt or activator? And why is Play only ever referred to in plugins.sbt and not your build.sbt’s libraryDependencies, but still, you can use its API in your code? And how does Play – run?

The sbt Plugin

The Playframework is separated into multiple modules, and with each new version, more parts of it are factored out into their own modules. The best known is simply called play – it contains the API that you as a developer interact with when developing a Play application.

The part that is running your application is actually an sbt plugin, and you can find it in the aptly named module sbt-plugin.

All plugins that your build uses must be specified in project/plugins.sbt, and are then in scope in each sub-project. To be more precise, Play is an auto-plugin2. As the name suggests, auto plugins can enable themselves automatically. Play does not use this feature however – because you want to specifically enable either the Scala or the Java plugin.

// Use Play with Scala lazy val root = (project in file(".")).enablePlugins(PlayScala) // Use Play with Java lazy val root = (project in file(".")).enablePlugins(PlayJava) ▸ Read more...

Playframework 2.4 Dependency Injection (DI)


The Playframework 2.4 has been released after one year of development with the biggest new feature being Dependency Injection (DI). But injecting dependencies, what’s the point? And why does Play require it?

Obviously you were already able to use DI in your Play applications, except for the Play API itself. In previous versions of Play, there is the central Global object which holds global mutable state. Another such object is the currently running Application. Both would cause issues in testing and in development mode when you did not organize and isolate code carefully. This leaked into the application lifecycle and the plugin system, for example you have to define a plugin priority and make sure that external components are instantiated lazily and closed after an app restart (in development mode).

Dependency Injection in Play 2.4 essentially tries1 to get rid of global state and simplifies writing isolated, resuable, and testable code by instantiating components on each reload and by providing stop hooks.

Runtime DI

The runtime DI mechanism defined by Java Specification Request 330, with its reference implementation Guice, has been selected as the default DI framework. This makes it rather straightforward to start writing new Play applications without worrying too much about DI, as components are injected automatically by using the @Inject annotation. The official documentation on runtime DI is pretty complete so I will not go into detail about it.

Compile-Time DI

Guice as a standard mechanism makes sense for a framework that offers a first-class Java API.
As a Scala developer however, you might not be too keen on relying on reflection and runtime instantiation. Luckily, Play also provides a compile-time DI mechanism.

In its simplest form, compile-time DI, or any DI for that matter, is just constructor parameter DI. All of your dependencies are declared as constructor parameters in your classes, be it controllers, actors, or any other class. The Application Loader, which replaces the Global object, prepares all dependencies and instantiates your classes by passing their dependencies into their constructor. The link from controllers to route handling is made by creating a (generated) router that maps routes to instantiated controllers – again, via its constructor.

This requires enabling injected routes in your build.sbt:

routesGenerator := InjectedRoutesGenerator

An Application Loader’s main job is to is provide the current Application.

To do this, you will assemble all of the classes required by your app. All parts of Play, now called components, support compile-time DI by providing a trait that ends with Components and builds on three basic dependencies: ApplicationLifecycle, Configuration, Environment2.

ApplicationLifecycle allows your component to register a stop hook. Configuration is the TypesafeConfig that you would previously get from a running application. Environment is a collection of methods that revolve around your running Play app, such as the classloader, dev/test/production mode, and obtaining resources.

The base component trait BuiltInComponentsFromContext extracts environment and configuration from the Application Loader’s context, and instantiates applicationLifecycle.

Let’s say we have a small app with one Application controller that needs to make a webservice call. Now instead of importing WS and the current application, we mix in a trait at the application loader level and pass a concrete WS instance to the controller.

import play.api.{ApplicationLoader, BuiltInComponentsFromContext} import import play.api.routing.Router import router.Routes // Routes are generated from routes file class AppLoader extends ApplicationLoader { override def load(context: Context): Application = new AppComponents(context).application } class AppComponents(context: Context) extends BuiltInComponentsFromContext(context) with NingWSComponents { // NingWSComponents has a lazy val wsClient lazy val applicationController = new controllers.Application(wsClient) lazy val assets = new controllers.Assets(httpErrorHandler) override def router: Router = new Routes(httpErrorHandler, applicationController) } ▸ Read more...

Play Angular Require Seed Updates

This is just a short post illustrating the latest updates in my Play-Angular-RequireJS Seed.

Play 2.4

The biggest obvious change is the update to the latest version of the Playframework, 2.4. Play 2.4 offers several ways of using Dependency Injection. In my opinion, a Scala project should aim to use compile-time DI, so the seed uses exactly that. It’s simple to use, type-safe, and eliminates a lot of global state. If you prefer using Guice or any other runtime DI mechanism, it shouldn’t be too hard to change that. ▸ Read more...

Understanding sbt and sbt-web settings

Inside sbt-web: Part II – Understanding sbt and sbt-web’s settings

Just enough sbt

If we want to talk about sbt-web, we must first discuess a few concepts related to sbt itself1. sbt is the Scala Build Tool, often critized for being overly complex. It however enables a lot of interesting use cases, so one might argue its not incidental but domain-related complexity2.

Let’s first look at the abstractions sbt provides and then go on to understand how sbt-web builds on them.


A build definition corresponds to the project you’re building. Each build can consist of multiple sub-builds, with one being the root project, or root build. Each project contains a top-level build file, build.sbt, that corresponds to the root build. .sbt files allow a subset of Scala syntax, and are compiled by sbt to Scala files. Alternatively you can write Scala build files directly (all build-related Scala files go into the project folder), but with the recent additions to sbt, this is rarely needed.

If you don’t provide a build file, sbt will infer a standard build for you.

A typical project might look like this:

my-project/ build.sbt < -- root build file project/ <-- definitions for all sub-projects <-- define sbt version plugins.sbt <-- sbt plugins Common.scala <-- common build code my-domain-model <-- sub-project build.sbt <-- sub-project build file src/main/scala/... <-- sources my-play-web-ui build.sbt app conf my-play-admin-web-ui build.sbt app conf ▸ Read more...

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

PlayBasics Updated for Play 2.3.2

Over the weekend I have updated most of the PlayBasics projects to the latest version of the Playframework, 2.3.2. This includes the move to sbt-web and its plugins. ▸ Read more...

RequireJS Optimization with Play 2.2, WebJars, and CDNs

The Story So Far

This post is just a short follow-up to my previous post about using RequireJS with Play 2.1 and WebJars. In that post I laid out a general approach on how to modularize your Play app using RequireJS, and how to make it production-ready by dividing your RequireJS configuration into several files (one for development, one for production, one for building). This is obviously flawed and can be an easy source of errors when the versions of your WebJars assets don’t match up with CDN versions. It also violates the DRY principle. At the time however it was the only way to use these technologies together.

Meanwhile, In Another Galaxy

Direct RequireJS support

In the meantime, James Ward has been actively developing WebJars and its accompanying Play plugin with two notable enhancements.

First off, WebJars now supports RequireJS directly (previously, it was only limited to the Play plugin). This means it is no longer required to write require(['webjars!angular.js'], function(angular) {...}). Instead require(['angular.js'], function(angular) {...}) is sufficient. To differentiate WebJars libraries from local JavaScript files, the local ones should be prefixed with ./.

For example:

require(['angular', './common'], function(angular) { angular.module('myModule', ['common']); }); ▸

Ping Conference, Play Edition, Day 2


“We want to go crazy about technology today”

Continuing with the second day of the awesome Ping Conference, with no further ado, I’ll shortly summarize the talks. Here we go! ▸ Read more...

Ping Conference, Play Edition, Day 1

PingConf logo

Ping Conference, Play Edition, Day 1

A few days ago I attended Ping Conf, the first ever conference about Play, organized by Peter Hausel (@pk11), and Gawker Media in Budapest. ▸ Read more...

Playframework 2.2 Action Building and Action Composition

Play 2.2 Building and Composing Actions

New Results in 2.2

One of Play 2.2’s biggest changes is the complete overhaul of the Action and Results architecture. While it did work pretty well in earlier versions, there also used to be a great variety of Results to choose from:

  • Result
  • PlainResult
  • SimpleResult
  • AsyncResult
  • ChunkedResult

Play 2.2 reduces all this to SimpleResult (to be renamed to Result in 2.3). The previous result types have been deprecated and will be removed in Play 2.31.

This leads to the following mapping:

Play 2.0/2.1 Play 2.2
Result, SimpleResult, PlainResult SimpleResult
AsyncResult Future[SimpleResult]
ChunkedResult SimpleResut (via Status.chunked(Enumerator))



To produce a SimpleResult or Future[SimpleResult] easily, Actions now work differently than before.

The official documentation is sparse as always, so I want to give an overview over the changed principles of Actions and Action composition. This article doesn’t show many code examples because I created a new PlayBasics sub-project that walks you through the presented concepts.


On the top of the Action hierarchy sits EssentialAction2, already introduced with Play 2.1 and until now mostly used when dealing with EssentialFilters or streaming data directly from the request.

An EssentialAction is closer at Play’s implementation details than an Action. It is defined like this:

trait EssentialAction extends (RequestHeader => Iteratee[Array[Byte], SimpleResult])

So an EssentialAction extends a function from RequestHeader to an Iteratee. If that confuses you, just rewrite it as a class:

class EssentialAction extends Function1[-RequestHeader,+Iteratee[Array[Byte], SimpleResult]] { def apply(rh: RequestHeader): Iteratee[Array[Byte], SimpleResult] } ▸ Read more...