Common Pitfalls to Avoid when using HTML5 Application Cache

Application Cache, also known as AppCache, has been a pretty hot topic with web developers these days. AppCache enables you to allow your website visitors to browse your website when they are offline. You can even store parts of your website, such as images, stylesheets, or web-fonts in the cache on a user’s computer. This can help your website load faster and hence reduces load on your server.

To use AppCache, you make a manifest file with a file extension of “appcache”, for example: manifest.appcache. In this file you can list all the files you want to be cached. To enable it on your site, you have to include the reference to this manifest file on your webpage on the html element, like this:

<html lang="en" manifest="manifest.appcache">

Here’s a sample manifest file:

CACHE MANIFEST
# 23-01-2015 v0.1
/style.css
/logo.gif
/script.js

NETWORK:
*

FALLBACK:
/server/ /fallback.html

Along with the benefits of AppCache, there are some common pitfalls that you should avoid in order to prevent ruining the user experience and breaking your application.

Never list the Manifest File in the Manifest File

If you include the manifest file itself in the application cache manifest, it gets in a kind of loop, making it nearly impossible to inform your website that a new cache file is available and it should download and use the new manifest file instead of the old one. Therefore, always be careful not to make the following mistake:

CACHE MANIFEST
# 23-01-2015 v0.1

manifest.appcache
page2.css

Non-Cached Resources Do Not Load On a Cached Page

This is a very common mistake when working with AppCache for the first time. This is where the NETWORK flag in the manifest file comes to the rescue. The NETWORK section of a manifest file specifies resources for which a web app requires online access.

URLs specified under the NETWORK flag are basically “whitelisted”, that is the files specified under this flag are always loaded from the server when an internet connection is available. For example, the following snippet of code makes sure that requests to load resources contained in the /api/ subtree always load from the network and not the cache.

NETWORK:

/api

Always Set Application Type Manifest in .htaccess of Your Server

A manifest file should always be served under the correct media type of text/cache-manifest. If the media type is not set, then AppCache will not work.

It should always be configured in the .htaccessof your production server. This point is mentioned in most tutorials teaching AppCache but is overlooked by many developers when they are transitioning their web application from a development to a production server.

Enter the following in your .htaccess file in Apache:

AddType text/cache-manifest .manifest

If you are uploading your application to Google App Engine, you can accomplish the same task by adding the following piece of code to your app.yaml file:

- url: /public_html/(.*\.appcache)
  static_files: public_html/\1
  mime_type: text/cache-manifest
  upload: public_html/(.*\.appcache)

Avoid Dropping the Whole Manifest Due to File Not Found

If even a single file specified in the manifest file is not found or is not able to be downloaded, then the whole manifest file is dropped. This is a strange behavior of AppCache and should be kept in mind while designing a web application making use of AppCache.

For example:

CACHE MANIFEST
# 23-01-2015 v0.1
/style.css
/logo.gif
/script.js

If logo.gif was deleted, the AppCache will not be able to find the deleted image file and hence nothing in the manifest file will be executed.

Data is Loaded from AppCache Even When Online

Once the cache manifest file has been saved by your web browser, the files are loaded from the cache manifest itself, even if the user is connected to the internet. This feature helps in improving the loading speed of your website and helps in reducing server loads.

Changes on the Server Do Not Take Place Until the Manifest File’s Updated

Since you know from the previous point that data is loaded from AppCache even if the user are online, changes that you have made to the files in your website or server do not take place until the manifest file is updated.

You always have to update the manifest file after updating the website or your user will never be able to see the changes, but they will only see the previously cached data. You can update the version number or date in a comment in your manifest file to force the user’s web browser to download the new version of the manifest file. For instance, if the following used to be your manifest file before making the changes to your website:

CACHE MANIFEST
# 23-01-2015 v0.1

It could be changed to something like the below block of code, so that the user’s browser could download a new copy of the manifest file.

CACHE MANIFEST
# 23-01-2015 v0.2

Please note that line preceded by # is a comment line that isn’t executed.

The Manifest File Must be Served from Same Origin as Host

Although manifest files can hold reference to resources to be cached from other domains, it should be served to the web browser from the same origin as the host page. If this is not the case, then the manifest file will fail to load. For example the following manifest file is correct:

CACHE MANIFEST
# 23-01-2015 v0.2

https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.js

