[Support Guide] How does Netlify’s CDN handle caching files?

Support Support Guides
,
1

Last reviewed by Netlify Support in December 2024

While the topic of caching effectively is complex, Netlify’s solution is designed to be automatic and worry-free. It shouldn’t require any special configuration or build tools like cache-busting or service workers to deliver an optimal experience.

What can go wrong?

Some cache-busting techniques can make your site build and load more slowly. Scarier still, modifying Netlify’s default caching settings can break atomic rollbacks and deploys, which are some of the coolest things about Netlify’s CDN! You’ll want to check any custom configuration to override the defaults with some experts here in the Forums, lest your next visitor accidentally get stuck with an out of date index.html cached in their browser for a year :scream:

Claiming that cache-busting would make your site SLOWER on Netlify’s CDN is pretty bold; it might seem counterintuitive, but it’s true! Here are two ways that happens:

  1. When you change a filename with every build on Netlify, that means the browser can never reuse its cache for the old filename. The browser isn’t smart enough to know this other filename’s cache should be checked!
  2. If the file with the always-different filename is a JavaScript or CSS file that is included in every HTML file, ALL of those files just changed and all need to be re-downloaded by the browser – even though they are essentially the same files, and are identical in both content and function.

Note that this other article explains that situation in more detail.

There are smarter cache-busting techniques that might not slow things down, but the two examples above are pretty common pitfalls.

In September 2023, we changed our CDN’s handling of cached files so that you cannot get things “stuck” in our cache beyond the lifespan of a deploy, so this advice also applies to resources which Netlify proxies to - which includes both “assets on your remote server” as well as “everything run in a lambda function” - cache busting is not needed, but you also don’t need to worry about accidentally-too-long cache-control settings. You can find detailed information about how to control caching here.

However, in the case of lambda functions, you should consider using On-Demand Builder Functions to control content that you wish to be cached after runtime for future visitors as that functionality is designed to support our atomic rollbacks and deploys and works well for this use case.

Finally, we also have an article about how Netlify caches for those who are interested in more in-depth details; feel free to ask questions about it in this thread. We want this guide to remain as useful as possible, so please let us know if you have feedback!

5 Likes
19

Hi fool,

I am using a bundler that automatically appends a content hash as a suffix to all my JS and CSS files. This means that:

  1. The file name changes if the file content changes
  2. The file name DOESN’T change if the file content remains the same.

Now, from what I understand the default Netlify behavior is:

  1. Client checks with Netlify for each file if content changed (done via etag and optimized via HTTP2, but nonetheless a network roundtrip)
  2. If file content is unchanged client takes it from cache, otherwise it fetches updated version from Netlify

The relevant cache config AFAIK is max-age=0. Now, I am tempted to change the max-age for my CSS and JS files to something very high, like 604800 or even higher.
I don’t see any downside to this, as my file-content-aware fingerprinting (done by my bundler) should take care of cache invalidation.

Am I missing anything here?

UPDATE: I have now realized that I have asked this exact same question before :grinning_face_with_smiling_eyes:

Thank you for your extensive answer there. Overall, I am still thinking that increasing the max-age for JS and CSS makes sense for me, because cache busting is taken care of by content-aware fingerprinting of my bundler.

1 Like