Auto Updates for Offline First Applications
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

The appCache Nanny

Teaches the applicationCache douchebag some manners!

Build Status Dependency Status devDependency Status

As we all know, the Application Cache is a Douchebag. It's time to teach it some manners – The appCache Nanny for Rescue!

No more manifest attributes on your HTML files. Whether you want to cache your assets offline or not, when to start ... You Are In Control™

Have a glance:

// start to check for updates every 30s

// optionally, pass intervals in ms
appCacheNanny.start({checkInterval: 10000})

// you can also check for updates at any time

// The appCache nanny tells you if there is a new update available

// She tells you about all relevant applicationCache events
appCacheNanny.on('update', handleUpdate)
appCacheNanny.on('error', handleError)
appCacheNanny.on('obsolete', handleObsolete)
appCacheNanny.on('noupdate', handleNoupdate)
appCacheNanny.on('downloading', handleDownloading)
appCacheNanny.on('progress', handleProgress)
appCacheNanny.on('cached', handleCached)
appCacheNanny.on('updateready', handleUpdateready)

// plus some extra ones
appCacheNanny.on('init:downloading', handleInitDownloading)
appCacheNanny.on('init:progress', handleInitProgress)
appCacheNanny.on('init:cached', handleInitCached)
appCacheNanny.on('start', handleStart)
appCacheNanny.on('stop', handleStop)

// options
appCacheNanny.set('loaderPath', '/path/to/my-custom-loader.html')
appCacheNanny.set({ 'loaderPath': '/path/to/my-custom-loader.html' })
appCacheNanny.get() // returns all options


  1. Copy appcache-loader.html into the root directory of your app, so that it's accessible at /appcache-loader.html.
  2. Create the manifest.appcache file and put it in the root directory of your app, next to /appcache-loader.html. If you use a different name, make sure to set it accordingly in appcache-loader.html.

Then load the appcache-nanny.js on your HTML pages.

<script src="appcache-nanny.js" async></script>

If you use bower, you can install it using:

bower install --save appcache-nanny

Or install via npm

npm install --save appcache-nanny


I extracted appcache-nanny.js from, which is an Offline First web application, anno 2011. It's battle tested by a ton of users, devices, internet environments. checks every 30 seconds if an update is available. And whenever the user navigates from one view to another, it reloads the page in case there is. As the assets are all cached, the user cannot tell that their page got just reloaded. It's silent, without any notification, or a prompt asking the user to reload the page. And it works very well so far.


appCacheNanny demo screencast

The appCache Nanny comes with a simple server for testing. Start it using Node:

npm start

It will start a local server at http://localhost:8888.

This is a static server with a few hidden features:

  • GET /bump-version increases the app version, so an update gets triggered on next check
  • GET /remove-manifest makes GET /manifest.appcache return 404, so it becomes obsolete on next check
  • GET /recreate-manifest undoes the previous step.


Unlisted paths get loaded from the server, not from cache (via FALLBACK)

Thanks to the iframe hack, your HTML pages do not get added to the list of cached assets locally, and won't get checked for updates each time. Which is great especially for a Single Page Application with pushState enabled. But if your app has paths like /welcome, /Dashboard, Meeting/123 and your manifest.appcache looks something like



/ /

Beware that opening will always show the currently cached version, as it is explicetly listed, while and other paths will load the page from the server, unless the user is offline.

You might have learned that assets that are not listed in the cache manifest cannot be loaded at all, even when online. But that's not the case if the loaded HTML page does not have the manifest property on the html tag.


The appCache Nanny is based on tremendeous amount of research others have done on applicationCache. I'd like to highlight


  • on obsolete, remove the iframe, load it again to check if a new *.appcache path has been set. If yes, update and trigger updateready event, otherwise trigger obsolete event

Fine Print

The appCache Nanny has been authored by Gregor Martynus, proud member of the Hoodie Community.

License: MIT