Managing Web Dependencies in Play with WebJars

November 1, 2013
webjars Play! Play

A common need in applications is to manage your web dependencies like Bootstrap and jQuery. The simplest way of doing this is to download the appropriate files, store them in your application directory and reference them in your application. There are a couple of disadvantages to this approach.

For starters, it is not always clear which version of the asset was downloaded. Sometimes it is encoded in the name of the file or the directory structure, for e.g., “jquery-1.9.0.min.js”, but I guess the onus is on the development team to keep it this way. The other disadvantage I see with this approach is it is quite manual. For example, updating versions of javascript libraries with their respective dependencies can be rather tedious. So enter WebJars, a very simple library that integrates with Play as well as other web frameworks, that packages client-side web libraries as JAR files and allows for them to be managed as SBT dependencies (or Maven and Gradle). This article will show you the steps required to integrate WebJars into a sample Play application.

The first thing you need to do is edit the build.sbt file. Add the WebJar dependency. Your build.sbt file should look like the following.

name := "sample-play-with-webjars"

version := "1.0-SNAPSHOT"

libraryDependencies ++= Seq(
  javaJdbc,
  javaEbean,
  cache,
  "org.webjars" %% "webjars-play" % "2.2.0"
)     

play.Project.playJavaSettings

Add a WebJars dependency like Bootstrap to the build.sbt file. You can find a list of dependencies on the official WebJars site. I'm including Bootstrap into my Play application as an example.

name := "sample-play-with-webjars"

version := "1.0-SNAPSHOT"

libraryDependencies ++= Seq(
  javaJdbc,
  javaEbean,
  cache,
  "org.webjars" %% "webjars-play" % "2.2.0",
  "org.webjars" % "bootstrap" % "3.0.1"
)     

play.Project.playJavaSettings

Now go to your conf/routes file and add in a route to the WebJarsAssets controller that will be used when accessing the dependencies.

# Routes
# This file defines all application routes (Higher priority routes first)
# ~~~~

# Home page
GET     /                           controllers.Application.index()

# Map static resources from the /public folder to the /assets URL path
GET     /assets/*file               controllers.Assets.at(path="/public", file)

GET     /webjars/*file                    controllers.WebJarAssets.at(file)

Now add a reference to the bootstrap css from your app/views/main.scala.html file via the WebJar route we just defined.
It should look like this:

@(title: String)(content: Html)

<!DOCTYPE html>

<html>
    <head>
        <title>@title</title>
        <link rel="stylesheet" media="screen" href="@routes.Assets.at("stylesheets/main.css")">
        <link rel="shortcut icon" type="image/png" href="@routes.Assets.at("images/favicon.png")">
        <link rel='stylesheet' href='@routes.WebJarAssets.at(WebJarAssets.locate("css/bootstrap.min.css"))'>
        <script src="@routes.Assets.at("javascripts/jquery-1.9.0.min.js")" type="text/javascript"></script>
    </head>
    <body>
        @content
    </body>
</html>

To prove that everything works, I've changed app/views/index.scala.html to use the sample progress bar from Bootstrap to make it really obvious that WebJars has been configured properly and that the Bootstrap dependency has been resolved. Your file should look like the following:

@(message: String)

@main("Testing out WebJars") {


      <div class="page-header">
        <h1>Progress bars</h1>
      </div>
      <div class="progress">
        <div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;"><span class="sr-only">60% Complete</span></div>
      </div>

}

Now if you start up the application and navigate to http://localhost:9000, your default home page should look like the following.
```
$ play run
```

The sample code for this article is up here. I hope this article showed you a better way of managing your web dependencies.

Read more