News & Announcements
Netlify Cache Key Variations
Following the launch of Cache-Tags and Purge API, today we’re happy to announce yet another feature in the series of caching improvements that aim to give Netlify users more control over their cached content.
Netlify now supports a custom
Netlify-Vary header, which instructs Netlify’s edge on how to better cache and serve dynamic assets using Netlify’s CDN with Netlify Functions, Netlify Edge Functions or external services proxied to using redirect rules.
Why is it important?
Netlify allows developers to choose which static response to be served and cached for a given request based on rules like authentication, country or locale based conditions, or even query parameters. This works great when serving static assets, but over the last couple of years the web ecosystem has evolved and now there’s a big trend of building dynamic applications running in serverless functions or edge functions within our system.
Different types of dynamic resources may need to respect different parts of the incoming request when deciding whether to serve a cached response or not:
- Some resources don’t look at query parameters and will get a much higher cache hit rate by not taking these into account, while others use specific query parameters and need the cache to take those into account.
- Some resources might be cacheable depending on a cookie value (ie. no
is_logged_incookie might mean, “show a login page,” and
is_logged_in=1cookie might mean, “show a logged in member page”).
- Some frameworks, like Next.js, depend on varying cached responses based on the value of specific headers like
Vary header is very restrictive and generally meant for use cases like content negotiation, so Netlify offers a more flexible
Netlify-Vary header, that gives fine grained control over which parts of a request need to match the cached object.
How do cache key variations work?
Netlify now supports a custom
Netlify-Vary header, which takes a set of comma delimited instructions for what parts of the request to vary on:
queryvary by request URL query parameters
headervary by the value of a request header
languagevary by the languages from the
countryvary by the country inferred from doing the GeoIP lookup on the request IP address
cookievary by a value of a request cookie
These instructions, together with the request URL, will define the cache key which Netlify uses to uniquely identify a cached object in our CDN.
By default Netlify doesn’t take query parameters into account to construct the cache key, since things like
_utm parameters or session IDs for analytics, social links, etc, can drastically reduce cache hit rates.
However, if you know that the responses from a resource will only depend on specific query parameters, like a
per_page parameter, you can change this behavior for a resource by adding
Netlify-Vary to your dynamic content responses:
Netlify-Vary will tell Netlify to take just those 3 query parameters into account when deciding whether to serve a cached response, so other query parameters like
_utm will not affect your cache hit rate.
If you'd like to include all query parameters when creating the cache key, you can achieve this by adding the following
You can now instruct Netlify Edge to vary content on specific headers, so your business logic can be transported as a header and still influence the cache. To control which headers go into the cache key, you can use the
header instruction like this:
This will make the cache take a custom
Device-Type header into account for the cache key and distinguish between objects with different
Device-Type header values, so for example different users trying to access your platform from different device types (e.g.
web, etc.) will see different custom content for each type of device.
Similarly to query parameter variations, you can also provide a list of headers:
Cookies serve a variety of purposes, but one of their common use cases is A/B testing. However, cookies often contain additional information, such as authentication details or analytics data. In such scenarios, you don’t want to vary the cached content on the entirety of the cookie value, but just on a couple of key-value pairs.
Similarly to query variations, you can target a subset of cookie key-value parameters to be considered on the cache key:
This will tell Netlify to vary cached content based off the values for both
ab_test_bucket set on the request’s
Language & Country
One of the most common use cases for cached content variations is varying the content depending on user features such as language and geolocation.
To vary on the user’s language, you can specify groups of languages to take into account for your cache key. These are based on the
Accept-Language header from the request. For example, the following instruction will keep different cache objects for users with English as an accepted language, users with German as an accepted language, and all other users.
To group more languages together, use
This will vary the cached content for clients accepting English, clients accepting Spanish or Portuguese and clients accepting Danish, Dutch or German as well as the unlisted group of all other clients.
Similarly, to vary cached content based on the geographical origin of the request, you can specify groups of countries to take into account for your cache key. The following instruction will keep different cache objects for users located in England, users in Spain or Portugal and users in Denmark, The Netherlands or Germany, as well as the unlisted group of all other users.
You can use any combination of the above variation instructions to vary your cached content on:
This will tell Netlify to take both the entire query into account for cached objects, as well as the request’s country of origin.
Try it out today
Visit our documentation for more information on how to get started.
What’s next for edge caching on Netlify?
We’re thrilled to have brought you all these new caching features, unlocking more complex use cases and potentially making your current caching logic for dynamic assets much simpler and intuitive.
Our team is committed to making Netlify the world’s most advanced global caching infrastructure, and we’re looking forward to further evolve our platform to continue to serve your needs by building everything from simple web pages to a full-fledged web platform.