# HTTP cache (`http-cache`)
`http-cache` verifies that the page and all its resources follow a
good, sustainable caching strategy.
## Why is this important?
The right caching strategy can help improve site performance through:
* Shorter load times
* Reduced bandwidth
* Reduced server costs
* Having predictable behavior across browsers
Currently about ~50% of resources on the web can't be cached due to
their configuration:
![Cacheable Resources][maxage0 image]
[Source: http archive][maxage0]
## What does the hint check?
This hint checks the configuration of the `cache-control` header to
validate that the page and resources have a good caching strategy:
* all requests have a `Cache-Control` header, otherwise the behavior
can change from browser to browser
* main page should have a short cache (<= 3 minutes) or not cache at all
* static resources such as JavaScript, CSS, images, etc.:
* have a long expiry value (>= 1 year)
* use the `immutable` directive
* follow filename/path-based revving, and not
one based on query string parameters (see: [problems with
proxies][revving files])
The built-in regular expressions for file revving are:
```regexp
/\/[^/]+[._-]v?\d+(\.\d+(\.\d+)?)?[^/]*\.\w+$/i
/\/v?\d+\.\d+\.\d+.*?\//i
/\/v\d.*?\//i
/\/([^/]+[._-])?([0-9a-f]{5,})([._-].*?)?\.\w+$/i
```
This will match URLs like the following:
```text
https://example.com/assets/jquery-2.1.1.js
https://example.com/assets/jquery-2.1.1.min.js
https://example.com/assets/jquery-3.0.0-beta.js
https://example.com/assets/favicon.123.ico
https://example.com/wp-content/uploads/fvm/out/header-cb050ccd-1524626949.min.js
https://example.com/jquery.lazy/1.6.5/jquery.lazy.min.js
https://example.com/site/javascript/v5/jquery.cookie.js
https://example.com/rsrc.php/v3iJhv4/yG/l/en_US/sqNNamBywvN.js
https://example.com/assets/unicorn-d41d8cd98f.css
https://example.com/assets/app.e1c7a.bundle.js
https://example.com/assets/9f61f58dd1cc3bb82182.bundle.js
https://example.com/assets/9f61f.js
https://example.com/assets/9f61f.min.js
```
[Test your URLs](https://regex101.com/r/KDPUtH/)
### Examples that **trigger** the hint
`Cache-Control` header is not sent:
```text
HTTP/... 200 OK
Content-Type: text/javascript; charset=utf-8
...
```
An invalid directive:
```text
HTTP/... 200 OK
Cache-Control: invalid directive
...
```
An invalid directive-value pair:
```text
HTTP/... 200 OK
Cache-Control: max-age=abc
...
```
Uses a directive that is not recommended:
```text
HTTP/... 200 OK
Cache-Control: max-age=3600, must-revalidate
...
```
The combination of directives doesn't make sense:
```text
HTTP/... 200 OK
Cache-Control: no-cache, max-age=3600
...
```
The page has a `max-age` value greater than 3 minutes
```text
HTTP/... 200 OK
Content-Type: text/html; charset=utf-8
Cache-Control: max-age=300
...
```
A static resource has a `max-age` value less than 1 year:
```text
HTTP/... 200 OK
Content-Type: text/javascript; charset=utf-8
Cache-Control: max-age=3600
...
```
A static resource doesn't have the `immutable` directive:
```text
HTTP/... 200 OK
Content-Type: text/javascript; charset=utf-8
Cache-Control: max-age=31536000
...
```
### Examples that **pass** the hint
A static resource with `max-age` greater than 1 year and the `immutable`
directive:
```text
HTTP/... 200 OK
Content-Type: text/javascript; charset=utf-8
Cache-Control: max-age=31536000, immutable
...
```
A page with `no-cache`:
```text
HTTP/... 200 OK
Content-Type: text/html; charset=utf-8
Cache-Control: no-cache
...
```
## How to configure the server to pass this hint
How to configure Apache
Enabling Apache to automatically add the `Cache-Control` header
(as well as the equivalent `Expires` header) can be done using the
[`ExpiresActive` directive][expiresactive].
`Cache-Control` header's `max-age` values can be set using the
[`ExpiresDefault`][expiresdefault] and [`ExpiresByType`][expiresbytype]
directives. Other values such as `immutable` can be set using the
[`Header`][header directive] directive.
If you don't want to start from scratch, below is a generic starter
snippet that contains the necessary configurations to ensure that
commonly used file types are served with the appropriate `Cache-Control`
header, and thus, make your web site/app pass this hint.
Important notes:
* Do not use the following snippet if you are not doing filename revving.
* The following relies on Apache being configured to have the correct
filename extensions to media types mappings (see Apache section from
[`content-type` hint](content-type.md#how-to-configure-the-server-to-pass-this-hint)).
```apache
# Automatically add the `Cache-Control` header (as well as the
# equivalent `Expires` header).
ExpiresActive on
# By default, inform user agents to cache all resources for 1 year.
ExpiresDefault "access plus 1 year"
# Overwrite the previous for file types whose content usually changes
# very often, and thus, should not be cached for such a long period,
# or at all.
# AppCache manifest files
ExpiresByType text/cache-manifest "access plus 0 seconds"
# /favicon.ico (cannot be renamed!)
# [!] If you have access to the main Apache configuration
# file, you can match the root favicon exactly using the
# `` directive. The same cannot be done inside
# of a `.htaccess` file where only the `` directive
# can be used, reason why the best that can be done is match
# all files named `favicon.ico` (but that should work fine
# if filename/path-based revving is used)
#
# See also: https://httpd.apache.org/docs/current/sections.html#file-and-web.
ExpiresByType image/x-icon "access plus 1 hour"
# Data interchange
ExpiresByType application/atom+xml "access plus 1 hour"
ExpiresByType application/rdf+xml "access plus 1 hour"
ExpiresByType application/rss+xml "access plus 1 hour"
ExpiresByType application/json "access plus 0 seconds"
ExpiresByType application/ld+json "access plus 0 seconds"
ExpiresByType application/schema+json "access plus 0 seconds"
ExpiresByType application/vnd.geo+json "access plus 0 seconds"
ExpiresByType text/xml "access plus 0 seconds"
# HTML
ExpiresByType text/html "access plus 0 seconds"
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Where needed add `immutable` value to the `Cache-Control` header
# Because `mod_headers` cannot match based on the content-type,
# the following workaround needs to be done.
# 1) Add the `immutable` value to the `Cache-Control` header
# to all resources.
Header merge Cache-Control immutable
# 2) Remove the value for all resources that shouldn't be have it.
Header edit Cache-Control immutable ""
```
Also note that:
* The above snippet works with Apache `v2.2.0+`, but you need to
have [`mod_expires`][mod_expires] and [`mod_headers`][mod_headers]
[enabled][how to enable apache modules]
for it to take effect.
* If you have access to the [main Apache configuration file][main
apache conf file] (usually called `httpd.conf`), you should add
the logic in, for example, a [``][apache directory]
section in that file. This is usually the recommended way as
[using `.htaccess` files slows down][htaccess is slow] Apache!
If you don't have access to the main configuration file (quite
common with hosting services), add the snippets in a `.htaccess`
file in the root of the web site/app.
For the complete set of configurations, not just for this rule, see
the [Apache server configuration related documentation][apache config].
How to configure IIS
You can enable the `Cache-Control` and/or `Expire` headers on IIS
using the [` element under `][clientcache
iis].
`` will set the cache for all the configured static
content so you might want to use it in combination with the
`` element and set different values depending on where
the resources are in the file system.
The following is an example that sets `cache-control: no-cache`
for all static resources and then overrides it for the files under
the `static` folder with `cache-control: max-age=31536000, immutable`:
```xml
```
In the example above, you want to have your JavaScript, CSS, images,
etc. under the `static` folder, and your HTML elsewhere. If your static
content is in another folder change the path of ``
to the right one.
Important notes:
* Do not use the above snippet if you are not doing filename revving.
* The above snippet works with IIS 7+.
* You should use the above snippet in the `web.config` of your
application.
For the complete set of configurations, not just for this rule,
see the [IIS server configuration related documentation][iis config].