Designing Website Asset Caching with Scalatra

By: OmniSpearPosted on

Regardless of if you spent countless hours writing pretty CSS and JavaScript or you just need to package Bootstrap and jQuery in your application the last thing you need to worry about is loading all of your assets individually. This can wreck your sites loading times and rendering performance. Scalatra being a light weight framework for building straight forward applications and API’s doesn’t come with a prescribed solution, though WRO4J can step in to assist us with this process. We will step through the configuration of WRO4J, SBT, and finally the inclusion of these into your layouts.

To configure WRO4J we will first add it into our Build.scala or Build.sbt file. We will add a dependency in the following manner:

      libraryDependencies ++= Seq(
        "ro.isdc.wro4j" % "wro4j-core" % "1.4.0",
        ...
      )

We then need to configure our wro.xml file for our Boostrap and jQuery assets:

<?xml version="1.0" encoding="UTF-8"?>
<groups xmlns="http://www.isdc.ro/wro">
    <group name='core'>
        <css minimize="false">/css/bootstrap.min.css</css>
        <css minimize="false">/css/bootstrap-theme.min.css</css>
        <css minimize="false">/css/bootstrap-glyphicons.css</css>
        <css minimize="true">/css/app.css</css>
        <js minimize="false">/js/jquery.min.js</js>
    </group>
    <group name='bottom'>
        <js minimize="true">/js/bootstrap.min.js</js>
    </group>
</groups>

Followed by our wro.properties file which defines our WRO4J usage:

cacheUpdatePeriod=0
modelUpdatePeriod=0
debug=false
disableCache=false
gzipResources=true
ignoreMissingResources=false
jmxEnabled=true
preProcessors=cssImport,semicolonAppender
postProcessors=cssMinJawr,jsMin

Now we will adjust our layouts to point to the new compiled asset:

        <link href="/assets/core.css" rel="stylesheet" />
        <script src="/assets/core.js"></script>

While this is running you should see a local development speed improvement similar to the table below. This result will be amplified when the application is running remotely in a production environment.

To make this capability suit our needs better in development and to additionally be used for Cache Busting in production we can also add a versioning output to our SBT build process. This will create a file that holds version information and a build number from our Jenkins CI, which we will use to determine the build state and to append to the URL to bust the cache.

To create our version.scala add the following code to your Build.scala file:

lazy val project = Project (
    ...
      // put this in your build.sbt, this will create a Version.scala file that reflects current build state
      sourceGenerators in Compile <+= (sourceManaged in Compile, name, organization, version) map {
        (sourceManaged: File, name: String, vgp: String, buildVersion) =>
          import java.util.Date
          val file = sourceManaged / vgp.replace(".", "/") / "Version.scala"
          val code =
            (
              if (vgp != null && vgp.nonEmpty) "package " + vgp + "n"
              else ""
              ) +
              "object Version {n" +
              "  val namet= "" + name + ""n" +
              "  val versiont= "" + buildVersion + ""n" +
              "  val datetimet= "" + new Date().toString() + ""n" +
              "  val buildNumbert=""+System.getProperty("BUILD_NUMBER", "MANUAL_BUILD")+""n" +
              "}n"
          IO write(file, code)
          Seq(file)
      }
    )
)

We also need to make sure that Scalate will see this class in scope during runtime.

In Build.scala replace:

            Seq.empty,  /* default imports should be added here */

With:

            Seq("import "+Organization+".Version"), /* default imports should be added here */

Now we can update our layout file with a condition that will automatically switch between development and production inclusions of our assets with a Cache Busting scheme.

    #if(com.omnispear.example.assets.Version.buildNumber=="MANUAL_BUILD")
        <!-- Bootstrap core CSS -->
        <link href="/css/bootstrap.min.css" rel="stylesheet" />
        <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
    #else
        <link href="/assets/core.css?v=<%=com.omnispear.example.assets.Version.buildNumber%>" rel="stylesheet" />
        <script src="/assets/core.js?v=<%=com.omnispear.example.assets.Version.buildNumber%>"></script>
    #end

To verify your BUILD_NUMBER handling will work and be passed from Jenkins or your other build system of choice you can run the command example below. Then verify that your assets have switched properly and you are seeing minified and gzipped responses.

./sbt -DBUILD_NUMBER=234 "container:start" "~ ;copy-resources;aux-compile"

An alternative solution would be to use the SBT WRO4J plugin. However, we feel the above method is slightly cleaner and easier to work with for our development process.

The example project for this is available on github. We also would like to thank those whom helped with the initial help with the generation of the Version.scala.