Version my app

This tutorial explains what we mean by "Versioning an App", shows you how to do it in BladeRunner, and explains the benefits of doing so.

What do you mean by "Versioning an App"?

Versioning your app allows it to be cached more effectively by a browser. It makes sure that the browser does not have to keep requesting and reloading resources it’s already got, but also ensures that if the app changes in some way, those changes are loaded into the browser as soon as possible.

Although a number of caching strategies exist, only Versioning and HTML5 App-Cache allow the entire application to be fully cached by the browser. Since App-Cache isn’t yet supported in all browsers, BladeRunner relies instead on versioning.

These are all common caching strategies for web apps:

  • No Caching Headers: the browser re-requests every resource, every time it loads the app.

  • Last-Modified and/or ETag Headers: the browser sends a conditional request for each resource, to re-send it only if it’s changed since the last time the app was used. Even when there is nothing to load however, the overhead for this can still be as much as 50ms per resource, depending on your connection speed.

  • Expires and/or Cache-Control Headers: the browser loads nothing provided the expiry time is still in the future. Without a versioning mechanism however, users will not receive updated versions of the app until that time. If a short expiry time is set, the whole app is frequently downloaded.

  • HTML5 App-Cache: the browser works completely off-line, unless a new version of the app is available, in which case it will be loaded in the background, ready for use the next time the user loads the app.

How Versioning Works in BladeRunner

If the cache headers for the resource URLs used by your app never expire, then you will never be able to ensure that users receive updates. By including a version number within the app URL, new versions can be pushed to users by redirecting them to a new URL, each time the app changes. Which is great… but changing the URL each time you update your app breaks users' bookmarks.

What we do in BladeRunner is to use the <base /> HTML tag, to make the browser request all the resources within a page using a versioned URL, leaving the main page URL permanently unchanged. That way, bookmarking still works, and each time the app is used, only index.html is reloaded by the browser.

So How Do I Use Versioning in My App?

It’s easy. You just need to add the following code to the index.html page (or pages, if you are using more than one aspect):

<base href="@APP.VERSION@"/>

Within the development environment, versioning is still enabled so that your app behaves in the same way as it will in production, but a unique APP.VERSION is sent each time the page is requested, preventing any of the previously cached content from ever being reused during development.

When you use the bladerunner war command, to build a WAR file for deployment to the production environment, then a unique APP.VERSION is automatically assigned to the WAR. In production therefore, users will run the app from their browser cache until such a time as you deploy a new WAR, with a new APP.VERSION.