immutable
The `immutable` directive sets caching behavior for static assets, enabling the use of the `immutable` cache control attribute for improved performance.
Description
The immutable directive in NGINX is utilized to enhance caching strategies for static assets, particularly in web frameworks that implement a cache-busting approach using versioned URLs. When this directive is enabled, the server responds to requests for static resources with HTTP headers that include the Cache-Control directive set to immutable, as well as a far-future Expires header. This tells the browser and intermediate caches that the asset will not change and can thus be cached effectively without needing to revalidate the resource each time it is requested.
The immutable directive is applicable in multiple contexts, including http, server, and location, and it accepts a single argument flag which can enable or disable the directive. By setting immutable on;, NGINX will configure responses to include both the max-age directive (set to 1 year) and the immutable attribute, allowing enhanced utilization of cached content. The directive also ensures that the Expires header is transmitted only for HTTP/1.0 requests since newer versions of HTTP handle caching more efficiently through the use of Cache-Control.
By marking resources as immutable, NGINX allows browsers to cache them indefinitely, which optimizes performance for static content delivery. This is especially useful for applications like single-page apps and frameworks that frequently update their assets without altering their URLs. Additionally, the stale-while-revalidate and stale-if-error values can be appended to the Cache-Control header to mitigate cache misses in specific browser conditions, making the caching mechanics even more robust.
Config Example
http {
server {
location /static/ {
immutable on;
}
}
}Ensure that the underlying static assets truly do not change, as marking them as immutable can lead to stale content being served if they are updated without changing the URL. Also, browser support for the immutable directive should be verified as behavior may vary across browsers. Note that older browsers may not understand the immutable directive, resulting in fallback behaviors.
If using in combination with other caching directives, ensure they do not conflict with immutable to avoid unexpected caching issues.