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:

# 23-01-2015 v0.1


/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:

# 23-01-2015 v0.1


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.



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:

# 23-01-2015 v0.1

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.

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:

# 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.

# 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:

# 23-01-2015 v0.2

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:


Then your manifest file should look like:

# 23-01-2015 v0.2


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) {

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:



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:




0 条评论
登录 后参与评论



Build Android Packages From Command Line

A few months ago,I dealed with a task:To build a large amount of apk files. The...


docs and demos of Watson services

Services 1)Language 1.1) AlchemyLanguage :Demo Document AlchemyLanguage is a c...


Async方法死锁的问题 Don't Block on Async Code(转)



Clang - Use Xcode to make first Clang plugin


Caused by: android.os.NetworkOnMainThreadException

Caused by: android.os.NetworkOnMainThreadException at android.os.StrictMode$And...



全部参数一览 //Path to a program. ANT_EXECUTABLE:FILEPATH=D:/apache-ant-1.10.1/bin/ant...


POJ-1644 To Bet or Not To Bet(概率DP)

To Bet or Not To Bet Time Limit: 1000MS Memory Limit: 10000K Total Subm...


Spring Boot 与 Kotlin 上传文件

如果我们做一个小型的web站,而且刚好选择的kotlin 和Spring Boot技术栈,那么上传文件的必不可少了,当然,如果你做一个中大型的web站,那建议你...


Common Pitfalls to Avoid when using HTML5 Application Cache

本文作者:IMWeb 黎腾 原文出处:IMWeb社区 未经同意,禁止转载 Application Cache, also known as AppCa...


Note_Motivation & Gamification