Here we have specified the content to be stored in the user’s browser cache which is referenced from another domain, which is perfectly fine.

Relative URLs Are Relative to the Manifest’s URL

One important thing to take note of is that the relative URLs that you mention in the manifest are relative to the manifest file and not to the document where you reference the manifest file. If you make this error when the manifest and the reference are not in the same path, the resources will fail to load and in turn the manifest file will not be loaded.

If your application structure looks like the following:

css/style.css
js/main.js
img.jpg
index.html
manifest.appcache

Then your manifest file should look like:

CACHE MANIFEST
# 23-01-2015 v0.2

css/style.css
js/main.js
img.jpg

Programmatically Checking the Status of Your Manifest

You can programmatically check if your application is using an updated version of the cache manifest by testing window.applicationCache.status. Here’s some example code:

function onUpdateReady() {
  alert('found new version!');
}

window.applicationCache.addEventListener('updateready', onUpdateReady);

if (window.applicationCache.status === window.applicationCache.UPDATEREADY) {
  onUpdateReady();
}

Running the above code on a website lets you know when a new update for the AppCache manifest is available. Please note that UPDATEREADY is a defined state. You can even use the swapCache() method in the onUpdateReady() function to swap the older manifest file with the newer one:

window.applicationCache.swapCache();

Conclusion

AppCache is a useful technology, but as we’ve seen, you should be careful when implementing it in your projects. Developers should be selective in selecting what we should include in our manifest file. Ideally, the manifest file should include static content such as stylesheets, scripts, web-fonts and images. However, you are always the best judge of what to include in your manifest file. Appcache is a double edged sword, so be careful while using it!

Much of what’s discussed above has been covered elsewhere, along with some additional points. You can check out the following resources for more:

Application Cache Gothas on MDN
Application Cache is a Douchebag by Jake Archibald
Offline Cookbook by Jake Archibald

Frequently Asked Questions (FAQs) about HTML5 Application Cache

What is the HTML5 Application Cache and why is it important?

The HTML5 Application Cache (AppCache) is a feature that allows developers to specify which files the browser should cache and make available to users offline. It’s important because it can improve the performance of web applications by reducing server load and saving bandwidth. It also allows applications to run even when the user is offline, providing a better user experience.

How does the HTML5 Application Cache work?

The HTML5 Application Cache works by using a manifest file. This file lists the resources the browser should cache for offline use. When a user visits a webpage, the browser checks if a manifest file is associated with it. If it is, the browser downloads and stores the listed resources. The next time the user visits the webpage, the browser loads the cached resources instead of downloading them from the server.

What are the common pitfalls when using the HTML5 Application Cache?

Some common pitfalls when using the HTML5 Application Cache include not updating the manifest file correctly, leading to old resources being served; not handling the cache manifest fallback section properly, resulting in errors; and not considering the impact of caching on the user’s device storage.

How can I avoid these pitfalls?

To avoid these pitfalls, always update the manifest file correctly when resources change. Use the NETWORK section of the manifest file to specify resources that should never be cached. Also, consider the user’s device storage and only cache necessary resources.

What is the future of the HTML5 Application Cache?

The HTML5 Application Cache is being deprecated in favor of Service Workers. Service Workers provide more control over caching and can handle more complex scenarios. However, as of now, not all browsers support Service Workers, so it’s still important to understand and use the HTML5 Application Cache.

How do I create a manifest file?

A manifest file is a simple text file that lists the resources to be cached. It should be served with the MIME type ‘text/cache-manifest’. The first line of the file should be ‘CACHE MANIFEST’, followed by the resources to be cached.

How do I associate a webpage with a manifest file?

To associate a webpage with a manifest file, add the ‘manifest’ attribute to the ‘html’ tag of the webpage. The value of the ‘manifest’ attribute should be the URL of the manifest file.

How do I update the cache?

To update the cache, make a change to the manifest file. The browser checks for updates to the manifest file every time the user visits the webpage. If the manifest file has changed, the browser downloads and caches the new resources.

What happens if a resource listed in the manifest file cannot be downloaded?

If a resource listed in the manifest file cannot be downloaded, the entire cache update process fails. The browser will continue to use the old cache.

Can I use the HTML5 Application Cache for all resources?

While you can technically use the HTML5 Application Cache for all resources, it’s not recommended. Caching too many resources can fill up the user’s device storage and negatively impact performance. It’s best to only cache necessary resources.