TypeScript icon, indicating that this package has built-in type declarations

    4.0.6 • Public • Published

    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

    Source: http archive

    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)

    The built-in regular expressions for file revving are:


    This will match URLs like the following:


    Test your URLs

    Examples that trigger the hint

    Cache-Control header is not sent:

    HTTP/... 200 OK
    Content-Type: text/javascript; charset=utf-8

    An invalid directive:

    HTTP/... 200 OK
    Cache-Control: invalid directive

    An invalid directive-value pair:

    HTTP/... 200 OK
    Cache-Control: max-age=abc

    Uses a directive that is not recommended:

    HTTP/... 200 OK
    Cache-Control: max-age=3600, must-revalidate

    The combination of directives doesn't make sense:

    HTTP/... 200 OK
    Cache-Control: no-cache, max-age=3600

    The page has a max-age value greater than 3 minutes

    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:

    HTTP/... 200 OK
    Content-Type: text/javascript; charset=utf-8
    Cache-Control: max-age=3600

    A static resource doesn't have the immutable directive:

    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:

    HTTP/... 200 OK
    Content-Type: text/javascript; charset=utf-8
    Cache-Control: max-age=31536000, immutable

    A page with no-cache:

    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.

    Cache-Control header's max-age values can be set using the ExpiresDefault and ExpiresByType directives. Other values such as immutable can be set using the Header 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).
    <IfModule mod_expires.c>
      # 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
            #     `<Location>` directive. The same cannot be done inside
            #     of a `.htaccess` file where only the `<Files>` 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.
            <Files "favicon.ico">
                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
        <IfModule mod_headers.c>
            # 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.
            <FilesMatch "\.(appcache|cur|geojson|ico|json(ld)?|x?html?|topojson|xml)$">
                Header edit Cache-Control immutable ""

    Also note that:

    • The above snippet works with Apache v2.2.0+, but you need to have mod_expires and mod_headers enabled for it to take effect.

    • If you have access to the main Apache configuration file (usually called httpd.conf), you should add the logic in, for example, a <Directory> section in that file. This is usually the recommended way as using .htaccess files slows down 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.

    How to configure IIS

    You can enable the Cache-Control and/or Expire headers on IIS using the <clientCache> element under <staticContent>.

    <clientCache> will set the cache for all the configured static content so you might want to use it in combination with the <location> 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 version="1.0" encoding="utf-8"?>
                <clientCache cacheControlMode="DisableCache" />
        <location path="static">
                    <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="365.00:00:00" cacheControlCustom="immutable" />

    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 <location path="static"> 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.

    Can the hint be configured?

    Yes, you can configure:

    • the max-age values for the page and resources
    • the regular expressions used to know if the file is immutable or not


    By default, the recommended value for the page is Cache-Control: no-cache or a max-age equal or less to 3 minutes. For the resources max-age should be greater or equal to 1 year. You can change this as follows:

    "http-cache": ["error", {
        "maxAgeTarget": 300, // 5 minutes in seconds
        "maxAgeResource": 1576800 // 6 months in seconds

    Custom regular expressions for revving files

    If none of the built-in regular expressions work for your use case, you can provide your own via the revvingPatterns property. This property accepts an Array of escaped RegExp:

    in the .hintrc file:

        "connector": {...},
        "formatters": [...],
        "hints": {
            "http-cache": ["error", {
                "revvingPatterns": ["\\/\\d+\\/\\w+\\.\\w{1,3}"]

    Also pay attention to the escaping. The example above will validate that static resources follow a convention like the following one:


    How to use this hint?

    This package is installed automatically by webhint:

    npm install hint --save-dev

    To use it, activate it via the .hintrc configuration file:

        "connector": {...},
        "formatters": [...],
        "hints": {
            "http-cache": "error",
        "parsers": [...],

    Note: The recommended way of running webhint is as a devDependency of your project.

    Further Reading


    npm i @hint/hint-http-cache



    DownloadsWeekly Downloads






    Unpacked Size

    84.7 kB

    Total Files


    Last publish


    • molant
    • antross
    • johnatms
    • sarvaje