immutable: NGINX module for setting immutable caching on static assets

Installation

CentOS/RHEL 6, 7, 8 or Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install nginx-module-immutable

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_immutable_module.so;

This document describes nginx-module-immutable v0.0.1 released on Feb 24 2020.

---

This tiny NGINX module can help improve caching of your public static assets, by setting far future expiration with immutable attribute.

Synopsis

http {
    server {
        location /static/ {
            immutable on;
        }
    }
}

will yield the following HTTP headers:

...
Cache-Control: public,max-age=31536000,immutable
Expires: Thu, 31 Dec 2037 23:55:55 GMT 
...

How it's different to expires max;:

• Sets immutable attribute, e.g. Cache-Control: public,max-age=31536000,immutable for improved caching
• Sends Expires only when it's really necessary, e.g. when a client is requesting resources over HTTP/1.0
• Sets public attribute to ensure the assets can be cached by public caches, which is typically a desired thing.

Thus in most cases, immutable on; can be used as as a better alternative to expires max;.

Example: Magento 2 production configuration

Provided that your store runs in production mode, you have already compiled all the assets. This sample config can be optimized to:

location /static/ {
    immutable on;

    # Remove signature of the static files that is used to overcome the browser cache
    location ~ ^/static/version {
        rewrite ^/static/(version\d*/)?(.*)$ /static/$2 last;
    }

    location ~* \.(ico|jpg|jpeg|png|gif|svg|js|css|swf|eot|ttf|otf|woff|woff2|json)$ {
        add_header X-Frame-Options "SAMEORIGIN";
    }
    location ~* \.(zip|gz|gzip|bz2|csv|xml)$ {
        add_header Cache-Control "no-store";
        add_header X-Frame-Options "SAMEORIGIN";
        immutable off;
    }
    add_header X-Frame-Options "SAMEORIGIN";
}

When used together with ngx_security_headers, it can be simplified further:

security_headers on;

location /static/ {
    immutable on;


    location ~ ^/static/version {
        rewrite ^/static/(version\d*/)?(.*)$ /static/$2 last;
    }

    location ~* \.(zip|gz|gzip|bz2|csv|xml)$ {
        add_header Cache-Control "no-store";
        immutable off;
    }
}

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-immutable.