Cache-Control header can cause problems when you change your assets but users are still using their cached versions. Middleman has two approaches to solve this problem for you.
The most effective technique for preventing users from using outdated files is to change the asset's filename every time you change one of your assets. Since that would be a pain to do by hand, Middleman comes with an
:asset_hash extension that does it for you. First, activate the extension in your
Now, refer to your assets as normal, with their original filename. You can use helpers like
However, because this extension works by rewriting your files to reference the renamed assets, it's possible the extension might mess up and miss a reference, or do something you don't want to your code. In that case, you might have to fall back to the older cache buster method.
If you want to exclude any files from being renamed, pass the
:ignore option when activating
:asset_hash, and give it one or more globs, regexes, or procs that identify the files to ignore. Likewise, you can pass an
:exts option to change which file extensions are renamed.
Cache buster in query string
The second approach is to append a value to the end of URLs that reference your assets. For example, instead of referencing
my_image.png you'd reference
my_image.png?1234115152. The extra info at the end of the URL is enough to tell many (but not all) browsers and proxies to cache that file separately from the same file with a different cache buster value. To use this, activate the
:cache_buster extension in your
Note that this approach is more likely to cause your assets to never be cached, this is further explained at "Testing ye olde “querystring cache busting” trick blog post".
Now, to use cache-safe URLs, you must use asset path helpers like
my script.js.erb and call asset helpers via ERb tags to output the right values. If you forget one, your users will still get the file (since the copy on the server just has a normal name) but they might not see changes.
Configuring your server
Configuring your server to use far-future
Cache-Control headers is different depending on which server you use. See Google's page speed docs for links on how to configure your particular server, and run Google Page Speed or YSlow to check that you've configured things correctly.