mod_expires and Cache Killers

Rule 3 of Steve Souders’ YSlow suggests that websites should Add a far future Expires header to the components. Components with a cache header could be static files such as those with extensions .css, .js, .jpg, .png, .gif etc. This gives a huge boost in client side performance of users with a primed cache. In apache this is done via mod_expires and an example configuration would be:

ExpiresActive On
ExpiresByType image/x-icon "access plus 1 month"
ExpiresByType text/css "access plus 1 month"
ExpiresByType application/javascript "access plus 1 month"
ExpiresByType image/gif "access plus 1 month"
ExpiresByType image/jpeg "access plus 1 month"
ExpiresByType image/png "access plus 1 month"

All this works well until you need to update a cached static file. The users with the primed cache will either have to wait 1 month to get the new file, or explicitly invalidate their cache. Some people will even ask their users to do a hard refresh but this obviously does not scale and it’s not very robust.

Since you cannot send an automatic signal to the browsers to reload those files all you can do is change the URL of those files (explicit invalidation). You could simply rename all those files, but an easier way to achieve the same effect is by adding a fake (unused – dummy) parameter at the end of the resource URL:

<img src="logo.jpg?2" />

The next logical step would be to automate this into the build system and have every production release feature new cache killer tokens. It seems that many well known sites do that already:



@import "/css/189/global.css";

@import '';


What happens with images referenced from within css files? You could rewrite the css files automatically as part of your production build process with Ant.

    <format property="cacheKill" pattern="yyyyMMddhhmm" locale="en,UK"/>

<target name="rewrite-css">
    <replace dir="${build.web.dir}" value="css?${cacheKill}&quot;)"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>css&quot;)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="png?${cacheKill}&quot;)"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>png&quot;)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="gif?${cacheKill}&quot;)"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>gif&quot;)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="jpg?${cacheKill}&quot;)"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>jpg&quot;)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="css?${cacheKill}')"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>css')</replacetoken></replace>
    <replace dir="${build.web.dir}" value="png?${cacheKill}')"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>png')</replacetoken></replace>
    <replace dir="${build.web.dir}" value="gif?${cacheKill}')"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>gif')</replacetoken></replace>
    <replace dir="${build.web.dir}" value="jpg?${cacheKill}')"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>jpg')</replacetoken></replace>
    <replace dir="${build.web.dir}" value="css?${cacheKill})"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>css)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="png?${cacheKill})"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>png)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="gif?${cacheKill})"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>gif)</replacetoken></replace>
    <replace dir="${build.web.dir}" value="jpg?${cacheKill})"><include name="css/**/*.css"/><include name="scripts/**/*.css"/><replacetoken>jpg)</replacetoken></replace>

This will take care of the following background image reference styles for css, png, gif and jpg files:

... background-image: url("images/ed-bg.gif");
... background-image: url('images/ed-bg.gif');
... background-image: url(images/ed-bg.gif);

and convert them to:

... background-image: url("images/ed-bg.gif?200905031126");
... background-image: url('images/ed-bg.gif?200905031126');
... background-image: url(images/ed-bg.gif?200905031126);

Good luck!

7 Responses to “mod_expires and Cache Killers”

  1. Simon Willison Says:

    I believe using a version number in a query string can cause some browsers and/or proxies to avoid caching an asset at all – it’s safer to bake the version number in to the filename or directory path in some way.

  2. cherouvim Says:

    Thanks for your input Simon, I’ll have to do some more research. On the other hand it’s a bit hard to think that slashdot would have gotten that wrong.

  3. Jordi Hernandez Says:

    I think the request string issue mentioned by Simon happened in older browsers indeed, but nowadays it is more or less safe to use this technique. The HTTP spec does indeed mandate browsers to use cache for such requests.
    And now the plug: java web apps can benefit from this technique and many others to accomplish nearly all of the YUI blog recommendations by using Jawr ( Images are still not supported but javascript and CSS are indeed combined,minified, gzipped and assigned a version-dependant URL (actually without request params). Jawr also has a debug mode in which files are served uncompressed and with a per-request changing param which forces the browser to reload and helps code-deply-test cycles.

  4. Yann C├ębron Says:

    JEE solution – works very well for me (unfortunately it does not support rewriting URLs for anything else than CSS/JS – yet)

  5. Ochoto Says:

    Squid’s default configuration is not to cache urls with a query string.

  6. javier Says:

    The solution is not complete. In one of our J2EE products we are using the tuckey url rewriter to rewrite urls with the following:


    the rule we use is the following.

    ^([^ ]+)-([0-9]+)\.([a-z]+)$

    The filter only applies to paths under /resources/ so only applies to css, js, etc

    This is not enough because inside the css files you point to images as well. The same problem could happen in the js files.

    In order to sort these issue out we use a filter that modifies these kind of resources on the flight and caches them.

    Our system finally publishes a jmx bean that allows us to change the version. By default the version is system.currentTimeMillis() that changes everytime we restart the server.

  7. High Performance Web Sites :: Even Faster Web Sites in Skiathos Says:

    [...] Ioannis Cherouvim, a software engineer from Greece, sent me this photo: [...]