One of the key features offered by Netlify from the very beginning is the ability to do atomic deploys, which ensure your site is never in an inconsistent state while you’re uploading a new deploy. Atomic deploys are part of what allows developers to focus on what’s important, enabling them to build their website without having to think on what files have changed or what files to update. Netlify achieves this by labelling each cached object with an internal cache ID specific to your site and context, so that a new deploy for that site and context will cause all objects labelled with that ID to be invalidated on Netlify Edge.

Additionally, on October of last year we released cache tags. With cache tags you can specify Cache-Tag or Netlify-Cache-Tag response headers, and then use our purge API to invalidate any object with a given tag from Netlify Edge in between deployments, without having to wait for the object’s lifetime to expire. Cache tags are a great way to invalidate content on-demand without losing the atomic deploy guarantee.

However, sometimes you don’t want your cached content to be invalidated on new deploys. For example, you might have a site proxying to a CMS server with a weekly release cycle. In this case, any deploy happening in between releases will invalidate your cached CMS content and cause Netlify Edge to revalidate it. This can affect performance, increase bandwidth spend, and put unnecessary strain on the CMS server.

Netlify-Cache-ID provides a way to label your cached content across Netlify Edge so it’s persistent across deploys, while still being able to be purged granularly, almost immediately, and globally.

Netlify-Cache-ID

Netlify now supports a Netlify-Cache-ID response header, allowing you to associate an object — or collection of cached objects — to an ID that can be invalidated simultaneously across all of Netlify’s edge network. Objects associated with a Netlify-Cache-ID will not be invalidated when your site is deployed, but you still have the flexibility to decide whether and when they should be cached or not.

Here's an example of a proxied response from a "products API" that will be cached on Netlify Edge for up to one year. The content is identified using Netlify-Cache-ID with productID-1 and products, which allow you to identify your content with different levels of granularity. Netlify Edge will use those values as the cache IDs instead of the internal cache ID, and the content will not be invalidated on a new deploy.

GET /products/productID-1 HTTP/2
Host: your-api.com
...

HTTP/2 200
Content-Type: text/html
CDN-Cache-Control: public, max-age=31536000, must-revalidate // Cache for up to one year on Netlify's Edge
Cache-Control: public, max-age=0, must-revalidate // Tell browsers to always revalidate
Netlify-Cache-ID: productID-1,products // Tag all product responses with these tags

Similarly to Cache-Tag and Netlify-Cache-Tag, content tagged with this header can be purged using Netlify’s purge API. Netlify-Cache-ID values are automatically registered as cache tags that you can use to purge objects by tag. The following function uses the capabilities of Netlify’s Improved Compute and invokes the purge API to purge all the site’s content tagged with products —while leaving the remaining site’s content cached on the CDN.

import { Config, purgeCache } from "@netlify/functions";

export default async () => {
  // set `productID-1` instead to invalidate only a specific product's content
  const tags = ["products"];
  await purgeCache({ tags });

  return new Response("Purged successfully!", { status: 202 });
};

export const config: Config = {
  path: "/purge"
};

Cache-Control directives are still respected so you can customise how long you want your objects to stay cached in case you don’t want to have to purge your content on-demand. Moreover, you can still take advantage of the Cache-Tags feature for added flexibility.

Visit our documentation for more information on how to get started and learn more about how these features work together.

Let us know what you think – head over to the forums and leave us a note.